Pipeline objects

Objects and samples for /pipelines (Automation) endpoints.

Event identifier

Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.

Jump to examples ↓

One of

string
Triggers the pipeline whenever an event of the following types occurs. first_open and first_opt_in are only available in immediate triggers.
- open events occur whenever your audience opens your app.
- first_open events occur when your audience opens your app for the first time.
- first_opt_in events represent the first time your audience opts into email (commercial only), sms, or open notifications.
- double_opt_in events occur when a new email channel registration occurs with the "opt_in_mode": "double" parameter.
- When used without a value, region_entered and region_exited types cause the trigger to fire whenever an audience member enters or exits any region.
Compound event identifier object
A compound event identifier is a JSON dictionary with a single key indicating the event type, and a value specifying the specific parameter to match on.
OBJECT PROPERTIES
- activation_time string
  The date-time indicating a time at which the trigger will automatically become active.
- condition array[object]
  A single condition set or array of condition sets. It is a collection of one or more conditions and an operator for combining them, in the case that there are multiple conditions. A condition set follows the same general syntax as a compound selector. It is a JSON dictionary with a single key indicating the operator. The key’s value is an array of one or more condition objects. Taken together, the operator and set of conditions form a boolean expression which must evaluate to true for a pipeline to be activated and its outcomes executed. Valid operators for a condition set are and and or. This field is evaluated before the pipeline is entered and only evaluated against events for the triggers on which they are set, which is noticeable when using multiple triggers.
- custom_event object<Event selector>
  A Custom Event selector is an event selector that describes the specific criteria a Custom Event must fulfill in order to trigger an automation. Supported Custom Event fields in the default scope are "name" (string) and ["value"]. Custom Events also have a map of properties that may also be selected under the "properties" scope. Values for the "properties" key may be string, boolean, number, or an array of strings.
  An event selector is a JSON dictionary consisting of a set of (possibly negated) event-specific selectors joined together by a doubly-nested set of operators, in disjunctive or conjunctive normal form. That is, only queries of the pattern “single AND of ORs” or “single OR of ANDs” are allowed (no further nesting is allowed), and only leaf nodes of such queries may be negated. Elision of single-value operators is allowed for the sake of brevity/usability on writes, but responses from our servers will always be fully qualified.
  Event-specific selectors are allowed to reference any field in a potentially matching event, at any nesting depth therein, with the goal of matching their structure to existing API formats, both inbound and outbound.
  Top-level operator dictionaries are of the form {"and": []} or {"or": []}, where the members of the array will be operator dictionaries of the other type (“AND of ORs” or “OR of ANDs”), or if eliding on ingress, negation operator dictionaries or event-specific selectors.
  Negation operator dictionaries are of the form {"not": {}} where the inner object is strictly an event-specific selector. I.e., only leaf nodes may be negated, in keeping with the tenets of conjunctive/disjunctive normal form.
- deactivation_time string
  The date-time indicating a time at which the trigger will automatically become inactive.
- double_opt_in object
  Matches when a double opt-in registration matching the specified criteria was made for a channel. A double opt-in selector is a complex selector that describes the specific criteria a double opt-in registration must fulfill in order for it to qualify as a match for triggering pipelines. The only supported value for scope is properties. All value selectors, except for date, are supported. The key object supports a simple string to select the value of a top-level key or any JsonPath query for maximum flexibility. For situations where a compound event identifier is necessary (e.g., when including trigger_id), but no selector is present or desired, an empty object {} is allowed. "immediate_trigger": "double_opt_in" and "immediate_trigger": { "id": "8e1a61d7-7e9d-4870-a548-2d4d6eb6405f", "double_opt_in": {} } are equivalent (assuming the ID is correct).
  One of
  - Complex Event Selector
    An event selector is a JSON dictionary consisting of a set of (possibly negated) event-specific selectors joined together by a doubly-nested set of operators, in disjunctive or conjunctive normal form. That is, only queries of the pattern “single AND of ORs” or “single OR of ANDs” are allowed (no further nesting is allowed), and only leaf nodes of such queries may be negated. Elision of single-value operators is allowed for the sake of brevity/usability on writes, but responses from our servers will always be fully qualified.
    Event-specific selectors are allowed to reference any field in a potentially matching event, at any nesting depth therein, with the goal of matching their structure to existing API formats, both inbound and outbound.
    Top-level operator dictionaries are of the form {"and": []} or {"or": []}, where the members of the array will be operator dictionaries of the other type (“AND of ORs” or “OR of ANDs”), or if eliding on ingress, negation operator dictionaries or event-specific selectors.
    Negation operator dictionaries are of the form {"not": {}} where the inner object is strictly an event-specific selector. I.e., only leaf nodes may be negated, in keeping with the tenets of conjunctive/disjunctive normal form.
