Javascript API for questionnaires

Avatar
Martijn Brandse
Edited
Follow

Javascript API for questionnaires

This documentation is designed for people familiar with Javascript programming and object-oriented programming concepts. You should also be familiar with questionnaires from a user's point of view. There are many Javascript tutorials available on the web.

This conceptual documentation is designed to let you quickly setup your own questionnaire page with the javascript API. You will learn about how to add a questionnaire page to your website without the use of an iFrame.
This API is available in version 7+ of the resource manager.

Functional concept

Questionnaires can be used for multiple purposes. They can be used as a pre-selection tool. They can also be used to send surveys to candidates and/or customers for example to measure candidate/customer satisfaction.

Questionnaires can be set-up in the Connexys application.  There is a separate article (Questionnaires) that explains you more about the set-up of questionnaires.

Usually you will create a separate page on your website that will contain the questionnaire. With the javascript API you can add the relevant questionnaire to this page.

Table of content

Chapter Content
Hello world
 Helps you get started with the API
Init options Specifications for the different init options
Using the questionnaire for pre-selection Explains you how you can use the questionnaire for pre-selection purposes.
Using the questionnaire as a survey tool Explains you how you can use the questionnaire as a survey tool and how to link the answered questionnaire to the appropriate records in the database.
Adding your own javascript logic to the form Explains you how you can add your own javascript function to events happening on the form.

Before you get started

  1. The page the questionnaire will be placed in must run under HTTPS.
  2. You need the public site URL of your ORG. This URL can be found in the "Setup" menu. Navigate to "Sites". You need the HTTPS site URL.
  3. Setup your salesforce org for the salesforce API

Step 2 and 3 require access to the Connexys application. If you don't have access to the Connexys application, ask your Connexys administrator to do this for you and to send you the public site URL. Also keep in mind that some of the setup of the form is done in the Connexys application. Without access to system you will be able to add the questionnaire to your website, but your Connexys administrator will need to finalize the setup process.

Hello world

The easiest way to start learning about the JavaScript API for questionnaires is to see a simple example.

<html>
    <head>
        <meta charset="UTF-8">        
        <meta name="viewport" content="width=device-width,  initial-scale="1.0">
        <link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle"> 
        <script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
    </head>
    <body>
        <div id="cxsFormHolder"></div>
        <script>
            cxsForm.init({
                target:"#cxsFormHolder",
                server:"https://MyCompany.force.com/",
                questionnaireId: "##here comes the ID##"
            });
        </script>
    </body>
</html>      

 

Even in this simple example, there are a few things to note:

  1. In the head section we set a few meta tags that will ensure that the page will be responsive for mobile devices.
  2. We load the Connexys JavaScript API using a script tag.
  3. We create a div element named "cxsFormHolder" to hold the questionnaire.
  4. We define a JavasScript function that creates a questionnaire in the div.

These steps are explained below.

1) Meta tags

The meta tag charset="utf-8" will make sure that the browser renders characters correctly.

The second meta tag  is used to improve the responsiveness of the page.

2) Load the Connexys Javascript API

To load the Connexys Javascript API, use a script tag like the one in the following example. You must get this script library from the public site URL of your own ORG. So you should replace the "https://MyCompany.force.com/" with your own public site url.

Also notice that we get it from the secure (HTTPS) version of the site. This is also very important.

<head>
    <script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
 </head>

3) Use a HTML container to place the questionnaire in.

For the questionnaire to display on a web page, we must reserve a spot for it. Commonly, we do this by creating a named div element and obtaining a reference to this element in the browser's document object model (DOM).

In the example above, we used CSS to set the height of the cxsFormHolder div to "100%". This will expand to fit the size on mobile devices. You may need to adjust the width and height values based on the browser's screensize and padding. Note that divs usually take their width from their containing element, and empty divs usually have 0 height. For this reason, you must always set a height on the <div> explicitly.

<div id="cxsFormHolder"></div>
4) Initialize the questionnaire
The questionnaire must be initialized to show it on the page. The initialization works with form options. There are two required options for every form: target and server. 
<script>
    cxsForm.init({
        target:"#cxsFormHolder",
        server:"https://MyCompany.force.com/",
        questionnaireId: "##here comes the ID##"
    });
</script>
The example above shows how you can open a pre-defined questionnaire. In practice, this will not be very likely. It will be much more likely that you will use URL parameters to determine which questionnaire will be shown to the user. We will explain that later in this help file.

5) Add jQuery to the page

Optionally add jQuery to the page. If the page has no jQuery library available it will add jQuery v1.10.2 from your org.

6) Add styling to the page

You will want to add your own style to the questionnaire using CSS. To give you a headstart on this you can optionally use one of our premade style. Simply include one of these lines to the head of your page, either as an example or as a start to build your own CSS upon.

Responsive styling based on Bootstrap:
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle">

Basic styling:
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyleBasic">

Init options

Required parameters

Option Type Explanation
target String

The HTML container the questionnaire will be placed in. Usually the ID of a DIV that will hold the questionnaire. In case of multiple results we will add the form to the first element.

<script>
    cxsForm.init({
        target:"#cxsFormHolder",
        server:"https://MyCompany.force.com/"

    });
</script>

Example: "#cxsFormHolder"
server String

