Actions

Action represents a single request or query your application wants to make in an external application. For example, "Create a task", "Get list of users", or "Send a message".

Here is an example of an action:

name: Create Task
key: create-task
inputSchema:
  type: object
  properties:
    title:
      type: string
    description:
      type: string
type: create-data-record
config:
  dataSource:
    collectionKey: issues
  fieldMapping:
    defaultValue:
      summary:
        $var: $.input.title
      description:
        $var: $.input.description

Action Structure

Action has the following properties:

  • inputSchemaData Schema describing the payload that will be validated when you run the action.
  • type – action type that maps to a Function Type that implements the run function of this action.
  • config – implementation of the run function.
  • outputSchema - defines expected output of the action.
  • customOutputSchema - overrides the default value of outputSchema. If customOutputSchema is set, outputSchema will always equal customOutputSchema

Run Function

Action interface provides one function: Run.

The implementation of this function is configured with two properties: type and config.

The run function receives the following arguments:

  • input - action input provided when running the action.

Action types map to Function Types and let you choose how action's run function is implemented. If not sure what action type to use, Javascript is the most versatile type that lets you do anything, and API Request to External App is commonly used to configure API requests if it's all that action needs to do.

TypeDescriptionFunction Type
run-javascriptRuns custom JavaScript (or TypeScript) codeJavaScript
api-request-to-external-appMakes API requests to the external app with authentication applied automaticallyAPI Request to External App
api-request-to-your-appMakes API requests to your Internal APIAPI Request to Your App
http-requestMakes arbitrary HTTP requests to any endpointHTTP Request
list-data-recordsList records in a data collection page by pageList Data Records
find-data-record-by-idFind a record in a data collection by IDFind Data Record By ID
search-data-recordSearch data records by a query stringSearch Data Record
match-data-recordFind a data record with fields matching a queryMatch Data Record
create-data-recordCreate a new data recordCreate Data Record
update-data-recordUpdate an existing data recordUpdate Data Record
delete-data-recordDelete a data record by idDelete Data Record

Action Implementation Wokrlofw

When implementing an action, it is recommended to use the following approach:

Try every option below in order. If earlier option does not work - move on to the next option. If you chose an option but it ended up not implement the action correctly - move on to the next option.

  • If the action potentially matches one of the Data Collection methods (i.e. list, create, etc) - find the corresponding data collection for the current integration and see if it has the corresponding method. If found - use the corresponding function type (i.e. list-data-records, create-data-record, etc)
    • Check if data collection and method have all the necessary inputs/outputs. If not - ignore this option.
  • If the action could potentially be implemented with a single API request (it is not a multi-step action) - find out if a corresponding API is available. If so - use api-request-to-external-app type.
  • If none of the above worked - use run-javascript type. Make requests to API docs to see what's available.

Using Actions

Action has only one function: run. To run an action, you need to provide an input that matches its inputSchema. As a result, you will get an output that matches its outputSchema.

All the action runs are recorded as Action Run Logs.

See full API reference here: Actions API Reference.