Adding participants to a lifecycle project from a workflow
I’m fairly new to Qualtrics and hoping maybe someone else has done something similar. Is it possible to add a participant to a lifecycle project via a workflow from another source/ Qualtrics survey/ form? Can someone provide detailed instructions in order to do so?
Trying to build a workflow that would work something like the following:
HR Manager enters an Employee ID # via Microsoft form or Qualtrics survey notifying of employee intent to term
Workflow immediately picks up Employee ID# from the form or survey and matches to Employee Directory (employees are already populated and do not need to be added)
Participant is added to Termination survey (survey set up to email the participant as soon as added) in order to capture their feedback before last day of employment.
Page 1 / 2
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.
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.
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.
@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)
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.
The survey will ask for the employee ID of the person who should be added as a participant/receive the invite.
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.
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
Create workflow to run when a survey response is recorded on the intake survey.
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).
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.
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.
Hi @CheriV, I’ve put together a prototype of how this design would look.
Create intake form survey project.
The survey will ask for the employee ID of the person who should be added as a participant/receive the invite.
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.
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
Create workflow to run when a survey response is recorded on the intake survey.
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).
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.
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.
Hi Jake,
Just to confirm, is it possible for us to build this through a workflow without the help from Qualtrics technical team?
Thanks Jake
Are you able to provide a little more instruction on how to set up the webservice import window?
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.
Create survey intake form question
Create a new regular/core survey project (non-lifecycle)
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.
Example: “Enter the employee ID of the employee that should be sent the survey.”
Create a 2nd question block with one text/graphic display question that shows the information to display if a valid employee ID was entered.
Example:
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.
Create a 3rd question block with one text/graphic display question that shows the information to display if an invalid employee ID was entered.
Example:
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.
Setup survey flow with participant search/validation functionality
Open the “survey flow” which is the 2nd tab on the top left of the survey builder.
Insert a new “web service” element under the “Show block” element
Add a new Branch If element to the survey flow under the web service element.
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).
Nest survey question block #2 within the branch.
Add a new Branch If element to the survey flow under the web service element.
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).
Nest survey question block #3 within the branch.
.Create workflow to add participant to Exit Survey project
Go to the “Workflows” tab at the top of the intake form project.
Create a new workflow with a trigger of a survey response.
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).
Add a WebService task under the decision with the following configuration:
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.
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.
Create an Email task under the WebsService task with the following configuration:
To field: ${e://Field/participants.0.email}
Enter the From name/email/subject however is required for your program.
In the message, include the anonymous survey link for your survey program (assuming your survey is accessed by employees via SSO).
Save your email task.
Enable your workflow by turning it on in the top right.
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.
Are you able to provide a little more instruction on how to set up the webservice import window?
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.
Create survey intake form question
Create a new regular/core survey project (non-lifecycle)
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.
Example: “Enter the employee ID of the employee that should be sent the survey.”
Create a 2nd question block with one text/graphic display question that shows the information to display if a valid employee ID was entered.
Example:
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.
Create a 3rd question block with one text/graphic display question that shows the information to display if an invalid employee ID was entered.
Example:
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.
Setup survey flow with participant search/validation functionality
Open the “survey flow” which is the 2nd tab on the top left of the survey builder.
Insert a new “web service” element under the “Show block” element
Add a new Branch If element to the survey flow under the web service element.
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).
Nest survey question block #2 within the branch.
Add a new Branch If element to the survey flow under the web service element.
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).
Nest survey question block #3 within the branch.
.Create workflow to add participant to Exit Survey project
Go to the “Workflows” tab at the top of the intake form project.
Create a new workflow with a trigger of a survey response.
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).
Add a WebService task under the decision with the following configuration:
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.
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.
Create an Email task under the WebsService task with the following configuration:
To field: ${e://Field/participants.0.email}
Enter the From name/email/subject however is required for your program.
In the message, include the anonymous survey link for your survey program (assuming your survey is accessed by employees via SSO).
Save your email task.
Enable your workflow by turning it on in the top right.
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.
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.
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. :/
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.
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.
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?
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.
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:
participants.0.firstName
participants.0.lastName
participants.0.email
participants.0.username
participants.0.userId
participants.0.participantId
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.
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:
participants.0.firstName
participants.0.lastName
participants.0.email
participants.0.username
participants.0.userId
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. :)