- pipeline_event object
  A JSON dictionary describing which pipeline events for a specified pipeline should be considered a match and should therefore trigger the pipeline.
  OBJECT PROPERTIES
  - cancellation_reason string
    For cancelled type selectors, the specific cancellation reason to consider for triggering. All others will be ignored.
    Possible values: cancellation_trigger, timing, condition, rewritten, rate_limit
  - message_id string
    Unique identifier for an In-App Automation. This is required when type is in_app_fallback.
  - pipeline_id string
    The UUID of a pipeline whose events should be considered. If this is not provided, then trigger_ids must be provided. This is not required if message_id is provided.
  - trigger_ids array[string]
    The list of trigger IDs that should be considered. If this is not provided, then pipeline_id must be provided. This is not required if message_id is provided.
  - type stringREQUIRED
    The type of event for the specified pipeline which should be considered.
    Possible values: entered, cancelled, fulfilled, in_app_fallback
- region_entered object
  A region selector is an event selector that describes the specific criteria a region must fulfill in order to qualify as a match (for triggering pipelines).
  Supported default scope region keys are currently: name (string) and region_id (string).
  Under the source_info scope, we support the following key: region_id (string).
  We also have support for the arbitrary scope attributes, which has no key restrictions because it is user-supplied in its entirety.
- region_exited object
  A region selector is an event selector that describes the specific criteria a region must fulfill in order to qualify as a match (for triggering pipelines).
  Supported default scope region keys are currently: name (string) and region_id (string).
  Under the source_info scope, we support the following key: region_id (string).
  We also have support for the arbitrary scope attributes, which has no key restrictions because it is user-supplied in its entirety.
- subscription_added string
  Matches when the specified subscription list is added. The value of the identifier is a simple string identifying the subscription list.
- subscription_removed string
  Matches when the specified subscription list is removed. The value of the identifier is a simple string identifying the subscription list.
- tag_added object
  Defines a tag selector.
  One of
  - OBJECT PROPERTIES
    - group string
      The tag group. If you do not specify a group, Airship uses the default device tag group; this group is represented by a channel’s tags array rather than the tag_groups object.
    - tag stringREQUIRED
      The tag.
  - string
    The device tag.
- tag_removed object
  Defines a tag selector.
  One of
  - OBJECT PROPERTIES
    - group string
      The tag group. If you do not specify a group, Airship uses the default device tag group; this group is represented by a channel’s tags array rather than the tag_groups object.
    - tag stringREQUIRED
      The tag.
  - string
    The device tag.

Used in:

Examples

{
  "event": "open"
}

{
  "tag_added": "cool_user"
}

{
  "custom_event": {
    "key": "name",
    "value": {
      "equals": "christmas"
    }
  }
}

Event selector

An event selector is a JSON dictionary consisting of a set of (possibly negated) event-specific selectors joined together by a doubly-nested set of operators, in disjunctive or conjunctive normal form. That is, only queries of the pattern “single AND of ORs” or “single OR of ANDs” are allowed (no further nesting is allowed), and only leaf nodes of such queries may be negated. Elision of single-value operators is allowed for the sake of brevity/usability on writes, but responses from our servers will always be fully qualified.

Event-specific selectors are allowed to reference any field in a potentially matching event, at any nesting depth therein, with the goal of matching their structure to existing API formats, both inbound and outbound.

Top-level operator dictionaries are of the form {"and": []} or {"or": []}, where the members of the array will be operator dictionaries of the other type (“AND of ORs” or “OR of ANDs”), or if eliding on ingress, negation operator dictionaries or event-specific selectors.

