About workflows

A workflow is the start-to-end series of steps that your data follows as it moves through Amperity. Each workflow is unique, even if most workflows share similar paths and steps. Every step of every workflow is visible from the Workflows page. Amperity will alert you if any issues arise.

About the Workflows page

For each workflow you can view details for every step within a workflow. The Workflows page automatically refreshes every 30 seconds and updates the status for all workflows that are currently running.

The workflow tab, showing a completed workflow.

Click the name of any workflow to open a page that shows a list of tasks and the order in which they occurred.

Note

The Workflows page is available to users of Amperity who are assigned the Amp360 User policy or the DataGrid Operator policy. The Workflows page is not available to users who are only assigned the AmpIQ User policy.

Workflow alerts are not available for workflows that run in a sandbox.

About workflow alerts

A workflow alert is sent when a task within the workflow requires your attention. Each alert contains a description of what caused the alert, along with a link to the workflow in Amperity.

Workflow alerts are always available from the Recent activity pane in the Sources, Stitch, Customer 360, Destinations, and Campaigns pages, and then also from the Workflows page.

Workflow alerts may be configured to be sent to an email address or sent to a channel in a Slack workspace. Click the link in the email or Slack message to open the workflow in Amperity, and then resolve the issue(s) that caused the workflow alert.

Common resolutions

The following types of workflow resolutions are the ones you are most likely to see in your tenant:

Ignore missing file

A workflow resolution may allow temporarily ignoring missing files for any courier or courier group.

Restart workflow

A workflow resolution may allow restarting a workflow. This will rerun the workflow starting from the task that failed using the current state of your tenant, including any configuration updates that have been made.

Caution

A workflow resolution may allow you to restart a workflow after making a configuration update to your tenant.

For example, a workflow restart may allow:

  • Updating credentials

  • Updating a query

In these types of cases, the resolution allows the state of your tenant to be updated before retrying the task. This change will be applied to all future workflows.

Retry task

A workflow resolution may allow retrying a specific task in a workflow. This is useful for transient issues that should not persist from one workflow to the next.

This type of resolution will rerun the workflow from the point at which the workflow failed, starting with the same failed task and using the same inputs as those provided to the failed workflow. In many cases, this type of resolution will allow to you temporarily change the state of your tenant to help troubleshoot the cause of the workflow.

Caution

A workflow resolution may allow you to change a parameter, and then retry a task.

For example, a workflow retry may allow:

  • Re-running Stitch with an empty table to troubleshoot the source of the workflow alert

  • Changing an input to determine if the missing input is the source of the workflow alert

  • Adjusting an error threshold

In these types of cases, the resolution does not change the state of your tenant after retrying the workflow. It only changes the state of the active workflow.

You will need to update your production tenant to persist the change to support future workflows.

Skip a task

A workflow resolution may allow skipping a task. This is useful with:

  • Missing or empty tables

  • Required tables or fields are empty

  • Schema changes

  • Corrupted archives or malformed files

  • PGP errors

  • Connection errors

When a task is skipped a workflow will continue. You can work to resolve the cause of the skipped task asynchronously.

Update credentials

A workflow resolution may require updated credentials.

Note

When you configure Amperity to pull data from or send data to an upstream or downstream system, valid credentials must be provided during that configuration process.

Credentials change over time. Keys get rotated, passwords get refreshed. Credential changes are often planned in advance, but always happen outside of Amperity and may have happened in-between yesterday’s successful workflow and today’s failed workflow.

When you see a workflow resolution that requires updated credentials, verify the credentials in the upstream or downstream system, and then update Amperity for those valid credentials. Once updated you should be able to restart the workflow.

To update credentials

  1. Open the Credentials page.

  2. Review the details for the credentials used with this workflow. Update the credentials for TikTok Ads Manager if required.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Update error threshold

A workflow resolution may allow a temporary change to the error threshold that caused this workflow to fail so that this workflow may continue.

Context-specific resolutions

Many workflows have context-specific resolutions that depend on upstream and downstream tasks within the workflow, but also may depend on steps that occur upstream or downstream from Amperity. It is impossible to predict the exact workflow steps that may be shown for any particular workflow action. In addition to the most common workflow resolutions, and depending on the workflow, you may see any of the following context-specific workflow actions:

Note

The potential list of context-specific workflow actions is larger than the lists of campaign-, courier group-, destination-, scheduled orchestration group- and/or source-specific resolutions described in this section. And this list of potential context-specific workflow actions may be only partially relevant to your tenant.

For example, if your brand only uses Amazon S3 for file-based transfers, then SFTP-specific errors won’t ever be shown. If your brand sends paid media campaigns to TikTok Ads and Meta Ads Manager, but not Google Ads, then Google Ads-specific errors won’t ever be shown.

This section is a reference meant to show that Amperity provides a broad (but thorough) list of workflow actions that address the most likely causes and solutions to help your brand self-service resolutions of issues as they may arise.

Campaigns

Some common workflow actions that your brand may see when sending campaigns from Amperity include:

Mismatched datatype

A datatype defines what the value of an attribute can be. For example, an email address is a String, an order date is a Datetime, revenue is a Decimal, the number of items in an order is an Integer, and something that can be true or false is a Boolean.

It’s possible for datatypes to be mismatched, which occurs when a campaign expects a datatype to be a String, but is returned as a Decimal (or some other non-String datatype). If a mismatched datatype occurs the campaign will fail, you will receive an error message, and an alert will be sent.

To resolve this error, open the link in the alert and visit the workflow actions page. The alert and workflow actions page will both contain the error message, which will be similar to:

SYNTAX_ERROR: '=' cannot be applied to varchar, integer

Follow the steps in the workflow action to identify which table is causing the error and then either update the campaign to select attributes from a different table or work with your DataGrid Operator to fix the table.

Missing table

Amperity must be able to find the table from which campaign attributes will be pulled before sending them to your destinations. If a table is renamed or removed the campaign will fail, you will receive an error message, and an email will be sent.

To resolve this error, open the link in the alert and visit the workflow actions page. The alert and workflow actions page will both contain the error message, which will be similar to:

Cannot select data from missing tables: <table name>

Follow the steps in the workflow action to identify which table is causing the error and then either update the campaign to select attributes from a different table or work with your DataGrid Operator to fix the table.

Unresolved column name

Amperity must be able to find the column from which campaign attributes will be pulled before sending them to your destinations. If a column is renamed or removed the campaign will fail, you will receive an error message, and an alert will be sent.

To resolve this error, open the link in the alert and visit the workflow actions page. The alert and workflow actions page will both contain the error message, which will be similar to:

SYNTAX_ERROR: Column <column name> cannot be resolved

or:

COLUMN_NOT_FOUND: Column '<column name>' cannot be resolved

Follow the steps in the workflow action to identify which column is causing the error, and then work with your DataGrid Operator to fix the column name that cannot be resolved.

Campaign workflow alerts

You can configure recipients for campaign workflow alerts by adding email addresses or Slack channels to the Configure alerts dialog box on the Workflows page.

Courier groups

Some common workflow actions that your brand may see when pulling data to Amperity using courier groups include:

Duration alerts

A duration alert notifies when a courier group has run for longer than a configured amount of time. A duration alert is sent to each email address that is configured to receive email alerts for courier groups and/or to a channel in your Slack workspace.

To configure a duration alert for a courier group

  1. From the Sources page, open the menu for a courier group, and then select Edit.

  2. Enable the Warn if runtime exceeds checkbox, and then set the number of hours (or minutes) at which, when this amount of time is exceeded, a workflow alert will be sent.

  3. Click Save.

Courier group workflow alerts

You can configure recipients for courier group workflow alerts by adding email addresses or Slack channels to the Configure alerts dialog box on the Workflows page.

Databases

Some common workflow actions that your brand may see when generating databases include:

  • Errors resolving column names in tables

  • Missing tables

  • SQL query alerts (including warning and failure thresholds)

Destinations

Some destination-specific workflow actions that your brand may see when sending campaigns and orchestrations from Amperity include:

Important

This does not represent a complete list of workflow resolutions that are available for destinations.

Common to destinations

The following destination-specific workflow actions are common across destinations:

to ActiveCampaign

Amperity provides the following destination-specific workflow actions for ActiveCampaign:

to Amazon Ads

Amperity provides the following destination-specific workflow actions for Amazon Ads:

to Amazon S3

Amperity provides the following destination-specific workflow actions for Amazon S3:

to Azure Blob Storage

Amperity provides the following destination-specific workflow actions for Azure Blob Storage:

to Braze

Amperity provides the following destination-specific workflow actions for Braze:

to Cordial

Amperity provides the following destination-specific workflow actions for Cordial:

to Google Ads

Amperity provides the following destination-specific workflow actions for Google Ads:

Note

Workflow actions for Google Ads are often identical to workflow actions for DV360.

to Klaviyo

Amperity provides the following destination-specific workflow actions for Klaviyo:

to Listrak

