Using JavaScript Scripts to Interact with the Civis API

If you haven't read the documentation on JavaScript Scripts, go do that now.  You'll also want to read our documentation on reading API documentation (Yeah, we see the irony in reading documentation about how to read documentation).

The Functions

There are two functions that you'll be primarily using when interacting with the API in JavaScript Scripts:

• civis.api.call() - The function that interacts with the Civis API.
• log() - Writes its contents to the job's run log.

Using civis.api.call()

There are three parts to this function:

• Method - The HTTP verb for the API call (e.g. PUT, GET, PATCH, etc.)
• Path - The path of the endpoint (e.g. /jobs, /jobs/:id).
• Parameters - Information about the API call that isn't included in the path.  If you were creating a new Database Import, "name" would be a parameter.

Example API Call:

If I wanted to get a list of Database Imports, the API call would be:

civis.api.call("get","/imports",{"type":"DbSync"})

Notes about each part:

Method

The method must be lowercase.  For example, you'll need to use "put" rather than "PUT" otherwise the civis.api.call() function will error.

Path

You can find the path on our API documentation page.  Remember that you'll need to replace any part of the path that contains a colon in front of it with an actual value.  For instance, to get information about a specific job, you'll want to use the /jobs/:id path, but in your JavaScript you'll need to replace ":id" with the actual ID of the job.

Parameter

Parameters must be contained inside of curly brackets "{}".  Some endpoints don't require parameters, so this part of the call is technically optional, but if there are required parameters then they must be included in the call.

Objects and Arrays in Parameters

While parameters need to be contained inside of curly brackets, some parameters have their own set of objects or arrays where properly formatting the API call can be tricky.  Using the POST /models documentation as an example, we see that there are two interesting parameters: excludedColumns and notifications.  Since excludedColumns is an array, we'd include it our JavaScript like:

civis.api.call("post","/models",{"excludedColumns":["column_1","column_2"]})

You'll need to contain your array with a set of square brackets.

To incorporate the notifications parameter, it'd look like:

civis.api.call("post","/models",{"notifications":{"successEmailSubject":"Model Complete!"}})

Notice that since the notifications parameter is an object, we had to include its properties in their own set of curly brackets.

The notifications parameter also contains an array for successEmailAddresses.  If we wanted to include both successEmailSubject and successEmailAddresses in our API call, it'd look like:

civis.api.call("post","/models",{"notifications":{"successEmailSubject":"Model Complete!","successEmailAddresses":["support@civisanalytics.com","email@email.com"]}})

Troubleshooting Your Code

One of the best ways to troubleshoot your code is to incorporate logging to detect at what point in the code the error is occurring.  If you have a JavaScript Script that makes multiple API calls, putting a logging event before each call will show you which call is responsible for the error.  For example, if I had a script that created a new SQL script and shared that script with another user, I would write:

log("Creating new SQL script.")

var new_script = civis.api.call("post","/scripts/sql",{"name":"Sales Count Script","remoteHostId":123,"credentialId":456,"sql":"select count(*) from schema.sales"})

log("Sharing the script.")

civis.api.call("put","/scripts/sql/" + new_script.id + "/shares/users",{"userIds":[123],"permissionLevel":"read"})

If you were to run this script and view the run log, if you get an error and see the "Sharing the script." log message, you know your code successfully executed the script creation portion of your code but failed on the sharing portion, and can troubleshoot appropriately.