Run action sequences automatically (Beta)

Run action sequences automatically based on a schedule or in response to an incoming webhook request. Automated action sequences can send notifications, write to input tables, respond to events from external systems, etc., without requiring a user to open or interact with the workbook.

This document explains how to configure action sequences to run automatically, either on a schedule or with a webhook trigger, and how to view details about all automated action sequences you published. For more information about actions in Sigma, see Intro to actions.

Requirements

The ability to create automated action sequences requires the following:

• You must be assigned an account type with the Full explore or Create, edit, and publish workbooks permission enabled.
• You must be the workbook owner or be granted Can explore¹ or Can edit access to the workbook.
• To configure a webhook trigger, your Sigma organization must have a REST API key owned by the user who creates the webhook trigger action. The external system uses this key to authenticate requests to the webhook endpoint. For more information, see Generate API client credentials.

1If you’re granted Can explore access to the workbook, you can only create automated action sequences in custom and saved views, and they do not run. See Limitations for more information.

About automated action sequences

Automated action sequences are configured at the workbook level and can be used to automatically trigger workflows that perform data operations and integrations without direct UI interaction. You can run an automated action sequence using one of the following triggers:

• Schedule: The sequence runs at specific intervals (daily, weekly, monthly, or on a custom cron schedule).
• Webhook: The sequence runs when Sigma receives a request from an external system to the webhook endpoint.

The following actions can be automated:

• Notifications and exports
• Input table row changes (insert, update, and delete) (see Limitations)
• API calls
• Stored procedure calls
• Python element execution
• Sigma agent calls

Automated action sequences also support conditional if/else statements, and you can configure multiple automated action sequences with different triggers and frequencies.

Limitations

• You cannot use automated action sequences to trigger UI-level changes, like setting a control value, opening a modal, navigating to a workbook page, etc.
• Automated action sequences can only modify input tables with the data entry permission set to allow edits in the published version of a workbook. If an existing target input table is updated to only allow edits in the workbook draft, the automated action sequence cannot run successfully (see Error status details in Last run statuses). If the input table is updated to once again allow edits in the published version, the automated action sequence runs successfully.
• A Call agent action can only be automated if the referenced agent uses backend-compatible action tools. If the agent includes a tool that performs a UI-level effect, such as setting a control value or opening a URL, Sigma surfaces a warning in the action configuration modal.
• Automated action sequences configured in custom or saved views do not run. Sigma allows you to create automated action sequences in a view with the intent of saving the view as a new workbook, where the sequences can be published and run as expected.

Create a scheduled action sequence

Configure an automated action sequence that runs on a recurring schedule.

1. Open a workbook draft.

   You can also create a custom view or open a saved view, but note that any automated action sequences you configure in the view do not run (see Limitations).

2. Go to the page-level editor panel and select the Actions tab.

   Alternatively, open the workbook menu and select Edit > Show automated actions.

   The editor panel is page-specific when no elements are selected. When one or more elements are already selected, click the background of the workbook canvas or select a page tab to open the editor panel for that page.

3. In the Actions panel, click Add action sequence to create a new sequence. To edit an existing sequence, skip to step 5.

4. In the action configuration popover, select an action type and configure the effect. For a list of action types and detailed information about how to configure them, see Action effects.

   To configure additional actions in the same sequence, click Add action, then repeat this step.

5. In the sequence card, click the Select a schedule field, then configure the schedule frequency. You can choose to run the sequence daily, weekly, monthly, or on a custom cron schedule. You can also change the schedule time zone.

6. In the workbook header, click Publish.

   Sigma only runs automated action sequences that are saved to the published version of a workbook.

7. To verify that the sequence is scheduled to run, check the Automated actions page in your user profile. For more information, see View all automated action sequences you’ve scheduled.

Create a webhook-triggered action sequence

Configure an automated action sequence that runs in response to an incoming webhook request.

1. Open a workbook draft.

   You can also create a custom view or open a saved view, but note that any automated action sequences you configure in the view do not run (see Limitations).

2. Go to the page-level editor panel and select the Actions tab.

   Alternatively, open the workbook menu and select Edit > Show automated actions.

3. In the Actions panel, click Add action sequence to create a new sequence. To edit an existing sequence, skip to step 5.

4. In the action configuration popover, select an action type and configure the effect. For a list of action types and detailed information about how to configure them, see Action effects.

   To configure additional actions in the same sequence, click Add action, then repeat this step.

5. In the sequence card, click the At scheduled time field and then select On webhook received from the dropdown.

6. In the webhook configuration, define the request parameters that external services can pass when they invoke the webhook:

   1. Click Add variable and enter a name for the parameter.
   2. Select a parameter type. For supported types, see Supported webhook parameter types.
   3. Configure the parameter to be Required or Optional.
   4. Repeat to add additional parameters as needed.

   You can reference webhook parameters in subsequent actions in the sequence as action variables. When configuring an action effect, select Action variable as the value source, then choose the webhook parameter.

7. Configure how external systems authenticate webhook requests. For more information, see Authenticate webhook requests.

8. In the workbook header, click Publish.

   Sigma only runs automated action sequences that are saved to the published version of a workbook.

9. To verify that the sequence is configured, check the Automated actions page in your user profile. For more information, see View all automated action sequences you’ve published.

10. Copy the webhook URL displayed. External systems can send POST requests to this URL to trigger the sequence. The URL includes the workbook ID and sequence ID for the automated action sequence. For more details, see Invoke a webhook-triggered action sequence.

Supported webhook parameter types

When you configure a webhook trigger, you can define parameters with the following types:

The JSON keys in the webhook request body must match the parameter names you define. To retrieve the expected request body schema for a published sequence, call the Retrieve webhook message schema endpoint.

Authenticate webhook requests

