Api Access for Activity Runs
URL
Whenever an activity is published, an API url automatically becomes available based on the activity name and schema. The url has the form
<base_url>/api/run/<schema>.<name>
<base_url> is the url at which the SheetKraft portal can be accessed. <schema> and <name> must be url-encoded if necessary. It will be possible to customize the <schema>.<name> part of the url in a future release.
Consider an activity in the schema 'test' with name 'Add 2 numbers'. The url for this activity will be
<base_url>/api/run/test.Add%202%20numbers
Note that the %20 is due to url-encoding of the spaces in the activity name.
Inputs
Suppose the activity takes two inputs with names 'number 1' and 'number 2' and returns an output with name 'sum'. The activity can be run by making a POST HTTP request to this url with a content type of application/json. An example of the json that needs to be posted is shown below.
{
"inputs": {
"number 1": 2.5,
"number 2": 5.7
}
}
Authorization
The POST request must be made with basic authorization (Authorization header must have the value of Basic <base 64 encoding of 'username:password'>) Note that it is recommended to use https for the SheetKraft portal for security reasons.
Response
After the activity runs successfully, a response of type application/json will be returned. An example is shown below
{
"id": 123,
"status": "Succeeded",
"outputs": {
"sum": {
"id": 35,
"type": "number",
"value": 8.2,
"format": null
}
},
"errors": [],
"warnings": [],
"messages": []
}
Table Input and Output
If the activity has a table input, it must be specified as an array of arrays. For example, an input with 3 rows and two columns userid and emailaddress would be provided as
[
[1, "user1@domain.com"],
[2, "user2@domain.com"],
[3, "user3@domain.com"],
]
If the activity has a similar table as output, it will be returned in the form
{
"schema": {
"fields": [{
"name": "user_id",
"type": "number",
"format": null
}, {
"name": "email_address",
"type": "string",
"format": null
}
]
},
"data": [
[1, "user1@domain.com"],
[2, "user2@domain.com"],
[3, "user3@domain.com"],
]
}
File Input
If the activity has file inputs, these must be uploaded with a separate API call to obtain a file id which must then be provided as an input.
To upload one or more files, a POST request must be made to <base_url>/api/runinput/upload with a content type of multipart/form-data in the following format.
Activity: <schema>.<activity_name>
InputName: <activity_input_name>
<file>
A json response will be obtained as shown below
{
"files": [{
"id": 25,
"name": "file1.xlsx"
}, {
"id": 26,
"name": "file2.xlsx"
}
]
}
The ids obtained from this response must be sent in the json to run the activity. For example if the activity has an input that needs one or more excel files and the name of the input is 'data_files', the json must be of the form
{
"inputs": {
"data_files": [{
"fileId": 25
}, {
"fileId": 26
}
]
}
}
If there is a single file, the array can be omitted and a single object with a fileId can be sent as shown below
{
"inputs": {
"data_files": {
"fileId": 25
}
}
}
File Output
If the activity has file outputs, the output will be of the form shown below
{
"id": 127,
"status": "Succeeded",
"outputs": {
"result_files": {
"id": 38,
"type": "file",
"value": 3,
"format": null
}
},
"errors": [],
"warnings": [],
"messages": []
}
This response indicates that there are 3 files associated with the output resultfiles. These files can be obtained with GET requests to the
<baseurl>/api/runoutput/download/<runid>/<outputid>/
In this example, to download the 3rd file, the url would be
<base_url>/api/runoutput/download/127/38/2
Note that the index is zero based and can be omitted. It has a default value of zero.