Kognitos Automations

Overview of the Kognitos Automations integration.

The following documentation is for Kognitos Automations v2.0.0.

Overview

Kognitos Automations lets one automation run another and track how it went. Use it to split work between a parent automation that fans out and a child automation that handles a single item. Each invocation creates its own run, so one item failing leaves the others untouched and every item ends with a status you can report on or retry.

Setup

The following integrations need to be connected to your Kognitos workspace:

• Kognitos Automations

Steps

Follow these steps to connect the integration in Kognitos:

1

Navigate

Using the left navigation menu, go to Integrations → Explore Integrations.

2

Find

Search for the integration and click on it.

3

Connect

Click on Connect to add a connection to the integration.

4

Configure

Add a name for the connection. You'll be prompted for authentication details if needed. Then, click on Connect.

Credentials

This integration connects to a Kognitos workspace, which can be the workspace the automation already runs in or a different one. You need three values.

1. API Key

1

Open API Keys

Click on your name or profile avatar in the bottom-left corner to open the user menu, then select API Keys.

2

Create a Key

Click Create API Key, then scope the key to the workspace whose automations you want to invoke. See API Keys for the full set of options.

3

Copy the Key

Copy the key as soon as it is created. It is shown only once.

The key needs permission to list and invoke automations and to read runs in the target workspace. A key limited to read-only access can list automations and runs but cannot invoke them.

2. Organization Id and Workspace Id

Open the target workspace in Kognitos and read both values from the address bar. A workspace URL has the form /o/<organization-id>/w/<workspace-id>.

Authentication

Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements.

Connect using API Key, Organization Id and Workspace Id

Connect to a Kognitos workspace using an API key.

Label	Description	Type
API Key	An API key generated in the Kognitos UI.	sensitive
Organization Id	The organization that owns the workspace.	text
Workspace Id	The workspace whose automations you want to invoke.	text

Configuration

The following options control how this integration reaches Kognitos. Both have defaults and only need changing in specific cases.

Option	Description	Type	Default
base url	Root URL of the Kognitos deployment to call, without a trailing path.	text	https://app.us-1.kognitos.com
timeout	Seconds to wait for any single call to the Kognitos API.	number	30.0

Set either option in plain language:

the department's Kognitos Automations's base url is https://app.us-1.kognitos.com

Change base url only when the target workspace lives in a different Kognitos deployment than the default. It must point at a Kognitos deployment, because the connection's API key is sent to that host as a bearer token.

Actions

The following actions are available in the Kognitos Automations integration:

1. Await a kognitos run's completion

Wait until a run finishes, then report how it went.

2. Get a kognitos run

Look up a run you already know the id of.

3. Get a kognitos run's status

Check how a run is doing, without waiting for it.

4. Invoke a kognitos automation

Start another automation and return its run straight away.

5. Invoke a kognitos automation for each item

Run one automation once per item and report how each one went.

6. List a kognitos automation's runs

List recent runs of an automation, newest first.

7. List the kognitos automations

List the automations this connection can invoke.

Concepts

Kognitos run

A single execution of a Kognitos automation.

Field Name	Description	Type
run_id	The run's unique identifier.	text
automation_id	The automation that was invoked.	text
stage	Whether the draft or the published version was invoked.	text

Kognitos run status

The observed state of a Kognitos run.

Field Name	Description	Type
run_id	The run this status describes.	text
automation_id	The automation the run belongs to.	text
state	One of pending, executing, stopping, stopped, awaiting guidance, completed or failed.	text
is_finished	True when the run will not change state on its own.	boolean
outputs	The run's outputs. Only populated once it has completed.	optional[json]
error_id	The identifier of the error that failed the run. Worth recording alongside a failed item: it is what support needs to find the failure.	optional[text]
error_description	Why the run failed, when it failed.	optional[text]
exception_id	The Guidance Center exception blocking the run, when it is awaiting guidance.	optional[text]
exception_description	What that exception says.	optional[text]
timed_out	True when a wait gave up before the run finished. The run itself is unaffected and keeps going.	optional[boolean]

Kognitos automation

An automation in the connected Kognitos workspace.

Field Name	Description	Type
automation_id	The automation's unique identifier.	text
display_name	The automation's name as it appears in the product.	text
description	What the automation does, if its author wrote one.	optional[text]
input_names	Names of the inputs the automation accepts.	optional[list of text]
latest_published_version	The newest published version, if any.	optional[text]