External systems must authenticate when they invoke a webhook. You can authenticate requests using REST API credentials or HMAC signature verification.

Authenticate with REST API credentials

By default, webhook requests authenticate using a REST API access token. The external system obtains a token using your organization’s client ID and client secret, then includes the token in the Authorization header of the webhook request.

To configure REST API authentication, your organization must have REST API client credentials. For more information, see Generate API client credentials and Get started with the Sigma REST API.

Authenticate with HMAC signatures

For action sequences with an On webhook received trigger, you can confirm that messages originate from a trusted party and have not been tampered with using a hash-based message authentication code (HMAC) signature.

HMAC signature authentication uses a shared secret and a hashing algorithm to sign and verify messages. The sender hashes the message together with the shared secret to produce a signature, then sends the signature alongside the message. Upon receipt, Sigma re-computes the signature using the same secret and algorithm and compares it to the one sent. A match confirms the message came from a party with access to the secret and that it has not been tampered with in transit.

While configuring an automated action with an On webhook received trigger:

1. For Authentication, select HMAC signature.

2. In the Provider preset dropdown, select a provider or select Custom to configure fields manually. If you select a provider, Sigma fills in the verification fields with that provider’s known signing scheme.

   Selecting a provider preset overwrites the other verification fields. Editing any field afterward sets the preset back to Custom.

3. Configure the verification fields to determine the hashing algorithm, payload definition, and other signature parameters. For more information, see Signature verification fields.

4. In the Signing secret field, paste the shared secret from your provider, then select Set secret. The secret is encrypted before storage.

   Sigma never returns the secret in the UI. Store the signing secret securely and rotate it if it is exposed.

5. Copy the webhook URL and configure your provider to send signed POST requests to it.

Signature verification fields

When configuring an action sequence with an On webhook received trigger and the HMAC signature authentication method, you can configure the following verification fields to construct the signature:

Rotate the signing secret

To rotate the signing secret, paste the new secret in the Signing secret field and select Set secret. The new secret replaces the old one. Rotating the secret is independent of publishing the workbook.

Invoke a webhook-triggered action sequence

After you publish the workbook, an external system can invoke the webhook to run the action sequence. Sigma validates the request, then enqueues the sequence to run asynchronously. The webhook returns a 202 Accepted response with an action trace ID; it does not wait for the sequence to finish.

1. Obtain a REST API access token using your organization’s client ID and client secret. For more information, see Get access token and Get started with the Sigma REST API.

2. Send a POST request to the webhook URL with a JSON body that matches the parameters you configured. Include the access token in the Authorization header.

   $
   curl -X POST "https://api.sigmacomputing.com/v2/webhooks/{workbookId}/{sequenceId}" \
   >
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
   >
     -H "Content-Type: application/json" \
   >
     -d '{
   >
       "parameter_name": "example value"
   >
     }'

   Replace {workbookId} and {sequenceId} with the IDs from your webhook URL. Replace parameter_name and its value with the parameters you defined for the sequence.

   For endpoint details and response format, see Send to a webhook.

View all automated action sequences you’ve published

Your user profile contains information about all automated action sequences you own. For each sequence, you can view its name, workbook name, trigger type, last run time, last run status, and sequence status.

You own a sequence when you publish it, and ownership transfers if another user publishes a change to its name, schedule, or status. The list does not include sequences owned by other users, even if they are sequences you originally configured, previously published changes to, or can access in the workbooks containing them.

If the list does not include a sequence you expect to see, check that you own the sequence, saved it to the published version of the workbook, and did not configure it in a custom or saved view.

1. Use one of the following methods to access the list of automated action sequences in your user profile:

   • Access the list from your Home page:
     1. From your Home page, click your user avatar and select Profile from the user menu.
     2. In the left navigation of your profile, select Automated actions, then browse or search for specific automated action sequences.
   • Access the list from a workbook:
     1. Open the workbook menu and select Edit > Show automated actions.
     2. In the Actions panel, click () More and select View all your automated actions.
     3. Your profile opens to the Automated actions page where you can browse or search for specific automated action sequences.

2. View the following automated action sequence details:

   • Sequence/Document: The name of the sequence and the workbook that contains the sequence.
   • Trigger: The type of trigger (Scheduled or Webhook). For schedule triggers, the schedule or interval is also displayed. For webhook triggers, the webhook endpoint URL is displayed.
   • Last run time: The date and time the sequence last ran.
   • Last run status: The state or outcome of the sequence’s most recent run. For definitions, see Last run statuses.
   • Sequence status: The sequence’s current operational state, which determines if it runs when the trigger event occurs. For definitions, see Sequence statuses.

3. (Optional) To view a more focused list of automated action sequences, use the search bar to search by sequence name. You can also filter the list by trigger type, last run status, sequence status, and scheduled run time.

4. (Optional) To view the run history of a specific automated action sequence, click its row in the list. The detail page lists each run with its run status, run time, and status details, including an action trace ID for failed runs.

5. (Optional) To open the workbook and edit the automated action sequence, click the workbook name.

Automated action sequence statuses

The Automated actions list displays the Last run status and Sequence status for each automated action sequence. The following tables list all possible statuses with their corresponding icons and definitions.

Last run statuses

2Sigma sends an email alert to you (the owner of the sequence) when, within any 7-day period, an automated action sequence fails at least 3 times and has a failure rate of 70% or higher.

Sequence statuses

Resume a suspended sequence

When a sequence is suspended due to repeated errors, it no longer runs when the trigger event occurs. You can resume a suspended sequence in the following ways:

• Publish the workbook: Sigma automatically resumes a suspended sequence when you publish the workbook it’s configured in.
• Resume manually: In the page-level Actions panel, click More next to the sequence name, then select Resume sequence.