Negation operator dictionaries are of the form {"not": {}} where the inner object is strictly an event-specific selector. I.e., only leaf nodes may be negated, in keeping with the tenets of conjunctive/disjunctive normal form.

Jump to examples ↓

One of

Event value selector object
Defines an event value to match.
OBJECT PROPERTIES
- key stringREQUIRED
  The field you want to match a value against.
- scope string
  Specifies an inner-dictionary on a potentially-matching event.
- value objectREQUIRED
  Specifies the criteria qualifying a value as a match. Integer values support up to 6 digits of decimal precision. You can specify a range of values using at_least/greater_than and at_most/less_than, but the value for at_least/greater_than must be less than the value of at_most/less_than or your request will return an error.
  OBJECT PROPERTIES
  - array_contains string
    Matches if an array contains the specified string value.
  - at_least integer
    Matches values greater than the specified value.
  - at_most integer
    Matches values less than the specified value.
  - equals object
    Specifies an exact match. String values are case sensitive and must match exactly.
    Any of
    - string
  - greater_than integer
    Matches values greater than the specified value.
  - less_than integer
    Matches values less than the specified value.
AND selector object
AND selector
OBJECT PROPERTIES
- and array
OR selector object
OR selector
OBJECT PROPERTIES
- or array
NOT selector object
NOT selector
OBJECT PROPERTIES
- not object
  Defines an event value to match.
  OBJECT PROPERTIES
  - key stringREQUIRED
    The field you want to match a value against.
  - scope string
    Specifies an inner-dictionary on a potentially-matching event.
  - value objectREQUIRED
    Specifies the criteria qualifying a value as a match. Integer values support up to 6 digits of decimal precision. You can specify a range of values using at_least/greater_than and at_most/less_than, but the value for at_least/greater_than must be less than the value of at_most/less_than or your request will return an error.
    OBJECT PROPERTIES
    - array_contains string
      Matches if an array contains the specified string value.
    - at_least integer
      Matches values greater than the specified value.
    - at_most integer
      Matches values less than the specified value.
    - equals object
      Specifies an exact match. String values are case sensitive and must match exactly.
      Any of
      - string
    - greater_than integer
      Matches values greater than the specified value.
    - less_than integer
      Matches values less than the specified value.

Used in:

Examples

{
   "and": [
      {
         "key": "name",
         "value": {
            "equals": "POWER_LEVEL"
         }
      },
      {
         "key": "value",
         "value": {
            "greater_than": 9000,
            "at_most": 10000
         }
      }
   ]
}

Pipeline object

A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

Jump to examples ↓

OBJECT PROPERTIES

activation_time string
The date-time when the pipeline becomes active and begins processing triggers and issuing push notifications.
If this value is in the future, the pipeline’s status is pending.
cancellation_trigger object
One of
- Event Identifier
  Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.
- array<ref>
  Defines event conditions that will cancel the fulfillment of a pipeline. If a pipeline has multiple cancellation triggers, they’re combined via an implicit OR operation. Any one of the triggers will cancel the fulfillment of the pipeline. Cancellation triggers are only allowed when a pipeline has no historical triggers and it is possible for a pipeline’s fulfillment to be delayed using the Timing Object. The first_open event identifier is not valid as a cancellation trigger.
