Data Import API - A Swagger Tour – Forsta Visualizations

A quick tour of the API using Swagger

You will need an admin account and an empty project to follow these steps, (Make a note of the numeric project Id).

The Swagger is useful for investigating how the API works. It would never be used for real uploads.

Logging In

Go to the relevant Swagger where you have your Forsta Visualizations admin account. In this case we are using dashboards.

Your production account will not be on dashboards. If your normal access URL is https://live.dapresy.com then the API will be at https://live-dataapi.dapresy.com, so always the original host name with -dataapi as a suffix e.g. dc-dataapi, manager-dataapi etc - if you have a custom or vanity URL you will need to use the main URL, if in doubt please contact support.

You should see this:

Let's get the token we are going to use for authentication.

Find the button labelled Post under the heading Account and click it

Then click on try it out

Follow the steps below this picture

Step 1 - enter your credentials in a valid JSON format eg:

{

"Username": "AdminUser123",

"Password": "AdminUser123sPassword"

}

Step 2 - Click Execute - you should see the result with code 200, if not check your credentials (are you on the right install?) and the format of the JSON.

Step 3 - Carefully copy the access_token

Click the "Authorize" button at the top of the page

1 - In the modal dialog paste the access token (Use the format "Bearer <token>" eg "Bearer x00...etc")

2 - Click authorize

You should see a success message. If not, check that the token was copied correctly, do not include the quotes.

Import Data

Now we will import some data into our project.

This is the data format used by the Data Import API, copy the contents of this file to your clipboard: Sample file (also attached to this article below)

For more details about the format and field values please refer to this document: Dapresy Import API reference - Case and Metadata

1 - Paste the JSON

2 - Enter the project id (make sure there are no trailing spaces)

3 - Click execute

After you click execute you should see the result. Status 200 means the message was processed correctly. If you see another number it is likely something was wrong with the JSON message or you weren't authenticated. (Did you remember to put "Bearer " in front of the authentication token?)

There are two parts to examine in the response:

1 is the import result

2 is the status - the status will be "SUCCESS" even if there are errors in the actual data sent, i.e. the operation was a success overall, so make sure to refer to the import result above to check if there are any issues with the data.

You can use the other methods on the page, for instance to see batches:

Remove the filter and sorting parts of the request, set the page size to be a larger value than 0, so that it looks like the above. If you do not amend the page size there will be no result returned.

The result should be like this:

Clarification of fields here:

IsActive - has this data batch been activated

NumberOfResp - the number of respondents in the batch

Tag - any applied tags which can be used in scheduled imports to select batches to activate / deactivate or when querying batches via the api.

UpdateData - is this batch to be used as an update to existing respondents

NewAndUpdateData - is this batch to be used to insert new and update existing

DataPointCount - the number of responses (individual answers) in the batch

Now you can go on to activate your data, as you now know which batches you have in the project, you will need to list these in the activation step.

Go to the Activation section and select the activation end point. Click on "Try it out". Edit the body so it matches the batches you have. You must list all batches here, IdsToActivate for the batches to activate, IdsToDeactivate are the batches that will not be activate - so if there is only the first batch in the project it would look like this: