In some cases, it may be useful to submit workflow requests programmatically from an external application. For example, it is a common pattern to react to an event in another system (when a ticket is added to a Zendesk or ServiceNow system) by creating a new workflow workitem in a thunk. While the Thunk.AI platform is almost entirely a no-code platform meant for business users, this form of integration does require some coding skills for the person doing the integration.
Each thunk provides a REST API for this purpose. The owner of a thunk can enable this capability by performing these specific steps:
Enable and export the structure workflow request tool for the Thunk
Generate an API Key for the Thunk to allow REST API access
View the API documentation for creating a workflow request for the Thunk
Submit a POST request to add a new structured workflow to the Thunk
Check on the status of the request via the Thunk REST API
1: Enable and export the structure workflow request tool
A thunk needs be configured to explicitly allow external requests to be add via a Thunk specific tool call the "Structured Workflow Process" tool. Each thunk has its own such tool. The owner of a Thunk can enable and export this tool in the Thunk Settings > Deployment > Export Tool Library screen. First enable exported tools for the Thunk and then enable the tool named structured_workflow_process_{thunk_name}. See the screenshot for an example.
2: Generate an API Key to allow REST API access
Each thunk has its own authentication keys for the REST API. Multiple API keys can be created and used for different applications. You can also revoke an API key.
Go to the the Inbound Requests > API Channel view and click on the API Keys button at the bottom. Enter a description for the API key and click "Create Key".
Important! The API key that is generated will only be shown that once. You must copy it to a safe place before closing the dialog.
Copy the API key to a safe place so that you can use it for the next steps. You can return to this dialog to revoke API keys if needed.
3: View the API documentation to create a workflow request
You can see the documentation for the endpoints you can call. Each thunk exposes its own REST API because the inputs required for a workflow request are specific to each thunk.
Go to Inbound Requests > API Channel and click on the "Instructions" button then click on the "View OpenAPI Documentation" button. This will take you to a view like the following.
From this documentation site, you can test your API. First click on the "Authorize" button and paste a copy of your API key into the dialog. Next, expand the POST /start endpoint. Click on the "Try it out" button.
The dialog will be prefilled with a JSON structure with fields defined by your Thunk's input. Change the JSON with meaningful values for the input and click on Execute.
If your request is valid, you will see an example for calling your API using curl and the response with a 200 status and request Id.
You can use this request id to find the status of your request using the /status endpoint. Copy the id and use it in the payload in the /status endpoint. You should see the status of your request.
4: Submit a POST request to add a new structured workflow instance
Having tested the REST API, you can now use any REST API client to automate adding new workflow requests to your thunk. For example, you can call your API using curl. For example:
curl -X 'POST' \ 'https://postern.thunk.ai/api/thunk/<thunk_id>/workflow/start' \
-H 'accept: application/json' \
-H 'x-api-key: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"items": [{
"data": {
"Name": "Issue - #42",
"Product": "Game of Life",
"Customer": "Everyone",
"IssueDetails": "Not sure of the meaning"
}
}
]}'
Replace your with your thunk_id and api-key.
5: Check on the status of the request via the REST API
After creating an request you will receive an id. You can use this identifier to request for the status of the workflow request.
curl -X 'POST' \ 'https://postern.thunk.ai/api/thunk/<thunk_id/workflow/status' \
-H 'accept: application/json' \
-H 'x-api-key: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"instances": [{ "id": "<request_id>" } ]}'