condition array[object]
One or more conditions, combined by operators. A condition set may contain a maximum of 20 conditions. Taken together, the operator and set of conditions form a boolean expression which must evaluate to true for a pipeline to be activated and its outcomes executed. Valid operators for a condition set are and and or. Nesting of operators is not supported within a condition set, i.e., you may not combine and logic with or logic.
constraint array[object]
An array of rate objects determining the maximum number of messages each audience member can receive over a period of time. You can set a lifetimes constraint as well, limiting a pipeline to an absolute maximum number of messages ever.
creation_time string
Read-only timestamp. The date-time indicating the time that the pipeline was initially created. This is a read-only field that is present on GET responses. If it is included in a POST or PUT request it will be ignored.
deactivation_time string
The date-time when the pipeline becomes inactive and quits processing triggers and issuing push notifications.
If this value is in the past, the pipeline’s status is completed.
enabled booleanREQUIRED
A boolean value indicating whether or not the pipeline is active.
historical_trigger object
One of
- Historical trigger object object
  Defines a condition that matches against event data trended over time. It consists of an event identifier, a time period, and a matching operator with a value indicating the number of occurrences of the event. The operator indicates whether to match greater than, less than, or exactly the number of occurrences specified. Valid matching operators are equals, greater_than, or less_than. The matching window is specified in days, with an upper limit of 90 days. A historical trigger will be periodically evaluated against the event history for every active device belonging to the application. Pipelines with historical triggers cannot also have a timing object.
  OBJECT PROPERTIES
  - creation_time string
    A date-time returned when getting a pipeline with a historical_trigger. Include this field in a PUT request to ensure that the historical_trigger is not reset.
  - days integer
    A time period key. An integer indicating the length of the matching window, in days. Maximum 90 days.
  - equals integer
    A matching operator. Since we are measuring inactivity with the historical trigger object, 0 is the only value supported with the equals operator, i.e., we are measuring number of events in a defined time window. Any number higher than zero would therefore represent activity.
  - event object<Event identifier>
    Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.
  - greater_than integer
    A matching operator. Specifies the number of events that must be targeted before the historical trigger will fire.
  - less_than integer
    A matching operator. Specifies the number of events that must be targeted before the historical trigger will fire.
- array<object>
  Historical trigger objects are limited to inactivity triggers, which trigger when a user fails to open the app within a defined number of days.
immediate_trigger object
One of
- Event Identifier
  Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.
- array<ref>
  Defines a condition that activates a trigger immediately when an event matching it occurs. If a pipeline has multiple immediate triggers, they’re combined via an implicit OR operation. Any one of the triggers firing will activate the pipeline. Immediate triggers are all event identifiers. first_open is a valid event identifier for immediate triggers. However, events within the trigger support AND and OR compound selection.
last_modified_time string
Read-only timestamp. The date-timeindicating the time that the pipeline was last modified. This is a read-only field that is present on GET responses. If it is included in a POST or PUT request it will be ignored.
name string
A descriptive name for the pipeline.
outcome objectREQUIRED
One of
- Outcome object object
  An outcome object contains a single push object where the audience field must be set to triggered.
  OBJECT PROPERTIES
  - push objectREQUIRED
    A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.
    OBJECT PROPERTIES
    - audience stringREQUIRED
      A special selector used in Pipelines to indicate that the audience of the push is composed of the device or devices that activated the trigger. See Pipeline objects for more information.
      Possible values: triggered
    - campaigns object<Campaigns object>
      An object specifying custom campaign categories related to the notification.
    - device_types array[string]REQUIRED
      An array containing one or more strings identifying targeted platforms.
    - in_app object<In-app message>
      A JSON object describing an in-app message payload.
    - message object
      One of
      - Message Object
        A Message Center message.
      - Message Object With Template
        Use a template with a message center message. You can reference a template by ID, or use {{handlebars}} directly in your message.
    - notification object<Notification object>
      The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.
    - options object<Push options>
      A JSON dictionary for specifying non-payload options related to the delivery of the push.
    - orchestration object
      An object used to indicate the strategy to employ when deciding which channels to target for a contact. An orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload, it will override the configured default value. The overall default strategy is fan_out.
      OBJECT PROPERTIES
      - channel_priority array[string]
        An array of channel types in priority order. Required if type is set to channel_priority.
      - type stringREQUIRED
        The name of the orchestration strategy to employ.
        Possible values: channel_priority, fan_out, triggering_channel, last_active
- array<object>
status string
Read-only field indicating whether or not the pipeline is currently issuing push notifications.
- pending: The pipeline is not yet active. Occurs when the current time is less than or equal to the activation_time.
- live: The pipeline is active.
- completed: The pipeline has finished running. Occurs when the current time is greater than or equal to the deactivation_time.
- disabled: The pipeline is not active.
Possible values: pending, live, completed, disabled
timing object
Determines when pipelines will be sent in accordance with triggers.
OBJECT PROPERTIES
- delay object
  Determines the time that Airship should wait after a triggering event before processing the pipeline outcome.
  OBJECT PROPERTIES
  - seconds integerREQUIRED
    An integer value greater than 0 seconds representing the number of seconds to delay.