Amperity provides the following destination-specific workflow actions for Listrak:

  • Authorization error

  • Invalid credentials

  • Invalid list name

to Meta Ads Manager

Amperity provides the following destination-specific workflow actions for Meta Ads Manager:

to Microsoft Advertising

Amperity provides the following destination-specific workflow actions for Microsoft Advertising:

to Oracle Data Cloud

Amperity provides the following destination-specific workflow actions for Oracle Data Cloud:

to Oracle DMP

Amperity provides the following destination-specific workflow actions for Oracle DMP:

to Salesforce Marketing Cloud

Amperity provides the following destination-specific workflow actions for Salesforce Marketing Cloud:

to Snapchat

Amperity provides the following destination-specific workflow actions for Snapchat:

to TikTok Ads

Amperity provides the following destination-specific workflow actions for TikTok Ads:

to Zendesk

Amperity provides the following destination-specific workflow actions for Zendesk:

Scheduled orchestration groups

Some destination-specific workflow actions that your brand may see when using scheduled orchestration groups include:

You can configure who receives alerts for orchestration group failures by editing the audiences under “Scheduled orchestration groups” in the workflow alerts dialog.

Note

Scheduled orchestration group group failure alerts are not sent for orchestrations that are run manually or for orchestrations that are configured to run after a courier group.

Orchestration workflow alerts

You can configure recipients for scheduled orchestration group workflow alerts by adding email addresses or Slack channels to the Configure alerts dialog box on the Workflows page.

Sources

Some destination-specific workflow actions that your brand may see when pulling data to Amperity using couriers and courier groups include:

Common to file-based sources

The following source-specific workflow actions are common across file-based data sources, including Amazon S3, Azure Blob Storage, Google Cloud Storage, and any SFTP site:

Note

These link to the SFTP source page, but the resolutions for common source alerts is identical across all SFTP and cloud storage data sources.

from Amazon S3

In addition to all common source workflow alerts <workflows-context-source-common>, Amperity provides the following destination-specific workflow actions for Amazon S3:

from Azure Blob Storage

In addition to all common source workflow alerts <workflows-context-source-common>, Amperity provides the following destination-specific workflow actions for Azure Blob Storage:

from Google Cloud Storage

In addition to all common source workflow alerts <workflows-context-source-common>, Amperity provides the following destination-specific workflow actions for Google Cloud Storage:

from SFTP

In addition to all common source workflow alerts <workflows-context-source-common>, Amperity provides the following destination-specific workflow actions for SFTP sites:

Stitch

If too many Amperity IDs change from one Stitch run to the next, Stitch will return a workflow alert. The cause of a significant number of Amperity ID changes is often related to a significant change to one (or more) data sources, such as an update that adds a customer key or foreign key to one (or more) feed schemas.

If your brand is making a series of planned updates and these additions are expected, Stitch may be configured to ignore jitter alerts.

How-tos

This section describes tasks related to managing workflow actions in Amperity:

Configure duration alerts

A duration alert notifies you when a courier group has run for longer than the configured amount of time.

for courier groups

Use a workflow alert to be notified when a courier group runs for longer than a configured amount of time. An alert will be sent to each email address that is configured to receive email alerts for courier groups.

To configure a duration alert for a courier group

  1. From the Sources page, open the menu for a courier group, and then select Edit.

  2. Enable the Warn if runtime succeeds checkbox, and then set the number of hours (or minutes) at which, when the configured amount of time is exceeded, a workflow alert will be sent.

    Enable duration alerts for workflows.
  3. Click Save.

Filter workflows

You can filter the list of workflows from the Workflows page. Click Show filters to open the Filters pane, and then select one (or more) values from the following dropdown lists:

Tip

Combine the filters with search functionality to show more specific filtering results.

Show the workflow filters pane, and then set the filter type to “Campaign” to filter the list of workflows to only show campaigns.

Search “dec” to filter to only campaign workflow that occurred in December.

by status

You may filter workflows by workflow type. Use the Status filter, and then select one (or more) of the following options:

  • Failed

  • Stopped

  • Succeeded

by type

You may filter workflows by workflow type. Use the Type filter, and then select one (or more) of the following options:

  • Campaign send

  • CCPA delete. This type supports privacy rights workflows, including data subject access request (DSAR), the California Consumer Privacy Act (CCPA), and General Data Protection Regulation (GDPR).

  • Courier

  • Courier group

  • Data refresh

  • Ingest

  • Input validation report update

  • Manual index run

by user

You may filter workflows by the users who started the workflow. Use the Started by filter, and then select one (or more) users from the list.

