Integration with third party APIs 🔗

Crunch allows users to import datasets from SurveyMonkey and Decipher APIs.

Authenticated users can to 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.

Integration with Decipher 🔗

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 a company name (the mycompany subdomain bit of the mycompany.decipherinc.com) and an API key. To obtain an api key, visit https://mycompany.decipherinc.com/apps/api/keys where mycompany is the given subdomain for your organization. Here you will find a link to create a new key, make sure you copy the key that is noted when you create a new key, this is what you need to provide Crunch with 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: app.crunch.io
Content-Type: application/json

....

HTTP/1.1 201 Created
Location: https://app.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.

System Message: ERROR/3 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 1)

Content block expected for the "code" directive; none found.

.. code:: http

GET /api/users/xyz/integrations/abcdef/surveys/

System Message: ERROR/3 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 1)

Content block expected for the "code" directive; none found.

.. code:: json

System Message: INFO/1 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 3)

Unexpected possible title overline or transition. Treating it as ordinary text because it's so short.
{

"self": "https://https://app.crunch.io/api/users/xyz/integrations/abcdef/surveys/", "element": "shoji:catalog", "index": [

System Message: ERROR/3 (None, line 7)

Unexpected indentation.

System Message: INFO/1 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 7)

Unexpected possible title overline or transition. Treating it as ordinary text because it's so short.
{
"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

System Message: WARNING/2 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 15)

Definition list ends without a blank line; unexpected unindent.

}, {

System Message: ERROR/3 (None, line 17)

Unexpected indentation.
"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

System Message: WARNING/2 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 24)

Block quote ends without a blank line; unexpected unindent.

}, {

System Message: ERROR/3 (None, line 26)

Unexpected indentation.
"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

System Message: WARNING/2 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 33)

Block quote ends without a blank line; unexpected unindent.

}, {

System Message: ERROR/3 (None, line 35)

Unexpected indentation.
"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

System Message: WARNING/2 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 42)

Block quote ends without a blank line; unexpected unindent.

}, {

System Message: ERROR/3 (None, line 44)

Unexpected indentation.
"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

System Message: WARNING/2 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 51)

Block quote ends without a blank line; unexpected unindent.

System Message: INFO/1 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 51)

Unexpected possible title overline or transition. Treating it as ordinary text because it's so short.

}

System Message: WARNING/2 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 52)

Block quote ends without a blank line; unexpected unindent.

System Message: INFO/1 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 52)

Unexpected possible title overline or transition. Treating it as ordinary text because it's so short.

]

System Message: WARNING/2 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 53)

Definition list ends without a blank line; unexpected unindent.

System Message: INFO/1 (/var/lib/jenkins/workspace/Crunch-io_zoom_master/apidocs/source/feature-guide/feature-integrations.rst, line 53)

Unexpected possible title overline or transition. Treating it as ordinary text because it's so short.

}

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://app.crunch.io/api/users/xyz/integrations/abcdef/",
      "data": {
          "survey_id": "<Survey ID>",
          "survey_name": "<Optional survey name>",
      }
    }
}

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://app.crunch.io/api/datasets/a598c7/
{
    "element": "shoji:view",
    "value": "https://app.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 of Decipher variables as public variables. The variables will be created in two separate folders. Survey Variables will contain all of the that were created by the user in the orginating Decipher survey. Survey Administration will contain the automatically generated variables used by Decipher to administer the survey. In some cases, crunch will create folders containing variables that are multi-dimensional. 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, follow 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://app.crunch.io/api/users/xyz/integrations/abcdef/",
      "dataset": "https://app.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://app.crunch.io/api/datasets/a598c7/
{
    "element": "shoji:view",
    "value": "https://app.crunch.io/api/progress/5be83a/"
}