In this article
Getting Started
This integration allows for the export survey data from the Forsta Surveys survey platform directly into Forsta Visualizations using the Forsta Surveys REST API and Forsta Visualizations Data REST API.
Beta status
The first release of the integration is a Beta, we expect to see issues as the integration is adopted. These will be fixed as soon as possible.
Important: COMPATIBILITY WITH ORIGINAL Forsta Surveys INTEGRATION AND FILE BASED IMPORTS!
The Forsta Surveys v2 integration is not directly compatible with the earlier Forsta Surveys integration or other sources. The metadata will not match, as the question codes and answer values are derived differently, the respondent id is created with a different mechanism from the UUID it is therefore not possible to start using the v2 integration in projects that have previously used other data sources without large modifications to the metadata or by using extensive mapping in the MDT during import and at the very least a complete import of data to update respondent id’s.
Pre-Requirements
In order to use this API, you will need to have an account on the Forsta Surveys platform with the API feature enabled. This will allow you to create an API key. An API key is a mandatory parameter for this integration to Forsta Visualizations. Please refer to the Forsta Surveys documentation for details on how to generate a key. It should be 64 characters long and consist of the public and private key. This key should be treated as you would a password.
Using the System
Your administration account will need access to the integration in Forsta Visualizations. If you do not see the Forsta Surveys V2 in the list of integrations and you believe it should be available, you will need to request access from your Customer Success Manager or Account Manager.
Setup Integration
To setup the data source adapter, the scheduled task in other words, complete the following tasks:
Task 1: Go to the Data Integration Scheduler screen
To access the Data Integration UI in Forsta Visualizations, please follow these steps after creating or selecting the appropriate project:
Select the Data tab from the main menu
Click on the arrow under Import data, then select Schedule imports from the dropdown menu.
Then the Data Integration UI will open.
Task 2: Create the Scheduled task
Your first scheduled task is automatically created when you access the Import Scheduler screen for the first time. This screen contains all the setup controls for the new data source adapter instance. Some of these parameters are mandatory, and some are optional.
When you access this screen for the first time, if you wish to give it a name rather than the default value enter the required name and check the Active checkbox. If you do not add a name an automatically generated name will be applied.
After the first scheduled task has been created, you can create more data scheduler tasks for the same project with different configurations. To create a new scheduler task, just click the ‘Create new’ button.
The import schedule configuration form will be cleared for new parameters and configurations. Also, if you need to delete a task, simply select the task you would like to delete from the Selected import schedule dropdown list and then click the ‘Delete selected’ button.
Task 3: Set Data Import Scheduler
Every Import Scheduler job can be scheduled to be triggered just once or to be repeated based on one of the following schedules:
Hourly
Weekly
Monthly
You can select the schedule type from the ‘Import type’ dropdown menu on the Import scheduler UI.
Note: When the ‘Run import on save’ checkbox is selected, then the import job will be triggered immediately after the Save button has been clicked. Scheduled jobs will also be saved for the time that you select. You may wish to set the scheduled time to run in the past to prevent the task running again or inactivate your scheduler after initial import.
Task 4: Choose Data Source
To select a Data Source for your Data Adapter, use the Data source dropdown menu. This dropdown list contains all data sources that users have access to.
By default, the data source is set to the FTP Server, but this should be changed to Forsta Surveys V2. When Forsta Surveys V2 is selected as the data source, then the configuration form will be loaded.
Task 5: Set up Data Source
To set up the Forsta Surveys data source, you need to create an API key. To learn how to do this, see prerequisites, in this manual (above)
To setup Forsta Surveys V2 integration, follow these steps:
Enter your API key from Forsta Surveys, this should be 64 characters long.
Set the base URL.
Click the ‘Load survey list’ button. If the list loads you entered the correct key and URL. If there is an error check the values entered in step 1 and 2.
The survey list will be populated with all surveys from Forsta Surveys that are linked to the provided API key.
Select the desired survey, and the Survey path field will be populated.
Survey layout, choose which layout template to use. This is optional and there may be no layouts defined.
Layout selected will be shown.
Optionally select which variables to include, you can preview all the variables in the MDT (please refer to relevant documentation on MDT usage). This defaults to importing all variables. I.E. if you leave this field empty all variables will be imported.
-
The filter expression allows you to filter the data downloaded. Here you can select response status filters, default is qualified, others are terminated, overquota and partial. To import all respondents including partial, the filter would be:
“qualified or partial or overquota or terminated”
-
Apply exclude flags to remove system variables - the types supported are v, x, t :
v -- this is a “virtual” (computed) variable rather than recorded while taking the survey.
x -- this is an "execute only" question, i.e., it is filled out during the survey but using code (e.g. prefill/autocode/autofill)
t -- this is a "transient" question, which usually indicates something auto-generated by the system (so for example, variables like qtime for interview time, vos / browser for operating system / browser assignment etc)
Select time period the selected survey's data. Select this from the Time period dropdown. If nothing is selected, then the system will load data from all respondents. If a specific date range is needed, then select the ‘Static’ option from time period dropdown.
The Start and End date controls will appear. Simply check the Start and End date check boxes and choose the specific dates from the calendars.
If incremental updates are required to be run at a regular interval use the Auto option.
Set import to Auto, use the “date” variable from the survey and set date format to MM/dd/yyyy hh:mm:ss
We recommend using a date time variable, as this makes it possible to correctly retrieve the newly added responses in the survey. Using ResponseDate will only filter on date, as it is stored as a date, rather than the time of day. This can cause issues with missing responses.
System Variables
The RespondentID is mapped from UUID, the same UUID will always give the same numeric value.
ResponseDate is taken from the system “date” variable in Forsta Surveys, if missing it is taken from
“start_date”, if also missing it will default to current date time.
Weight will be assigned to value 1 unless there is a variable named weight in the survey, that will be used instead.
Metadata Transformation
The final step is to create the metadata definition. Typically, this is used for eliminating unwanted variables (e.g. system information such as browser version or screen resolution), search and replace updates on codes and texts, fixing answer texts in multiple choice questions, fix any errors on import etc.
Please refer to general Forsta Visualizations documentation for further details on the metadata transformation function.
After completing these steps, the data adapter will be configured ready to use. The last step is to click ‘Save’ at the end of the Import scheduler UI.
After completing this, the Forsta Surveys Data Adapter will be configured ready to use. The last step is to click ‘Save’ at the end of the Import scheduler UI.
Using Layouts to Resolve Issues
You can use layouts in Forsta Surveys to exclude variables which are not required for reporting (aside from the flag exclusions (v,t and x) and include variable options described above).
The layout function also sets sort order of variables.
If there is an issue importing data, and the error relates to a specific variable you can use the Forsta Surveys layout feature to exclude the affected variable.
Care should be taken not remove required variables with layouts. E.G. UUID and date. Removing UUID will cause the import to fail as this the unique identifier for the responses. “date” is required to have the correct response date.
Stacked Data Support
Any stacked data will be loaded automatically. Activation will include stacked data. Any logic for last “x” batches will include stacked data associated with the regular data batches. The number of main data batches will match the number of batches selected for activation. If you have one main batch and three stacked data batches in each import, selecting to activate last 2 batches will result in 2 main data batches and 6 stacked data batches (2 * 3) being activated.
Iterators, the keys for the loop, are identified to be used in Forsta Visualizations.
Supported Controls
Typically, questions repeat to represent both columns and rows. For instance, a multiple choice defined with 4 rows and 3 columns will generate 4 multiple choice questions each with 3 answer options.
Scale questions are transferred as single choice (non-scale) but values are correctly transferred. To use the values as factor average values in Forsta Visualizations use the questions screen to change question type to single choice scale.