Hi Cheri,

You would likely need to use the Import Participant API endpoint to have these ad-hoc participant requests completed in real-time from a survey/form.

api.qualtrics.com/0817d51eb695b-import-participants

There could potentially be the following flow:

• HR team member submits Qualtrics survey that includes the details of the terminated employee
• Qualtrics workflow is configured to run upon survey submission that does the following two tasks:
  • WebService task: Imports the required participant into the exit survey project via API call
  • Email task: Distributes survey invite to the required participant

Thanks, I’ll check this out.

​@CheriV Out of curiosity, would the process be prone to human error as a human has to enter an Employee ID? (no chance of validation etc)

Hi ​@bench - To limit this issue, I would use an additional API call first to verify that the unique ID entered matches an existing participant in the directory. See the call below.

Step 1: Validate that the entered unique ID exists as a participant in the directory - api.qualtrics.com/9632f75da9159-get-all-participants-post

Step 2: If participant is found/exists, import the participant into the required survey project - api.qualtrics.com/0817d51eb695b-import-participants

This potentially introduces a lot of complexity, no? Do you have a good example for this?

I see why you would do this, I tried something similar, but eventually gave up as it was a project with hundreds of participants and the API returned 100 results at most, meaning I would need to call it again and again until I reach the very end.

I did not manage to loop this part of the workflow, tried to do looped API call in the code, just to find out I am not allowed to call API from the code.

It would be great to know if there is a way around this.

It does have the potential for human error.  However, no more than how we currently bring the participant into the survey.  I currently receive a notification from a Microsoft Forms entry made by the HR Manager with the Employee ID and Employee Name and then add the employee as a participant to the survey from the Employee Directory.  Each employee does have a unique Employee ID number.

Hi ​@CheriV, I’ve put together a prototype of how this design would look.

Create intake form survey project.

1. The survey will ask for the employee ID of the person who should be added as a participant/receive the invite.
2. The survey flow will run the Get All Participants api call to search for the employee ID entered by the user (api.qualtrics.com/9632f75da9159-get-all-participants-post).
3. If a participant is found (which is defined by a user ID being returned from the api call above), then display the name and email of the employee to the user. User can click submit to distribute survey.
4. If a participant is not found, then let them know that the ID did not match an existing employee and they can try to search again.

Then to actually import the participant into the exit survey project and distribute an email invite, you can run a workflow off of the survey to run this process.

Import Participant and Send Email Invite

1. Create workflow to run when a survey response is recorded on the intake survey.
2. Set a condition to only run the workflow if a participant was found in the search (which is defined by a user ID being returned from the api call above).
3. Run a WebService task to call the Import Participants api endpoint and insert the participant into the lifecycle project (api.qualtrics.com/0817d51eb695b-import-participants).
4. Run an email task to send a survey link to the participant.

Hi Roman. This design/use case is for individually adding one single employee at a time. Both API endpoints I’ve discussed in the design support searching/importing individual participants so looping through would not be necessary. As long as the search for validation is using the unique identifier, there should be a maximum of one participant returned so no looping would be necessary.

Hi ​@CheriV, I’ve put together a prototype of how this design would look.

 

Create intake form survey project.

1. The survey will ask for the employee ID of the person who should be added as a participant/receive the invite.
2. The survey flow will run the Get All Participants api call to search for the employee ID entered by the user (api.qualtrics.com/9632f75da9159-get-all-participants-post).
3. If a participant is found (which is defined by a user ID being returned from the api call above), then display the name and email of the employee to the user. User can click submit to distribute survey.
4. If a participant is not found, then let them know that the ID did not match an existing employee and they can try to search again.

 

 

Then to actually import the participant into the exit survey project and distribute an email invite, you can run a workflow off of the survey to run this process.

 

Import Participant and Send Email Invite

1. Create workflow to run when a survey response is recorded on the intake survey.
2. Set a condition to only run the workflow if a participant was found in the search (which is defined by a user ID being returned from the api call above).
3. Run a WebService task to call the Import Participants api endpoint and insert the participant into the lifecycle project (api.qualtrics.com/0817d51eb695b-import-participants).
4. Run an email task to send a survey link to the participant.

 

 

Hi Jake,

Just to confirm, is it possible for us to build this through a workflow without the help from Qualtrics technical team?  

Hi Cheri, yes this can be done without the Qualtrics technical team’s support. I was able to do the same.

Thanks Jake

Hi Cheri,

I’ll try to be more specific in the instructions below, but please use the screenshots I sent previously as a guide to exactly how it should look.

