App connections
The basics
Overview
With App Connections you can send data and commands from a Marketing Automation campaign to external applications. The feature is currently available as a public beta version.
Note
Make sure you adhere to all statutory regulations when sharing data with any third party application!
App connections are related to webhooks, but work a bit differently: Webhooks are defined via API and are triggered by a recipient's actions. App connections, on the other hand, are defined in the Optimizely Campaign graphical user interface and are triggered when a recipient reaches a specific node in a Marketing Automation campaign.
An app connection contains a set of parameters defining an HTTP request. Each app connection is first configured on the page App Connections and can then be used in the campaign editor of Marketing Automation via the Connect App node.
When a recipient reaches a Connect App node, the HTTP request will be sent to the external app as defined. This can be limited to specific target groups.
Opening the page App Connections
Prerequisites: You are logged in to Optimizely Campaign. You have permission to see app connections.
- In the menu bar, click on Administration.
- Click on App Connections. → The page App Connections is displayed.
Properties of HTTP requests from app connections
Authentication
Currently, all app connections use authentication with name and password. If the fields Username and Password on the page Edit App Connection are empty, the app connection will send HTTP requests with an empty authentication string.
A future version will support multiple authentication methods:
- no authentication string at all.
- basic authentication (already available).
- key authentication.
Content type
Currently, all HTTP requests using the POST method use the content type application/json. GET requests do not include a content type declaration. A future version will offer more options for content types.
Preparation of app connections
Settings and placeholders for dynamic values
App connections are configured on the page Create App Connection. Multiple text fields are used for defining the elements of the HTTP request that will be sent by the app connection.
Most use cases for app connections require sending data from a running campaign to an external app. This is possible by using placeholders which allow you to add values from a recipient list to your HTTP request. Each placeholder references a value from a single column in a recipient list. When a recipient reaches an app connection node, the data stored in that column for the recipient is put at the position of the placeholder.
Placeholders can be used in the fields for URL parameters. Replacing placeholders with dynamic values does not work in the field URL.
When using placeholders, use the internal name of the recipient list field in curly brackets, do not use the display name! The internal name is visible on the page Recipient Lists.
Creating an app connection
Prerequisites: You see the page App Connections. You have permission to edit app connections. You know how to address your external application via an HTTP request (if you want to address an Optimizely Campaign API, see API overview).
- Below the list of app connections, click on Create.... → The page Create App Connection is displayed.
- Enter a name.
- Select the appropriate HTTP method.
- Enter the URL for the HTTP request. Do not add "?" and parameters in the field URL!
- If you are using the HTTP method POST, enter the message body.
- If required: Enter a user name and a password. (see Authentication above)
- Optional: Enter a key and value that will be added as URL parameters.
- Optional: Click and enter additional pairs of keys and values.
- Click Save. → The new app connection is now available when you add an App Connection node in the campaign editor of Marketing Automation.
Editing an app connection
Prerequisites: You see the page App Connections. You have permission to edit app connections.
- In the list, click on the app connection you want to edit. → The selected entry is highlighted.
- Below the list of app connections, click on Edit.... → The page Edit App Connection is displayed.
- Adjust the parameters as desired (see Creating an app connection above).
- Click Save. → The changes are saved.
Use of app connections in an MA campaign
Adding a Connect App node
Prerequisites: You have created or opened an MA campaign and see the campaign editor.
- Drag a Connect App node from the side panel to the design area.
- To connect the node to other nodes in your campaign, click one of the handles on the sides of the node and drag a connection to another node. → The campaign contains a Connect App node.
Configuring a Connect App node
Prerequisites: You have configured an app connection. You see a Marketing Automation campaign with a Connect App node in the campaign editor.
- Hover the mouse pointer over the Connect App node.
- Click on (Properties). → A pop-up menu is displayed.
- In the field App Connection, select the app connection you want to use.
- Optional: If you do not want to execute the app connection for every recipient who reaches the node but only for those in a specific target group, select a target group in the field Perform Action Only For.
- Save the campaign.