Skip to content

Running Workflows

VibeIQ supports a variety of methods to trigger your workflows. Each method offers a set of unique advantages to best suit distinct integration needs.

System Events

System events are the most common type of event trigger because they allow you to trigger workflows based on actions users take in VibeIQ apps.

A few examples of system events are:

  • Item creation, update, or deletion
  • Plan publish
  • Board update
  • Asset creation
  • File upload

You can simulate these kinds of events using using Manual Triggers.

External Events

External events allow external systems to trigger workflows. External events are useful for integrating with third-party services and triggering workflows from your own custom applications.

There are several kinds of external events:

Workflow Trigger Key

With this method, you assign a workflow a triggerKey. When you send an external event to the event-workflow-request endpoint, VibeIQ will execute all workflows whose triggerKey matches the key provided by the event.

This approach is recommended if you:

  • Want to trigger one or more workflows.
  • Want to monitor the result of the triggered workflows.
  • The list of workflows to be triggered is not known at the time of building the integration or may change over time.

The response will contain a list of processes that were triggered from the different workflows. You can then use the process ID to track the progress of the workflow (see Observing Workflows).

curl --request POST \
 --url https://api.vibeiq.com/prod/api/event-workflow-requests \
 --header 'Content-Type: application/json' \
 --header 'X-Api-Key: API_KEY' \
 --header 'X-Api-Org: ORG_KEY' \
 --data '{ \
     "event": { \
       "foo": "bar" \
    }, \
    "triggerKey": "systemLoad" \
}'

import { Entities } from "@contrail/sdk";
await new Entities().create({
  entityName: "event-workflow-request",
  object: {
    event: {
      foo: "bar",
    },
    triggerKey: "systemLoad",
  },
});
Sample Response
{
  "createdProcesses": [
    {
      "eventWorkflowTemplateId": "rzMLXh5NCcL9VZ43",
      "status": "PENDING",
      "triggerEvent": {
        "foo": "bar"
      },
      "taskOutputs": {},
      "createdOn": "2024-08-01T15:45:21.114Z",
      "updatedOn": "2024-08-01T15:45:21.114Z",
      "createdById": "3wedKxNFaDLbvsVM",
      "updatedById": "3wedKxNFaDLbvsVM",
      "orgId": "rhEiMLLni_2hLeGv",
      "id": "GDz6XGVWWeNIgjqz",
      "eventWorkflowTaskIds": ["t9bwl0xtLexsVkZs"],
      "messageGroupId": "org:rhEiMLLni_2hLeGv:rzMLXh5NCcL9VZ43_1",
      "templateName": "foobar",
      "templateId": "rzMLXh5NCcL9VZ43",
      "startTime": "2024-08-01T15:45:21.983Z"
    }
  ],
  "errors": []
}

App eventWorkflowTriggerKeyMapping

Each app can have a eventWorkflowTriggerKeyMapping configuration string which parses external event objects to generate a triggerKey. That parsed triggerKey then invokes any workflow with the same trigger key.

This approach may be suitable to you if:

  • Your external events are complex and varying in use case.
  • You do not have control over the shape of the external event object.
  • You are concerned with overlapping event workflows and want to segment your workflows by app.

The eventWorkflowTriggerKeyMapping configuration is set in the app's configuration file.

Example

For example, an app with with the following configuration—

eventWorkflowTriggerKeyMapping: "{details.eventType}|{actionType}"

—would transform the following event—

{
  "details": {
    "eventType": "load"
  },
  "actionType": "imageLoad"
}

—into the following triggerKey—

load|imageLoad

Any workflow that has the trigger key load|imageLoad to be invoked.

curl --request POST \
    --url https://api.vibeiq.com/prod/api/external-events \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Key: API_KEY' \
    --header 'X-Api-Org: ORG_KEY' \
    --data '{
        "details": {
            "eventType": "load"
        },
        "actionType": "imageLoad"
    }'

import { Entities } from "@contrail/sdk";
await new Entities().create({
        entityName: 'external-event',
        object: {
          details: {
            eventType: "load",
          },
          actionType: "imageLoad"
        },
    });

Webhooks

Webhooks are a special integration tool in the VibeIQ platform that allow you to hook into and react to events in external systems.

Webhooks bypass the token-based authentication protocol entirely, and really on the developer to authorize the caller accordingly. The most common pattern is using one half of a symmetrical encryption key in the header, and verifying the signature in your app’s action. Sadly, webhooks are not a standardized protocol of W3 yet, so we can only suggest best practices here. Code Safely!

Learn about creating webhooks.

Scheduled Trigger

Some workflows were born to be CRON tasks. We offer first party support for CRON scheduling of workflows out of the box.

To create a schedule for a workflow, go to Schedules in the side menu and click on the “+ New” button. Add a name, the run frequency, and select the workflow you’d like to run. Scheduled can be disabled and enabled, without deleting them.

CRON jobs are limited at a 5 minute granularity. For example a CRON of * * * * * (translates to runs every minute) still only runs once every 5 minutes.

Manual Trigger

Every workflow, regardless of the trigger type, can be ran via a manual trigger. You can pass custom event data to the manual trigger. This is useful when testing expected behavior of your workflow or debugging issues with the workflow. Manual triggeres can be done from the Admin Console event workflows page.