1. Create survey intake form question
   1. Create a new regular/core survey project (non-lifecycle)
   2. In the 1st question block, make the first question an open text question requesting the user to enter the employee ID of the person who should be added as a participant/receive the invite.
      1. Example: “Enter the employee ID of the employee that should be sent the survey.”
   3. Create a 2nd question block with one text/graphic display question that shows the information to display if a valid employee ID was entered.
      1. Example:
         1. First Name: ${e://Field/participants.0.firstName}
            Last Name: ${e://Field/participants.0.lastName}
            Email: ${e://Field/participants.0.email}
            
            Click "submit" to distribute the survey to this employee.
   4. Create a 3rd question block with one text/graphic display question that shows the information to display if an invalid employee ID was entered.
      1. Example:
         1. The employee ID entered (${q://QID1/ChoiceTextEntryValue}) did not match to an existing employee in the Qualtrics Directory. Please try refresh the page and search a new employee ID.
2. Setup survey flow with participant search/validation functionality
   1. Open the “survey flow” which is the 2nd tab on the top left of the survey builder.
   2. Insert a new “web service” element under the “Show block” element
      1.  URL: https://syd1.qualtrics.com/API/v3/employee-directories/ex/participants?includeMetadata=true
         1. While my datacenter ID is “syd1” in the URL above, you can swap out the datacenter ID with your datacenter ID by going to your user settings.
      2. Method: POST
      3. Body Parameters (application/json): uniqueIdentifier = ${q://QID1/ChoiceTextEntryValue} (String)
      4. Custom Headers: [Insert your API token which can be found by going to your user settings].
      5. Set the following embedded data:
         1. participants.0.firstName
         2. participants.0.lastName
         3. participants.0.email
         4. participants.0.username
         5. participants.0.userId
         6. participants.0.participantId
   3. Add a new Branch If element to the survey flow under the web service element.
      1. Add criteria to only run the branch if Embedded data field “participants.0.userId” is Not Empty (this means that the Employee ID was valid and found in the Directory).
      2. Nest survey question block #2 within the branch.
   4. Add a new Branch If element to the survey flow under the web service element.
      1. Add criteria to only run the branch if Embedded data field “participants.0.userId” is Empty (this means that the Employee ID was invalid and not found in the Directory).
      2. Nest survey question block #3 within the branch.
3. .Create workflow to add participant to Exit Survey project
   1. Go to the “Workflows” tab at the top of the intake form project.
   2. Create a new workflow with a trigger of a survey response.
   3. Add a decision/criteria to continue the workflow if embedded data “participants.0.userId” is not empty (so that the workflow only runs if the employee ID was valid).
   4. Add a WebService task under the decision with the following configuration:
      1. Request Type: POST
      2. URL: https://syd1.qualtrics.com/API/v3/ex-projects/TS_XXXXXX/import-participants
         1. While my datacenter ID is “syd1” in the URL above, you can swap out the datacenter ID with your datacenter ID by going to your user settings.
         2. You will need to swap out the project ID (TS_XXXXXX) with the project ID of your Exit survey, which can be found by going to the survey project and copying it from the URL.
      3. Headers
         1. Content-Type = application/json
         2. accept = application/json, multipart/form-data
         3. x-api-token = [Insert your API token which can be found by going to your user settings]
      4. Body

         1. {
              "participants": [
                {
                  "firstName": "${e://Field/participants.0.firstName}",
                  "lastName": "${e://Field/participants.0.lastName}",
                  "email": "${e://Field/participants.0.email}",
                  "uniqueIdentifier": "${q://QID1/ChoiceTextEntryValue}"
                  }
              ]
            }

      5. Save your WebService task.
   5. Create an Email task under the WebsService task with the following configuration:
      1. To field: ${e://Field/participants.0.email}
      2. Enter the From name/email/subject however is required for your program.
      3. In the message, include the anonymous survey link for your survey program (assuming your survey is accessed by employees via SSO).
      4. Save your email task.
   6. Enable your workflow by turning it on in the top right.
   7. Test that the solution works by completing a survey response with a valid employee ID. Check the “run history” of the workflow to see if it was triggered successfully.

Thanks for providing this.  I’ve set it up, but I’m consistently getting the Employee Not Found response while testing.  I’m not sure what could be wrong.  

Hi Cheri,

If you use the Test button, it will use whatever value is currently in the right side of the parameter (which is currently set to ${q://QID1/ChoiceTextEntryValue}). You can instead type in a valid employee ID in that box to use the Test button. If that returns real data from your EX directory, then you know the webservice call is working!

You can make sure you are entering a real employee ID by opening any employee in your EX directory and entering the value in the “Unique Identifier” field.

You will need to revert back to ${q://QID1/ChoiceTextEntryValue} once you validate that the webservice call is working so that it works correctly when you run this via a survey response.

Actually, I see your issue. You need to make sure to set the left side of the embedded data field within the webservice element. You can copy and paste the exact same values that are on the right side.  See my screenshot from earlier for an example, but the screenshot below which you provided is missing the left side of the embedded data that labels the fields.

Current setup which is incorrect

 

Thanks for providing this.  I’ve set it up, but I’m consistently getting the Employee Not Found response while testing.  I’m not sure what could be wrong.  

 

Hi Cheri,

 

If you use the Test button, it will use whatever value is currently in the right side of the parameter (which is currently set to ${q://QID1/ChoiceTextEntryValue}). You can instead type in a valid employee ID in that box to use the Test button. If that returns real data from your EX directory, then you know the webservice call is working!

 

You can make sure you are entering a real employee ID by opening any employee in your EX directory and entering the value in the “Unique Identifier” field.

 

You will need to revert back to ${q://QID1/ChoiceTextEntryValue} once you validate that the webservice call is working so that it works correctly when you run this via a survey response.

 

Actually, I see your issue. You need to make sure to set the left side of the embedded data field within the webservice element. You can copy and paste the exact same values that are on the right side.  See my screenshot from earlier for an example, but the screenshot below which you provided is missing the left side of the embedded data that labels the fields.

 

Current setup which is incorrect

 

Ok, I missed those left side values.  They are now set.  However, when using an actual employee ID I’m still getting the Employee Not Found response.  :/

Hi Cheri,

It looks like you entered the left side of the body parameter incorrectly. It should be spelled (case-sensitive) exactly as “uniqueIdentifier”.

Once you make that change, you can test within the survey flow by typing in a valid employee ID in the right side of the body parameter and clicking the “Test” button. You would then want to revert back to the piped text field once you confirm it is working.

If you still face issues, please send a screenshot of the error you are facing within the “Test” button.

I fixed the body parameter and changed the text to an Employe ID I get this error:

I really appreciate your help!

I fixed the body parameter and changed the text to an Employe ID I get this error:

I really appreciate your help!

It looks like your URL you entered does not match what I gave. Make sure to add the full/entire URL. I’ve updated to your datacenter.

https://yul1.qualtrics.com/API/v3/employee-directories/ex/participants?includeMetadata=true

I fixed the body parameter and changed the text to an Employe ID I get this error:

I really appreciate your help!

 

It looks like your URL you entered does not match what I gave. Make sure to add the full/entire URL. I’ve updated to your datacenter.

 

https://yul1.qualtrics.com/API/v3/employee-directories/ex/participants?includeMetadata=true

Ok, I fixed that, and tested the webservice it worked!!

BUT… when I actually take the survey and test with the same EE ID, it says it does not match an existing employee. 

I fixed the body parameter and changed the text to an Employe ID I get this error:

I really appreciate your help!

 

It looks like your URL you entered does not match what I gave. Make sure to add the full/entire URL. I’ve updated to your datacenter.

 

https://yul1.qualtrics.com/API/v3/employee-directories/ex/participants?includeMetadata=true

 

Ok, I fixed that, and tested the webservice it worked!!

BUT… when I actually take the survey and test with the same EE ID, it says it does not match an existing employee. 

 

Here’s how the search results window is set up… maybe I have that wrong?  

Glad that worked! I think your last issue is that your ED fields are not spelled correctly. You need to copy and paste exactly as I documented them with the same capitalizations. For example, it’s firstName not firstname, and userId not userid.

• Set the following embedded data:
  1. participants.0.firstName
  2. participants.0.lastName
  3. participants.0.email
  4. participants.0.username
  5. participants.0.userId
  6. participants.0.participantId

All corrected.  Still same result (Did Not Match Existing Employee)

 

All corrected.  Still same result (Did Not Match Existing Employee)

 

Make sure your branching logic under the webservice also uses the same updated embedded data field name (participants.0.userId).

 

All corrected.  Still same result (Did Not Match Existing Employee)

 

Make sure your branching logic under the webservice also uses the same updated embedded data field name (participants.0.userId).

Yes!!  Just corrected that and that worked.  Now troubleshooting the workflow.  :)