# Automations {% hint style="warning" %} Automations is an extension module currently in beta phase. Get in touch with your mediarithmics contact if you want further information on how to enable it. {% endhint %} Triggered by user activity, automations let you launch predefined sequences of actions. ## Required changes to the schema Using automations might require some changes to your [schema](https://developer.mediarithmics.io/schema). You need to make sure your `UserPoint` object has a `scenarios` property referring to a `UserScenario` object configured as follows: ```graphql type UserPoint @TreeIndexRoot(index:"USER_INDEX"){ id: ID! creation_ts: Timestamp! @TreeIndex(index:"USER_INDEX") agents: [UserAgent!]! accounts: [UserAccount!]! emails: [UserEmail!]! activities: [UserActivity!]! profiles: [UserProfile!]! segments: [UserSegment!]! choices: [UserChoice!]! scenarios: [UserScenario!]! } type UserScenario { id: ID! @TreeIndex(index:"USER_INDEX") scenario_id: String! @TreeIndex(index:"USER_INDEX") execution_id: String! @TreeIndex(index:"USER_INDEX") node_id: String! @TreeIndex(index:"USER_INDEX") callback_ts: Timestamp @TreeIndex(index:"USER_INDEX") start_ts: Timestamp! @TreeIndex(index:"USER_INDEX") node_start_ts: Timestamp! @TreeIndex(index:"USER_INDEX") active: Boolean @TreeIndex(index:"USER_INDEX") } ``` ## Types of automation nodes Automations are composed of `nodes`, linked by `edges` or branches. During an automation, a user will go from node to node along edges until the scenario is over. According to their type, nodes can have 0 to 1 edges in and 0 to n edges out. ### Input nodes Input nodes are always at the start of an automation (each automation must and can have only one entry node). They define what will trigger the entry of a user in an automation. #### On segment entry input nodes If the scenario starts with this type of node, the scenario will be a **On segment entry** type of scenario (`ON_SEGMENT_ENTRY_INPUT_NODE`), where the UserPoint enters the scenario if he enters a specified segment. The node configuration is associated with a User Query or User List [segment](https://developer.mediarithmics.io/user-points/segments). #### On segment exit input nodes The scenario will be a **On segment exit** type of scenario (`ON_SEGMENT_EXIT_INPUT_NODE`), where the UserPoint enters the scenario if he leaves a specified User Query segment. The node configuration is associated with a User Query segment. #### Query input nodes The scenario will have a **React to an event** trigger (`QUERY_INPUT`), associated with a specified query. If an activity received matches the defined query, then the UserPoint will enter the scenario. The node configuration is associated with a [query](https://developer.mediarithmics.io/querying-your-data/otql-queries#creating-a-query). Only fields that have the directive [@TreeIndex](https://developer.mediarithmics.io/schema#treeindex) in the runtime schema can be used for these queries. {% hint style="info" %} These queries is evaluated in the ingestion pipeline onto incoming activities, after session aggregation and processing by [activity analyzers](https://developer.mediarithmics.io/data-streams/data-ingestion/real-time-user-tracking/activity-analyzers), before storage within the datamart. {% endhint %} {% hint style="warning" %} If a user enters a scenario, any attempt to make the user enter the scenario again will fail until the user exits the scenario. {% endhint %} ### Action nodes Automations support an array of action nodes. Once a user goes through an action node during a scenario, the action will be triggered asynchronously and the user will move on to the next node. #### Add to segment nodes If a user goes through an Add-to-segment node (`ADD_TO_SEGMENT_NODE`), he/she will be added to the configured segment. Add-to-segment nodes are associated with a User List segment. #### Remove from segment nodes If a user goes through a Remove from segment node (`REMOVE_FROM_SEGMENT_NODE`), he/she will be removed from the configured segment (if he/she is in segment, if not, nothing will happen). Remove from segment nodes are associated with a User List segment. #### Send email nodes If a user goes through a Send email node (`EMAIL_CAMPAIGN`), the platform will attempt to send an email using the information contained in the node configuration: * [**Email router**](https://developer.mediarithmics.io/advanced-usages/automations/email-routers)**.** The router which will be used to send your email. * [**Provider**](https://developer.mediarithmics.io/advanced-usages/automations/opt-in-provider)**.** The opt-in provider helps you target users who have given you explicit consent to email targeting. * [**Email renderer**](https://developer.mediarithmics.io/advanced-usages/automations/email-renderers) **(optional).** The renderer can be used to customize the email template. You can manage frequency capping settings on the send email nodes so that users do not receive too many emails. This is done by updating the `capping`, `capping_period` and `min_period_between_shoots` properties in the `email_blast` resource created by automations. ## Update email blast `PUT` `https://api.mediarithmics.com/v1/email_campaigns/:emailCampaignId/email_blasts/:emailBlastId` If you just want to update the capping information, look for the `GET /v1/email_campaigns/:emailCampaignId/email_blasts` in the inspector of your browser when opening an automations scenario, and copy the `emailCampaignId` (for the URL), `emailBlastId` (from the payload), as well as all other properties that do not need changing.\ Here only the properties related to frequency capping are shown: #### Path Parameters | Name | Type | Description | | --------------- | ------ | ------------------------------ | | emailBlastId | string | The ID for the email blast. | | emailCampaignId | string | The ID for the email campaign. | #### Request Body | Name | Type | Description | | ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | min\_period\_between\_shoots | string | The minimum period of time between two emails in the same capping period. Using ISO 8601 duration specification (for instance, "P1D" = 1 day, "P2M" = 2 months). | | capping\_period | string | The period to consider for capping. Using ISO 8601 duration specification. | | capping | string | Maximum number of emails sent in this blast for the defined capping period. | {% tabs %} {% tab title="200 " %} ``` { "status": "ok", "data": { "id": "string", "blast_name": "string", "subject_line": "string", "from_email": "string", "from_name": "string", "reply_to": "string", "send_date": 0, "status": "SCENARIO_ACTIVATED", "capping": 1, "capping_period": "P7D", "min_period_between_shoots": "P1D", "batch_size": 0, "number_mail_not_send": 0, "campaign_id": "string" } } ``` {% endtab %} {% endtabs %} {% hint style="warning" %} Send email nodes are created with a default capping value of one email every 13 months. {% endhint %} #### Custom action nodes If a user goes through a Custom action node (`CUSTOM_ACTION_NODE`), the platform will trigger an execution of the [Custom action plugin](https://developer.mediarithmics.io/advanced-usages/automations/custom-action-plugins) set in the node configuration. {% hint style="warning" %} To make the custom action plugin available in the automations UI, you need to create an instance of your plugin attached to your organisation. {% endhint %} {% hint style="warning" %} Custom actions for automations are currently in alpha phase. Get in touch with your mediarithmics contact if you want further information on how to enable them. {% endhint %} #### Feed nodes If a user goes through a Feed node (`SCENARIO_AUDIENCE_SEGMENT_FEED_NODE`), the platform will trigger an execution of the [Audience segment external feed plugin](https://developer.mediarithmics.io/audiences/audience-segment-feed#server-side-feeds) set in the node configuration. {% hint style="info" %} Feed nodes rely on implicit audience segments, which results in basic frequency capping being implemented out of the box: if a same UserPoint enters twice a feed node, it will be only activated once, unless it has exited the segment before the second passage. {% endhint %} {% hint style="warning" %} Feed components are only visible when you have [presets](https://developer.mediarithmics.io/advanced-usages/plugins/presets) configured. {% endhint %} {% hint style="warning" %} Feeds for automations are currently in alpha phase. Get in touch with your mediarithmics contact if you want further information on how to enable them. {% endhint %} ### Flow control nodes Flow control nodes modify the normal flow of an automation. #### Wait nodes If a user goes through a Wait node (`WAIT_NODE`), he/she will be put on hold until wait time is over. Wake up is stored in the `callback_ts` property of `UserScenario`. #### If nodes If a user goes through a If node (`IF_NODE`), he/she will be checked against the associated query and will be sent into the "true" branch or the "false" branch accordingly. #### Split nodes If a user goes through a Split node (`ABN_NODE`), he/she will be sent in one of the outgoing branches on a random basis. {% hint style="info" %} When sent several times through the same scenario, a same user will always go through the same split node branch. {% endhint %} ### Exit nodes Exit nodes mark the exit of an automation. All branches must end with an exit node. ### Exit conditions Exit conditions let you define events which -when received for a user who is currently going through a scenario- will cause the user to exit at once. Exit conditions are stored as queries. Only fields that have the directive [@TreeIndex](https://developer.mediarithmics.io/schema#treeindex) in the runtime schema can be used for these queries. {% hint style="info" %} These queries are evaluated in the ingestion pipeline onto incoming activities, after session aggregation and processing by [activity analyzers](https://developer.mediarithmics.io/data-streams/data-ingestion/real-time-user-tracking/activity-analyzers), before storage within the datamart. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.mediarithmics.io/advanced-usages/automations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.