Execution API Reference

APIs

Custom Actions

• Configure a module to be executable via API
• Define start parameters
• Execute a published module
• Without start parameters
• With start parameters
• Query the current session status

The Execution API should be used by third party applications to:

• Start execution of a published module, thereby creating a session in the process
• Pass start parameters to a published module
• Query the current status of a published module’s session

This API can currently not be used to:

• Return values

Configure a module to be executable via API

Before you can use the Execution API, you need to change the published module’s publishing settings: Select Only accessible via an API key under Access Settings:

Define start parameters

Start parameters define data that will be passed to the module when it is executed. They can be defined by clicking on the “Start” node of your module in the BRYTER editor.

Start parameters are configured as follows:

Name

The name of the start parameter when referenced in the module editor (e.g. Employment Start Date). The parameter can then be referenced in the module by using the @ key followed by the name of the parameter. Please note, this is not the name that should be used in the API call.

Type

The type of value that defines the start parameter (e.g. Date or Number)

Available start parameter types:

• Text
• Date (YYYY-MM-DD)
• Number
• Email Address

API parameter name

The name of the parameter to be used when calling the API endpoint (e.g. employment_start_date)

Execute a published module

Example values

• API Key: NiAMlNvpsDkMgmYpCPzBL8PfGFXGO1XE4Xko3bkW2bE
• Published Module Id: oITwNKIrRdS0A0TFVPP54g
• Session Id: C0jz_2J6RmOLoB8DyXPs9Q

Without start parameters

Request

POST /api/execution/PUBLISHED_MODULE_ID/sessions //REPLACE PUBLISHED_MODULE_ID with the ID of the ID of the published module you would like to execute 
Authorization: Bearer API_KEY //REPLACE API_KEY with the published module’s API key
Content-Type: application/json

With start parameters

If applicable, start parameters should be inserted within the body of the API call.

The following example executes a module that accepts employee data:

Request

In the example above, the module accepts the following start parameters:

employee_name, a text variable that is passed the value of “John Doe”

employee_email, an email variable that is passed the value of “john.doe@example.com”

employee_start_date, a date variable that is passed the value of “2021-09-09”

Response

Query the current session status

Once you receive a response from the Module Execution API call, you can run another API call to check the progress of the session initiated by the Module Execution API call. This allows you to monitor the status of the session and check if any errors have occurred.

Request

GET /api/execution/PUBLISHED_MODULE_ID/sessions/SESSION_ID  //REPLACE PUBLISHED_MODULE_ID WITH THE ID OF THE MODULE EXECUTED BY THE MODULE EXECUTION API AND REPLACE SESSION_ID WITH THE ID OF THE SESSION RETURNED BY THE RESPONSE FOT HE MODULE EXECUTION API CALL
Authorization: Bearer API_KEY  //REPLACE API_KEY with the published module’s API key
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
      "state": "created"
    }, 
    "links": {
        "self": "/api/execution//PUBLISHED_MODULE_ID/sessions/SESSION_ID",
        "browser": "https://app.bryter.test/PUBLISHED_MODULE_ID/sessions/SESSION_ID"
    }
}

The response will contain the current state or status of the session.

Possible session states:

• created: Session has been created but processing didn't start yet
• running: Engine is currently processing the session
• waiting_for_input: Engine is waiting for user input
• fatal_errored: There was a fatal error in the module execution that can't be recovered
• completed: The session completed successfully
• unknown: The session pre-dates the module execution API