Crunch allows users to import datasets from various third-party APIs, such as SurveyMonkey and Decipher.
Authenticated users can provide their API credentials and store them in the user integrations catalog. The different credentials will be required for each third-party provider.
Entries in the integration catalog will allow the integration endpoints to read metadata and responses from the providers’ APIs and import them as a dataset in Crunch.
The following describes how to integrate with Decipher's API.
How it works
Once the integration credentials are stored in the integration catalog, Crunch can import datasets from the Decipher API. Note that at this time, the user must have “Early Access” selected on their account to integrate with Decipher. See Progress.
To manage surveys from the Decipher API a client should:
- Obtain the associated integration credentials to use
- Obtain the name/id of the decipher dataset to import
- POST to the add_dataset endpoint under the Decipher integrations
The authenticated user should have these credentials stored in the /api/users/:userid/integrations/ catalog.
In order to discover the Decipher integration, the client should query the global integrations catalog at /api/integrations/ and follow the entry for the decipher integration.
Storing Decipher credentials
In order to read from the Decipher API, users need to provide a combination of your organization's workspace name (e.g., [workspace].decipherinc.com) and an API key.
To obtain an API key, visit https://[workspace].decipherinc.com/apps/api/keys, where [workspace] is the given workspace name for your organization. A link appears when you open the page, where you can create a new key.
Make sure you copy the key that is noted when you create a new key, as you need to provide Crunch with it in order to gain access to your decipher datasets within Crunch.
POST a shoji:entity to the user’s integration’s catalog containing the required keys:
POST /users/xyz/integrations/
{
"element": "shoji:entity",
"body": {
"name": "decipher",
"apikey": "secretapikey",
"company_name": "mycompany",
"description": "Optional description to hint which key is this"
}
}
The server will return a 201 response in the case of success containing the Location header for the newly created integration key.
POST /api/datasets/ HTTP/1.1
Host: [workspace].crunch.io
Content-Type: application/json
....
HTTP/1.1 201 Created
Location: https://[workspace].crunch.io/api//users/xyz/integrations/abcdef/
This newly created integration URL will be provided to the decipher integration endpoints to indicate which set of credentials to use to read from the Decipher API.
Listing Decipher surveys for import
Once you have a decipher integration stored, you can access a listing of the surveys available from your Decipher account. The id indicated is the survey_id which may be used for importing into Crunch.
GET /api/users/xyz/integrations/abcdef/surveys/
{
"self": "https://https://[workspace].crunch.io/api/users/xyz/integrations/abcdef/surveys/",
"element": "shoji:catalog",
"index": [
{
"date_modified": "2012-10-02T12:43:14Z",
"language": "english",
"title": "Survey 2",
"response_count": 431,
"date_created": "2016-03-21T22:25:20Z",
"id": "selfserve%2F548%2F130917",
"question_count": 16
},
{
"date_modified": "2014-10-03T23:20:19Z",
"language": "english",
"title": "My Special Survey",
"response_count": 413,
"date_created": "2016-03-21T22:25:20Z",
"id": "selfserve%2F548%2F130630",
"question_count": 31
},
{
"date_modified": "2019-08-10T08:48:48Z",
"language": "english",
"title": "The source",
"response_count": 596,
"date_created": "2018-08-10T03:44:41Z",
"id": "selfserve%2F548%2F180801",
"question_count": 24
},
{
"date_modified": "2016-10-06T13:36:34Z",
"language": "english",
"title": "Testing 1 2 3",
"response_count": 214,
"date_created": "2016-03-21T22:25:20Z",
"id": "selfserve%2F222%2F18902",
"question_count": 7
},
{
"date_modified": "2015-10-03T00:19:40Z",
"language": "english",
"title": "Roger Wilco",
"response_count": 924,
"date_created": "2016-03-21T22:25:20Z",
"id": "selfserve%2F222%2F3456",
"question_count": 37
}
]
}
Importing a dataset
Under the decipher integration url, an add_dataset endpoint is available, where clients can create a crunch dataset directly from the Decipher API:
POST /integrations/decipher/add_dataset/
{
"element": "shoji:entity",
"body": {
"integration": "https://[workspace].crunch.io/api/users/xyz/integrations/abcdef/",
"data": {
"survey_id": "<Survey ID>",
"survey_name": "<Optional survey name>",
"variable_attributes": {"description": "qtitle", "name": "qlabel"}
}
}
}
The server will return a 202 response with a progress response, and the Location header pointing for the imported dataset in Crunch. The new dataset will be created under the authenticated user’s personal project. See Progress.
HTTP/1.1 202 Accepted
Location: https://[workspace].crunch.io/api/datasets/a598c7/
{
"element": "shoji:view",
"value": "https://[workspace].crunch.io/api/progress/5be83a/"
}
Once the progress has completed, the new dataset will be ready and contain the variables and responses from the original Decipher API.
Importing rules
Crunch will import all Decipher variables as public variables. The variables will be created in two separate folders:
- Survey Variables will contain all variables created by the user in the originating Decipher survey.
- Survey Administration will contain the automatically generated variables used by Decipher to administer the survey.
In some cases, Crunch will create a folder to contain a multi-dimensional variable; specifically, array variables that are grouped by column or row in Decipher.
Updating a dataset
Crunch supports the ability to synchronize the responses in Crunch with that which exists in Decipher. To do this, it will grab any new responses that have been generated by Decipher and integrate them with the existing dataset in crunch. Any derived variables on your Crunch dataset will remain.
One limitation of this process is that any metadata changes on the Decipher end will not allow an update to occur, but you may create a new dataset in this case. Only datasets that were originally created using the decipher integration endpoint are eligible to update.
To proceed, proceed to the update_dataset in the Decipher integration and POST the user integration credentials and the dataset ID to update:
POST /integrations/decipher/update_dataset/
{
"element": "shoji:entity",
"body": {
"integration": "https://[workspace].crunch.io/api/users/xyz/integrations/abcdef/",
"dataset": "https://[workspace].crunch.io/api/datasets/123456/",
}
}
}
The server will return a 202 response with a progress response, and the Location header pointing for the updated dataset in Crunch.
See Progress.
HTTP/1.1 202 Accepted
Location: https://[workspace].crunch.io/api/datasets/a598c7/
{
"element": "shoji:view",
"value": "https://[workspace].crunch.io/api/progress/5be83a/"
}