The public site URL of your ORG. This URL can be found in the "Setup" menu. Navigate to "Sites". You need the HTTPS site URL. (including the "/" at the end of the URL.

Example: "https://MyCompany.force.com/"

Using the questionnaire for pre-selection

Often, you will use the questionnaire for pre-selection purposes. After the candidate submits the application form, you will ask the candidate to fill in a questionnaire. In this case the questionnaire needs two different parameters:

  • jobAppId (the 15 digit ID of the job application submitted by the candidate) You would normally get this ID back from the application form that was submitted by the candidate.
  • questionnaireId (the 15 digit ID of the questionnaire that must be filled in by the candidate) You would normally get this ID back from the application form that was submitted by the candidate.

The way you can get these parameters back from the application form is to add a custom "onAfterSubmit" handler to the application form. Consult the "Application form API" documentation on how to do that.

So, the onAfterSubmit handler on the application form will specify the right questionnaire and jobApp ID for you. In case a questionnaire ID is specified, you should forward the candidate to the questionnaire page and open the right questionnaire on this page. You can either specify the ID's in the INIT options of the questionnaire page.  

<script>
    cxsForm.init({
        target:"#cxsFormHolder",
        server:"https://MyCompany.force.com/",
        questionnaireId: "##here comes the 15 digit ID##",
        jobAppId: "##here comes the 15 digit ID##",
    });
</script>

Or you can use URL parameters to open the right questionnaire on the page. This would probably be the easiest way to do this. 

function myDoneFunction(isSuccess, results) {
    if(isSuccess && results.questionnaireId != null && results.applicationId != null) {
        var jobAppId = results.applicationId;
        var questionnaireId = results.questionnaireId;
        document.location = 'https://www.mywebsite.com/questionnairePage?questionnaireId='+questionnaireId+'&jobAppId='+jobAppId;
    }
}

 

Using the questionnaire as a survey tool

It is also possible to use the questionnaire as a survey tool. In this case the Connexys application will send out questionnaires to candidates and or customers. The results of the survey (the answered questionnaires) must be saved to the database and you will probably want the answered questionnaire to be linked to the right candidate or contact.

In case you want to send out a survey to a customer about a job that was filled by a candidate, you would probably want the answered questionnaire to be linked to the following records.

  • Customer
  • Candidate
  • Job

The following parameters can be specified in the URL (or in the init options) to link the answered questionnaire to the appropriate records in the database.

Option Type Explanation
jobAppId String

The ID of the job application.
contactId String The ID of the contact record (usually the customer)
jobId String The ID of the job.
accountId String The ID of the account.
candidateId String The ID of the candidate.
campusEventId String The ID of the camous event.
custom lookup fields on Answered Questionnaire object String

This one is only working with URL parameters

Use the field name of the lookup field on the Answered questionnaire object as the URL parameter name and the ID as the value. For example:

if you have a custom object with API name = "custom_object__c" and a lookup field on the answered questionnaire object with the API name called "custom_field__c", the right URL parameter is then: custom_field__c=a1k24000000LNRU

This can be used in version 9 and higher.

 

Adding your own javascript logic to the form

We allow you to add your own javascript functions to some events that can happen on the form. It works with callback parameters. These parameters refer to a custom javascript function on your page. These functions can be used to perform changes to the HTML of the page, giving you more control over what is happening on the page.

You can add callback functions to the following events:

Option Format Explanation
onInit function(Boolean firstTime)

This callback function is called each time the form is rendered or rerendered.

The function will be called with 1 parameter:

  • Boolean : true if this is the first time the form is rendered, otherwise false.

Example code

<script>
    cxsForm.init({
        target:"#cxsFormHolder",
        server:"<< Site url of your salesforce org. >>",
        onInit: MyInit
    });
</script>
onlanguageSwitch function(String languageCode)

Triggers just before the form language is switched. (the onInit will trigger once the form is rerendered in the new language).

The function will be called with 1 parameter:

  • String : Code of the new language (see above for the format of the language codes)

Example code

<script>
    cxsForm.init({
        target:"#cxsFormHolder",
        server:"<< Site url of your salesforce org. >>",
        onlanguageSwitch: MyLanguageSwitch
    });
</script>
onBeforeSubmit Function(JsonString formData) Triggers just before the form is submitted to the server.
The function will be called with 1 parameter:
  • JsonString : The form data that will be submitted to the server.

Example code

<script>
    cxsForm.init({
        target:"#cxsFormHolder",
        server:"<< Site url of your salesforce org. >>",
        onBeforeSubmit : MyBeforeSubmit
    });
</script>
onAfterSubmit Function(Boolean succesful, JsonString) Triggers when the server has responded to the form submit. The function will be called with 2 parameters:
  • Boolean : true if the submit was successfully saved, otherwise false.
  • JsonString : The format of this json string depends on the result. In case of success the json will contain candidateId, jobId, eventId, formId, mediaChannelId, questionnaireId, applicationId.


The server can return either "error" in the case of required field not being available, or "errors" in the case that a server error is triggered while saving to salesforce (for instance caused by custom field checks on the server).
Examples:
{ "error": "<errorLabel>", "fields": ["<field Key>"]}

{ "errors":[{"statusCode":"<error code>","message":"<error message>","fields":["<field name>"]}],"objectName":"<object name>"}

Example code

<script>
    cxsForm.init({
        target:"#cxsFormHolder",
        server:"<< Site url of your salesforce org. >>",
        onAfterSubmit : MyAfterSubmit
    });
</script>

NOTE: If your custom function return false the normal error and success handling won't be executed. (In case of success this can be used to not show a thank you message on the page but do a redirect to another page instead.).

 

 

Powered by Zendesk