- schedule object
  The time(s) when the pipeline can issue pushes and behavior for events occurring outside scheduled time(s).
  OBJECT PROPERTIES
  - dayparts array[object]REQUIRED
    A list of daypart objects that, when combined, are non-intersecting and form a nonempty group of time ranges on a nonzero number of days of the week. Daypart is a term borrowed from television/radio marketing .
  - miss_behavior string
    Behavior of the pipeline when a triggering event occurs outside the range of daypart objects and allowed_times. You can specify cancel (do not process the outcome) or wait (delay the outcome until the preferred time of the next allowed_times window or the beginning of that window). Defaults to wait if unspecified.
    Possible values: wait, cancel
  - type string
    The mode in which to interpret the times in this schedule. Default is local.
    Possible values: local, utc
uid string
The canonical identifier of the pipeline. This is a read-only field present on responses from the API, but it will be ignored if it is present on requests.
url string
Read-only string. The canonical resource URL of the pipeline. This is a read-only field present on responses from the API, but it will be ignored if present on requests.

Used in:

Examples

{
   "name":"The Darkest Pipeline",
   "enabled":true,
   "immediate_trigger":"first_open",
   "outcome":{
      "push":{
         "audience":"triggered",
         "device_types":[
            "ios",
            "android"
         ],
         "notification":{
            "alert":"Cool goatee, Abed"
         }
      }
   },
   "timing":{
      "delay":{
         "seconds":7200
      },
      "schedule":{
         "type":"local",
         "miss_behavior":"wait",
         "dayparts":[
            {
               "days_of_week":[
                  "thursday"
               ],
               "allowed_times":[
                  {
                     "preferred":"21:30:00"
                  }
               ]
            }
         ]
      }
   }
}

{
 "name":"Read Receipt",
 "enabled":true,
 "immediate_trigger": {
    "tag_added": "newSubscription"
 },
 "outcome":{
    "push":{
       "audience":"triggered"
       },
       "device_types": [
          "email"
       ],
       "notification": {
          "email": {
             "subject": "Did you get that thing I sent you?",
             "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
             "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
             "message_type": "commercial",
             "sender_name": "Airship",
             "sender_address": "team@urbanairship.com",
             "reply_to": "no-reply@urbanairship.com"
          }
       }
    },
   "timing":{
      "delay":{
         "seconds":7200
      }
   }
}

Subscription conditions

Subscription conditions have two possible attributes: list_name and negated.

Jump to examples ↓

OBJECT PROPERTIES

list_name stringREQUIRED
The name of the subscription list to be matched.
negated boolean
A boolean indicating the condition should match on the absence from the list.

Used in:

Examples

{ "name" : "Pipeline with Subscription Conditions",
  "enabled" : true,
  "immediate_trigger" : "/* ... */",
  "outcome" : "/* ... */",
  "condition": [
  { "or" : [
      {"subscription" : {"list_name": "sports_updates"}},
      {"subscription" : {"list_name": "silence", "negated": true}}]
  }]
}

Tag conditions

Tag conditions have three possible attributes: tag_name, group, and negated. Tag conditions can be replaced by segmentation conditions, which offer more features. But note that the behavior of tag conditions is slightly different than a segmentation condition using tag selectors when it comes to contacts. Tag conditions evaluate against a combined set of all tags of all channels. Segmentation conditions evaluate against all the channels of a contact individually to see if at least one channel satisfies the condition.

Jump to examples ↓

OBJECT PROPERTIES

group string
A tag group. Defaults to device.
negated boolean
If true, the condition will match on the absence of a tag. If absent or false, the condition will match on the presence of a tag.
tag_name stringREQUIRED
The name of the tag the condition will match against.

Used in:

Examples

{
    "name" : "Pipeline with Tag Conditions",
    "enabled" : true,
    "immediate_trigger" : "/* ... */",
    "outcome" : "/* ... */",
    "condition": [
        {
            "or" : [
                {
                    "tag" : {
                        "tag_name" : "VIP"
                    }

                },
                {
                    "tag" : {
                        "tag_name": "dont_push",
                        "group": "my_special_sandbox",
                        "negated": true
                    }
                }
            ]
        }
    ]
}