Decipher QualLink Instructions

Overview

This setup is used to check QualLink if a user with a given email exists. If not, then an account associated with said email is created and a temporary password is created and e-mailed to the user/respondent. We gather PII information such as First/Last name and email address within Decipher and use that information through an API integration with QualLink to realize the setup.

Required Data Fields

Program your survey as usual, but make sure a PII collection question is added to the survey, that would specifically require the below information from each respondent:

• First name
• Last name
• Email address 

This information is needed to check for an existing user, or otherwise register a user account for the respondent. Without it, the QualLink integration will not be possible.

QualLink Settings

The following fields are available to pass through information to QualLink:

• Email (required) – Respondent email. Must be a valid email. Eg. john.doe@example.com
• FirstName – Respondent’s first name.
• LastName – Respondent’s last name.
• DisplayName (required) – Display name for the new user (i.e. username).
• ApiKey – The API key provided from Qual Link for this job.
• SetTempPassword – Boolean value (1 – True; 0 - False). Whether a temporary password should be generated if this is a new user.
• ResponseFormat – Boolean value (1 – True; 0 - False).
• LanguageCode – Language code for the new user. Must be a valid BCP 47 language tag. (eg. en-GB, es).
• EventId – The Event ID from Qual Link for this job.
• GroupTags – Groups to add the new user to. A comma separated list of strings, that would act as filter tags that each respondent should be assigned to. On Qual Link’s side, passed group tags will be created if they do not exist. Can be left empty, if unused.

Decipher Settings

Decipher integration is handled through the platform’s API Integration element – this is referred to as a <logic> tag, that has predefined attributes, which are used to pass the necessary information to QualLink.

 More on information on the <logic> tag and its setup can be found under Decipher’s KB article:
https://forstasurveys.zendesk.com/hc/en-us/articles/4409461436827-Generic-API-Call

API Integration <logic> tag attributes are as follows:

• label (required) – As any Decipher element, a unique label needs to be set.
• api:data – The information we need to pass through the API call. This would be the fields defined in the previous step, though it the data needs to be formatted in a specific way in order to be correctly passed through.
• api:headers (optional) – It allows you to pass through custom headers for your call. In this case however, we need to pass through the content type and API key through here.
• api:params (optional) – It is the name of a variable that contains the URL parameters and must be a dictionary. In this case, we will be passing through data definition information.
• api:url (required)  – The base URL to access (in our case - https://api.qualboard.com/api/v4/users/import). The hostname must exist in the api.txt file located in the company directory (selfserve/XXX) or be white-listed within the api.1 logic node.
• api:method (required) – This attribute specifies the call method. It can be set to GET (default), POST, DELETE, or PUT. We will be using “GET” in this setup.
• uses (required) – This should always be “api.1”. It is a defined key within Decipher, denoting the type of <logic> tag we use.
   

Decipher Survey Integration

Now that we have defined what can be passed to QualLink as information and what Decipher’s API Integration element uses to do it, the below setup can be directly referenced or used in order to set this up within any Decipher survey (just be sure to replace any information on per need basis):

1) Formatting the survey data in a matter that we can pass it through to QualLink

We store all the QualLink fields and their associated information (as well as any survey data we will pass) within a hidden variable within the Decipher survey, since we need to format the entire thing as a dictionary, that we will later pass through the API integration <logic> tag element. Add the below hidden question at the end of your survey, replacing the bold and underlined red font text with the relevant information (i.e. the collected PII, API key, Event ID and /if needed/ group tags):

2) Passing the Decipher formatted data to QualLink

We have stored the information in its proper format within the hidden QUALBOARD_DATA variable. Now we need to funnel that data through the API Integration <logic> tag. Add the below logic tag, after the hidden QUALBOARD_DATA variable:

3) Reading QualLink Response

The above <logic> tag sends the necessary information to QualLink and with our GET method, we expect a response from their server, that would denote if this were a new user or not. If the user is new, we’d also receive the temporary password, which we need to supply to the respondent. We use the below hidden variable (added after the QualBoard <logic> tag) to capture the QualLink response, so we can further use that information to finish the setup:

4) Sending the account information e-mail to the respondent/user

We have passed the necessary information to QualLink, we have gotten and stored their response. Now we need to actually use that response and decide whether an email should be sent to the respondent or not. If they are a new user, then we’d have to send an email with their temporary password and login instructions.
 
 This would be handled through another <logic> tag.
 
 We create a “resource” <res> tag, that would hold the PII data we will send over email.
 We create a “pipe” <pipe> tag, that hold would show the user’s temporary password.

Relevant company information is then added to the e-mail <logic> tag:

• company – The sender company. In this case – Qualtrics.
• content – The body of the email. The information we added to the <res> tag.
• recipient – The user we are sending the email to. Here we need to reference the email the respondent provided within the PII collection question.
• sender – The email of the sender company. In this case, support@qualboard.com.
• subject – The subject of this email.

 
 Add the below <res>, <pipe> and <logic> tags, after the QUALBOARD_RESPONSE hidden variable.

With this, the setup is complete though it is strongly recommended it is thoroughly tested with active emails so that the entire process can be reviewed.
 
 If needed, the below Decipher DEMO project can be referenced as both setup, code and general overview:
 https://schlesinger.focusvision.com/apps/portal/#/projects/detail/selfserve/1819/g0db/230329

For further documentation visit:
 https://qb4.qualboard.com/docs/v4/

If you have any questions or need assistance, please email support@qualboard.com.