This documentation is designed to let you setup your own application form page with the Javascript API to be prefilled with social media and document providers. You will learn how to use the TextKernel Sourcebox Widgets for this purpose.
This documentation is designed for people familiar with Javascript programming and object-oriented programming concepts. There are many Javascript tutorials available on the web. You should also be familiar with TextKernel Sourcebox Widgets and the concept of starting a job application from social media or a document provider delivering a CV. You should also have contact with TextKernel about using their product for this purpose.
More information about the Application form API can be found in the following articles: Application Form API and Application Form API Advanced features
This API is available in version 7+ of the resource manager.
Before you get started
In order to use the Sourcebox Widgets, you need to have an account configured at TextKernel, of this account you will need the hostname and the token. If you want to automatically upload CVs to the application form, you will also need the account, username and password from TextKernel. TextKernel has documentation to help aquire API keys for all social media and storage providers. Most configuration is stored in the TextKernel Sourcebox settings. Only the Google gapiClientId and Dropbox app key are need to be placed in your page.
Functional concept
To ease the job appication of a candidate, the Application Form API supports prefilling the application form from external sources. This can either be social media, e.g.: LinkedIn, Facebook and Xing. Or this can be document providers, in e.g.: Dropbox and directly from the candidate's harddrive.
If only upload from the local harddrive needs to be supported, this can be done by using only configuration in Connexys, and no Sourcebox implementatie is required.
In the example below, both the Widgets and the form are placed in the same page. Splitting this in two seperate pages might be preferable for a production implementation. In which case it is also possible to place the widgets directly into the job listing or a job page.
Contents
| Chapter | Content |
| Hello world | Helps you get started with the API by showing a minimal working version |
| Adding a CV Document | How to automatically fill the CV from file upload or other sources |
| Complete example | Shows a more eleborate example, showing off a lot of different common use cases |
| Calling the test form | Instructions on calling the test page which is part of the managed package |
The example below shows a minimal working version of the concept. First the candidate must click on the LinkedIn widget. After the candidate grants access to LinkedIn, the candidates first name will be prefilled in the following form.
A lot of the basic flow code is already in place in the first example, as this is needed for a minimal working example. First we will show the whole example. After this example a step by step explanation is shown.
<html>
<head>
<script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
</head>
<body>
<pre id="response" style="display:none">TK_RESULT</pre>
<div id="tkSourceBoxHolder" style="display:none">
<div id="tk_linkedin" class="TK_WIDGET" rel="linkedin" desc="LinkedIn"></div>
</div> <div id="cxsFormHolder" style="display:none">
Loading form...
</div>
<script src="//home.textkernel.nl/sourcebox/js/tkwidget.js" type="text/javascript">
TK.CONFIG = {
"token": "tk_token",
"hostname": "tk_hostname",
"redirectOnError": window.location.href ,
"postProfileUrl": window.location.href
}
</script>
<script>
jQuery(document).ready( function() {
var hasProfile = jQuery('#response profile').length == true;
if(!hasProfile) {
jQuery('#tkSourceBoxHolder').css('display', 'block');
}
else {
initCxsForm();
}
});
function initCxsForm() {
jQuery('#tkSourceBoxHolder').css('display', 'none');
jQuery('#cxsFormHolder').css('display', 'block');
cxsForm.init({
target:"#cxsFormHolder",
server:"https://MyCompany.force.com/",
onInit:fillFormWithData
});
}
function fillFormWithData() {
if(jQuery('#response profile').length > 0) {
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__First_name__c', jQuery('#response firstname').html());
}
}
</script>
</body>
</html>
Explanation for each part
Head
<head>
<script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
</head>
First we load the Application Form API javascript and css resources. Replace the https://MyCompany.force.com with own public site url. How to obtain this url is explained in the https://help.connexys.com/hc/en-us/articles/209210905-Application-Form-API arcticle.
We also load jquery, to use in our example. This is not required, the places where jquery is used in this example can be replaced by plain javascript or any other simular tool.
TK_RESULT
<pre id="response" style="display:none">TK_RESULT</pre>
In this first hidden section we load the post parameter which Sourcebox send back with the profile of the candidate. In this example, replace the "TK_RESULT" text with the "TK_RESULT" post parameter received back from TextKernel. We have done this to save us the trouble from writing server code which should parse the TextKernel profile and pass only the required information back to the client browser.
For example in PHP you can set the TK_RESULT like this
<pre id="response" style="display:none">
<?php if(isset($_POST['TK_RESULT'])) {echo $_POST['TK_RESULT']; } ?>
</pre>
tkSourceBoxHolder
<div id="tkSourceBoxHolder" style="display:none">
<div id="tk_linkedin" class="TK_WIDGET" rel="linkedin" desc="LinkedIn"></div>
</div>
This is the holder in which all the the widgets can be placed, at this moment it only holds LinkedIn, in later examples we will add more widgets.
<script src="//home.textkernel.nl/sourcebox/js/tkwidget.js" type="text/javascript">
TK.CONFIG = {
"token": "tk_token",
"hostname": "tk_hostname",
"redirectOnError": window.location.href ,
"postProfileUrl": window.location.href
}
</script>
TextKernel library configuration
The TextKernel library include and configuration. Replace tk_token and tk_hostname with your Sourcebox token and hostname respectively. These values are provided by TextKernel
jQuery(document).ready( function() {
var hasProfile = jQuery('#response profile').length == true;
if(!hasProfile) {
jQuery('#tkSourceBoxHolder').css('display', 'block');
}
else {
initCxsForm();
}
});
initCxsForm
This is the jQuery onload method, which will check if we came back from Sourcebox, or if we visit the page for the first time. It will show the Sourcebox widgets or Connexys form accordingly.
function initCxsForm() {
jQuery('#tkSourceBoxHolder').css('display', 'none');
jQuery('#cxsFormHolder').css('display', 'block');
cxsForm.init({
target:"#cxsFormHolder",
server:"https://MyCompany.force.com/",
onInit:fillFormWithData
});
}
fillFormWithData
Show the Connexys form and hide the Widgets. Also initialize the form. Replace https://MyCompany.force.com/ with your own public site url, as described above. Note the onInit method here, which will can fillFormWithData method when the form has been initialized and rendered in the browser.
function fillFormWithData() {
if(jQuery('#response profile').length > 0) {
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__First_name__c', jQuery('#response firstname').html());
}
}
If we a response back with profile data, fill the candidate’s first name with the first name of the response. Which name to use as the first parameter for the setFieldValue can be found in by inspecting the page with for example the Chrome DevTools.
To add a CV document to the form data, we need to set the textkernel document url to:
tk_hostname/downloadDocument?trxmlid=
with the trxmlid appended. Replace the tk_hostname with your textkernel hostname.
This can be, for example: "https://home.textkernel.nl/connexys"
This Sourcebox hostname must also be configured in the form definition which is used. in the Connexys Resource Manager Setup.
This form definition also needs to have a Sourcebox account, username and password specified, to make the automatic document upload work.
var trxmlId = $('#response trxmlid').html();
if(trxmlId) {
var docUrl = 'tk_hostname/downloadDocument?trxmlid='+trxmlId;
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Last_CV__c', docUrl);
}
A complete example of the functionality is shown below, this example has:
- Error handling on errors from TextKernel.
- Added skip, Xing, Facebook, Google Drive, Dropbox and local harddisk upload.
- Filling a lot more field
- Including date field
- And linking the CV document when we got it from the Sourcebox.
- A lot of comment lines, describing functionality.
Some new placeholders are introduced, but these work in the same manner as the placeholders in the hello world example.
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Connexys Apply Form Example page</title>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle"/>
</head>
<body>
<!-- replace TK_RESULT below with the TK_RESULT post parameter received back from TextKernel -->
<pre id="response" style="display:none">TK_RESULT</pre>
<div id="tkSourceBoxHolder" style="display:none">
<h1>TextKernel SourceBox example</h1>
<a href="javascript:initCxsForm()">Skip to form</a> without prefilling
<h2>Apply using social media</h2>
<div id="tk_xing" class="TK_WIDGET" rel="xing" desc="XING"></div>
<div id="tk_facebook" class="TK_WIDGET" rel="facebook" desc="Facebook"></div>
<div id="tk_linkedin" class="TK_WIDGET" rel="linkedin" desc="LinkedIn"></div>
<h2>Apply using CV document</h2>
<div id="tk_dropbox" class="TK_WIDGET" rel="dropbox" desc="Dropbox"></div>
<div id="tk_googledrive" class="TK_WIDGET" rel="googledrive" desc="Google Drive"></div>
<div id="tk_cv" class="TK_WIDGET" rel="cv" desc="Local Harddisk"></div>
</div>
<div id="cxsFormHolder" style="display:none">
Loading...
</div>
<script src="//home.textkernel.nl/sourcebox/js/tkwidget.js" type="text/javascript">
// Initialize TextKernel SourceBox with your own tk_token, tk_hostname and google api id (gapiClientId).
// See the SourceBox documentation for more information
// The gapiClientId below is needed to get google drive to work
TK.CONFIG = {
"token": "tk_token",
"hostname": "tk_hostname",
"redirectOnError": window.location.href ,
"postProfileUrl": window.location.href ,
"gapiClientId":"gapiClientId"
}
</script>
<!-- All three script blocks below are needed to get google drive to work, see the sourcebox documentation -->
<script src="https://apis.google.com/js/client.js?onload=onGapiLoad" type="text/javascript"></script>
<script src="https://www.google.com/jsapi" type="text/javascript"></script>
<script type="text/javascript">
google.load('picker', '1');
</script>
<!-- The code below is required for DropBox, replace dropBoxAppKey with your app key from DropBox -->
<script data-app-key="dropBoxAppKey" id="dropboxjs" src="https://www.dropbox.com/static/api/2/dropins.js" type="text/javascript"></script>
<script>
jQuery(document).ready( function() {
// check for textkernel error and if found show an error message to the candidate
// replace with the TK_ERROR_MESSAGE parameter from Sourcebox
var tkError = 'TK_ERROR_MESSAGE';
if(tkError != '') {
alert('TextKernel Error:'+tkError);
}
// check if we got a response back from TextKernel SourceBox
var hasProfile = jQuery('#response profile').length == true;
// if we have not made the roundtrip to SourceBox, show the SourceBox buttons.
if(!hasProfile) {
jQuery('#tkSourceBoxHolder').css('display', 'block');
}
// if we have made the reoundtrip to SourceBox, initialize our Connexys form.
else {
initCxsForm();
}
});
// Show and initialize the Connexys form
function initCxsForm() {
jQuery('#tkSourceBoxHolder').css('display', 'none');
jQuery('#cxsFormHolder').css('display', 'block');
cxsForm.init({
target:"#cxsFormHolder",
server:"https://MyCompany.force.com/",
onInit:fillFormWithData
});
}
// this function is called every time after the form is initialized, as defined in the
// cxsForm.init above.
function fillFormWithData() {
if(jQuery('#response profile').length > 0) {
// fill some fields from the SourceBox response into the Connexys form
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__First_name__c', jQuery('#response firstname').html());
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Initials__c', jQuery('#response initials').html());
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Last_name_prefix__c', jQuery('#response lastnameprefix').html());
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Last_name__c', jQuery('#response lastname').html());
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Town_city__c', jQuery('#response deliveryaddress municipality').html());
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Address_line_1__c', jQuery('#response deliveryaddress streetname').html());
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__E_mail_address__c', jQuery('#response emailaddress').html());
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Country__c', jQuery('#response deliveryaddress country').html());
// the date of birth is a little bit more complex, because we need to transform the format.
// transform the dd-MM-yyyy format given back from SourceBox to the expected yyyy-MM-dd by cxsForm
var birthDate = jQuery('#response dateofbirth').html();
if(birthDate != null && birthDate != '') {
birthDate = birthDate.split('-');
birthDate = birthDate[2]+'-'+birthDate[1]+'-'+birthDate[0];
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Date_of_birth__c', birthDate);
}
// upload the CV as document for this candidate
// Note, the tk_hostname, tk_account, tk_username and tk_password for Sourcebox should
// should be configured on the used form in de connexys settings
// the hostname configured, should match the hostname in the lines below.
var trxmlId = jQuery('#response trxmlid').html();
if(trxmlId) {
var docUrl = 'tk_hostname/downloadDocument?trxmlid='+trxmlId;
cxsForm.setFieldValue('cxsrec__cxsCandidate__c.cxsrec__Last_CV__c', docUrl);
}
}
}
</script>
</body>
</html>
In our package we have included a test form. Make sure the step in the Setup Saleforce server instance for use with Javascript Application Form article have been followed. Also add the cxsApplyFormExampleSourceBox page to your site and then navigate in a browser to this page and replace the capitalized placeholders with the correct values:
https://MyCompany.force.com/cxsApplyFormExampleSourceBox?tk_token=TK_TOKEN&tk_account=TK_ACCOUNT&tk_username=TK_USERNAME&tk_password=TK_PASSWORD&tk_hostname=TK_HOSTNAME&gapiClientId=GAPI_CLIENT_ID&dropBoxAppKey=DROPBOX_APP_KEY
!Note for connexys employees a filled url with a working example configuration can be found in the Sourcebox example for the Application Form API article.