Hide skipped tasks

Some workflows contain a large number of skipped tasks. You can hide skipped tasks when reviewing the list of individual tasks that occurred during a workflow.

To hide skipped tasks

  1. From the Workflows page, select a workflow.

  2. On the individual workflow’s page, enable the Hide skipped tasks option.

Open workflows

You can access workflow alerts from the following locations:

from email alerts

When email workflow alerts are enabled for your tenant, a user who receives that alert and who can log into Amperity may click the link in the email to open Amperity and resolve the workflow.

Tip

Users who do not have permission to log in to Amperity may reply to the email workflow alert to open a support ticket.

from Recent activity panes

The Sources, Stitch, Customer 360, Campaigns, and Destinations page will show workflow alerts when a task requires your attention. You can also access all workflows from the Workflows page.

To open workflows from Recent activity panes

  1. Open the Sources, Stitch, Customer 360, Campaigns, or Destinations page.

  2. Open the Recent activity pane.

  3. Browse or search the notifications.

  4. A notification that contains a workflow action will be highlighted. Click the “View workflow” link to open the workflow.

    Tip

    When workflow resolutions are available, an alert is shown with a button named Show resolutions.

from Slack alerts

From a Slack channel in your brand’s Slack workspace, click the link in the message to open the workflow.

Note

You may be required to log in to Amperity before you can view the workflow.

from the Workflows page

The Workflows page contains a list of all of the workflows that have occurred in your tenant. You can filter the workflows using search, from the filters pane, or by sorting the columns (ascending or descending) within the list of workflows.

To open workflows from the Workflows page

  1. Open the Workflows page.

  2. Open the Recent activity pane.

  3. Browse or search the list of workflows.

  4. A workflow that contains a workflow action will have a “Failed” workflow type. Open a failed workflow.

    Tip

    When workflow resolutions are available, an alert is shown with a button named Show resolutions.

Resolve workflow

Some workflows may have errors that will prevent the workflow from completing successfully. Use the Workflows page to resolve workflows that failed by reviewing options for resolution, and then choosing one of those options or choosing to restart the workflow.

The workflow tab, showing a workflow with errors.

To resolve workflow errors

  1. From the    menu in the top navigation bar select Workflow. This opens the Workflow page.

  2. Select a workflow with a “ Failed” status.

  3. Click Show Resolutions, review your options, and then select a resolution. Work through any steps that may be required by the selected resolution.

  4. Click Resolve.

Search workflows

You can search within the list of workflows from the search box at the top of the Workflows page. Use the search functionality as a way of filtering the list down to a smaller list of individual workflows or to find a specific workflow.

For example:

  • “failed” will filter to only failed workflows

  • “dec” will filter to all workflows that occurred in December, along with any workflows that have “dec” in the workflow name

Tip

Combine the search functionality with filters to show more specific search results.

Search “dec” to filter to all workflows that occurred in December.

Show the workflow filters pane, and then set the filter type to “Campaign” to filter the list of workflows to only show campaigns that occurred in December.

Send alerts to email addresses

You can configure Amperity to send workflow alerts to individual email addresses or group aliases as long as the domain that is associated with those email addresses is configured to be an allowed domain in Amperity.

Email workflow alerts are sent from “notifications@amperity.com”. A reply to the emailed workflow alert will reply to “support@amperity.com”, after which a support ticket is opened automatically.

Important

Email addresses that receive workflow alerts must belong to an allowed domain in Amperity. Allowed domains are configured from the Users & Activity tab.

Click Add user, and then in the dialog box that opens under Allowed domains, review the list of domains. If the email domain that your brand requires for sending email workflow alerts is not listed, click Request domain.

The email address to which workflow alerts are sent is not required to exist as a user in Amperity.

To configure alerts for email addresses

  1. From the Workflows page, click Configure alerts.

  2. In the Configure alerts dialog box, under Campaigns, Courier groups, or Scheduled orchestration groups, type an email address in the Emails box, and then hit the RETURN button on your keyboard.

    You may enter more than one email address.

  3. Click Save.

Send alerts to Slack channels

You can configure Amperity to send workflow alerts to channels in your brand’s Slack workspace. This configuration requires the following steps:

  1. Authorize your Slack workspace

  2. Configure one (or more) Slack channels for workflow alerts

Authorize workspace

You must authorize Amperity to be able to send workflow alerts to your Slack workspace. This authorization occurs within Slack.

Important

Only one Slack workspace may be authorized for your tenant.

Amperity only sends workflow alerts to the configured channels. Amperity does not send direct messages (“@”).

