This article will walk you through setting up an Application and the steps needed to support this process. The diagram below shows the flow after an application is configured. While the details below will detail out the steps to configure the surveys and application in Peoplevine along with sample code and links for submitting the responses and application.
To get started, you need to setup the survey forms along with assigning them to the application. Check out this article on how to build a survey application. Also please note the base URL for these calls are https://api.peoplevine.com/survey.asmx/. Change .com to .co.uk for Region 2.
Now that you have your application in place, you'll need to build out your UI to display the questions and flow to the user. If you're looking to build this from scratch and make it dynamic to field changes/additions in Peoplevine, then we recommend you connect to returnSurvey to bring back the survey_fields.
Inside the survey object you receive from returnSurvey, you will find survey_fields. This array of objects contains information about each field including the type, label, help text, style, field type and more.
[ { "field_name": "custom field name", "survey_field_no": 0, "survey_no": 0, "field_type": "e.g. dropdown", "field_label": "Label of Field", "field_values": "Available values to select from split by ^", "field_help": "Any help text", "field_style": "CSS Class", "field_order": 0, "field_required": false, "data_map": "maps to crm field to populate" }]
Loop through these fields to build your survey. When mapping these fields, make sure you can get the survey_field_no, survey_assign_no and survey_no as these will be needed to map the data to answerSurvey.
In order to accomodate all fields types, we support the following:
- canvas - used for signatures
- upload - ability to attach a file
- textbox - plain input with validation based on data_map
- password - capture someone's password (keep masked)
- encrypted - similar to password, but a separate field
- multiline - plain input with multiple lines
- label - display to user
- text - display to user
- dropdown - select one from a list (see 1)
- radiobutton - select from from list (see all)
- checkbox - select multiple from a list
- yesno - choose yes or no
- date - enter a date
- rating - rate 1 through 5
- rate10 - rate 1 through 10
- stars - rate with stars
- hidden - on the form as we need to submit to answerSurvey
- payment - prompt for payment information, make sure you provide us with the token from the provider
Once your survey is rendered, you can then submit the responses to the answerSurvey API. You can learn more about answering a survey via this article. Please note that you can submit the forms all at once or in separate flows, just make sure the response_guid is consistent across all answers.
Uploading a File
When submitting a file to the answerSurvey API please make sure that you have already uploaded that file to our media repository. Once uploaded, you can provide the URL to the survey_answer value.
You can upload files to our uploadMedia API in the Media endpoint. Add the title, description, media type (file extension) along with mapping to a reference_type/no. The reference_type can be survey and reference_no be the survey_no. This will associate the media to the survey. You will also need to convert the file to a array of bytes and then pass along to the uploadMedia API. Here's sample JSON that is required.
{ { "media_title": null, "media_description": null, "media_type": null, "reference_type": null, "reference_no": 0 }, { "media_object": Array[of Bytes ] }}
Setting Up and Submitting the Application
When answering a survey application, we recommend you making two additional calls to setup the application. You can choose to submit these once they've submitted all data or we recommend setting up the application and then updating the status once fully submitted.
If you are building a dynamic UI to load all questions/forms, you should call returnSurveyGroup (via the survey api). This will allow you to return the application and all surveys/forms associated with it.
Call returnSurveyGroup with these parameters set. If you know the customer_no it allows us to determine if they've applied already.
{ "customer_no": 0, "survey_group_no": 0, "survey_group_status": "active", "includeAssignments": true}
Once you obtain the survey_group and data, you'll want to loop through the surveyGroup.assignments until all items are displayed and/or completed. Please note that the reference_type in the assignments refers to either survey or content. If it's a survey, you can obtain the survey_no from reference_no and call returnSurvey and obtain the survey_fields. If it's content, you can call viewPage in the content API to return this.
When looping through the forms and submitting to answerSurvey, make sure you set a static response_guid (a unique identifier) that is used on all answers and when submitting the application. This value ensures that we group this response together. If the user completes the application, the guid should be cleared. A new guid should be provided to each user/application. This is typically known as a UUID or GUID.
After the first survey is answered, we recommend you call createSurveyApplication in the survey API to start the application. To submit this, you will need the customer_no that is generated when you submit answerSurvey. Then include the following data when sending to createSurveyApplication.
{ "reference_type": "membership", "reference_no": 0, "survey_group_no": 0, "response_id": "RANDOM GUID", "customer_no": 0, "application_status": "pending" }
This will set the application as pending in Peoplevine and will continue to show progress as they continue to answerSurvey. The response will contian the survey_application_no. When the user is finished submitting the application, you will leverage the survey_application_no to call submitApplication in the survey API and just update the application_status to new with this body:
{ "updateFields": "application_status", "survey_application_no": 123, "application_status": "new" }
Once set as new, Peoplevine will fire off any triggers such as the "thank you for submitting" email along with notifications to your staff.