To authorize a Slack workspace

  1. From the Users & Activity page, under Slack integration click Connect Slack workspace.

  2. This opens a Slack authorization page with a message similar to:

    Amperity is requesting permission to access the [your-brand's-workspace] Slack workspace.
    

    Click Allow to enable sending workflow alerts to your brand’s Slack workspace. You can configure specific channels after you have authorized the Slack workspace.

  3. Click Save.

Configure channels

You can configure each workflow alert type to send alerts to one (or more) channels in your brand’s Slack workspace. You may configure more than one channel to receive alerts for the same workflow type. You cannot configure workflow alerts to be sent as a direct message in Slack to a single individual.

Tip

Create a dedicated channel (or set of channels) in your brand’s Slack workspace to which workflow alerts are sent. Channels to which workflow alerts are sent may be public or private.

For most use cases, a single “#amperity-workflow-alerts” channel is sufficient, but some use cases may prefer to have dedicated channels for courier groups and campaigns.

To configure one (or more) Slack channels

  1. From the Workflows page, click Configure alerts.

  2. In the Configure alerts dialog box, under Campaigns, Courier groups, and Scheduled orchestration groups, add the name of the Slack channel to which you want to send workflow alerts, and then hit the RETURN button on your keyboard.

    You may enter more than one Slack channel for each workflow alert type and each workflow alert type may be configured for their own Slack channels.

  3. Click Save.

Disconnect workspace

You can disconnect a Slack workspace from the Users & Activity page. Select the    menu icon for the configured workspace, select Disconnect, and then confirm that you want to disconnect the workspace.

Stop a workflow

You can stop a workflow that is actively running from one of the following locations:

  1. The Stop workflow button in the top right of an individual workflow’s details page.

  2. The Stop workflow option available from the    menu on the Workflows page.

When a workflow is stopped while a task is running, it will initially enter a “Stopping” state while the task is being stopped, after which the workflow will move to a “Stopped” state. If a workflow is stopped while no tasks are running it will immediately move to a “Stopped” state.

A workflow alert is sent to all users who are subscribed to workflow alerts.

Important

Orchestration tasks that have started running within a workflow cannot be stopped because of external dependencies that each orchestration has with a downstream system. Orchestration tasks that have started may run to completion even when the workflow to which they are associated is stopped.

View all workflows

The Workflows page is available to users of Amperity who are assigned the Amp360 User policy or the DataGrid Operator policy. The Workflows page is not available to users who are only assigned the AmpIQ User policy.

Important

Workflow alerts are not available for workflows that run in a sandbox.

View error details

You can view error details for a workflow. Open an individual workflow, then from a row with an error or an issue, select the    menu icon, and then choose View error details. This opens a dialog box that contains the full error message.

Note

Errors are often more directly actionable using a workflow resolution. In some situations, viewing the full error message can help troubleshoot the root cause of an error.

View inputs and outputs

You can view the inputs and outputs for a workflow. Inputs show all of the information that was submitted to a task, such as the names of the service, the ID for the file(s) that were submitted to the task, downstream dependencies (such as list names or attribute names that are required by a destination), and so on. The inputs and outputs for an individual task within a workflow are unique to that workflow.

To view inputs and outputs for a workflow. Open an individual workflow, then from a row within the workflow, select the    menu icon, and then choose View inputs/outputs. This opens a dialog box that contains all of the inputs and outputs for that task.

View workflow details

Workflow details are available from the Workflows page. Click the name of the workflow or from the    menu icon for workflow click View details.

Details include the list of individual tasks that occurred during the workflow, the workflow’s current status, type of workflow, who started the workflow, the time at which the workflow started, and the duration of the workflow (from start to finish).

View resolutions

Workflow resolutions are available after accessing a workflow alert from any of the following locations:

To view workflow resolutions

  1. Open the workflow from the recent activity pane, list of workflows, email, or Slack message.

    This will open Amperity. You may be required to log in.

  2. On the individual workflow’s page, when workflow resolutions are available, an alert is shown with a button named Show resolutions.

    This opens the Resolve error dialog for the workflow.

    A list of options is available for any failed workflow.

    The workflow tab, showing a workflow with errors.
  3. Each set of workflow resolutions is specific to the workflow.

    Common resolutions include restarting the workflow, retrying a specific task in the workflow, or verifying and then updating credentials.

    Resolutions can also be context-specific, including campaigns, courier groups, destinations, scheduled orchestration groups, and sources.

    Review the list of options, and then determine the resolution.

  4. Select one of the resolution options, and then click Resolve.