The Mapp Connect Automation Event allows you to trigger Whiteboard automations from your third-party integrations and your own plugins. For example, you can have automations (customer journeys) started by an event that is registered in your Shopware platform, or via a different Mapp Connect integration. Contacts are added to the Whiteboard plan via Mapp Connect API and go through the defined journey.  

Use Case Recommendations

This solution is good for:

  • making changes in contact attributes
  • adding a contact attribute (without value, based on the triggered third-party event)
  • listening for communication events from third-party apps that can then trigger a customer journey in Engage

For standard emails, such as welcome emails, or adding attributes that are part of the JSON body, use the email and/or user method. See API Endpoints.

External Event Setup with Custom Integrations

With custom integration, you have the possibility to trigger a Whiteboard automation in Mapp Engage with events that you define in your third-party apps. For most apps, you need to create those events in the app, and configure the integration in Mapp Engage accordingly.  Below, we describe the process of setting up 3rd party app - external - events within Mapp Engage.

A) Create external event

To create events in your 3rd party app, refer to its online help. Below, you will find an example of an API call.

Call example

POST /integration/<INTEGRATION ID>/event?subtype=automation

JSON payloadAutomation subtype mapping
{ 
   "email":"user@mapp.com",
   "external_event":"new_account",
   "interest":"climbing",
   "accountActivationURL":"sample.com/7F000xf"
}
CODE

FieldsDescription
"email"A contact for whom the Whiteboard(s) should be triggered.
"external_event"

A parameter for Whiteboard to list all incoming automation event types. These will then be visible in the Whiteboard UI.

"interest"

In this mapping example, this attribute adds the value to the custom attribute "Interests". 

Depending on the added mapping, unlimited amount of attributes can be stored in contact profile or used as email parameters.

"accountActivationURL"

In this example, this attribute is used as an email parameter. This means that it's not stored in the contact profile, or any other dataset in Mapp Engage, but it can be used in the message sendout via the defined Whiteboard.

Formula to use it in the prepared message template: 

<%parameter.accountActivationURL%>

  • The request body can contain any JSON object

  • The response is an HTTP status code

For more detail, please refer to our Third-Party integrations documentation, and to your third-party app online help.

B) Add external event to Mapp Connect 

This step defines which events are monitored so that they can then be used to trigger Whiteboard automations. Once created (in point C below), the Whiteboard automation will listen to these events and react as defined there.

  1. Open the integration you want to configure for external events: Data Management > Mapp Connect.
  2. In the Overview section under Automations (whiteboard) settings, add the events: Enter the event name and click ADD. These events must be included in the JSON payload as the value of the "external_event".
     
  3. If your integration does not have the automation mapping, you must add it. To do so, go to the Mapping tab and configure the automation mapping.
  4. In the default mapping, the source is named "external_event". If your "external_event" attribute is named differently in your JSON payload, edit the source of this field in the automation mapping. 

    For more information see Add Mapping.

  5. If you would like to include email parameters or contact attributes within this external event (included in your JSON), add them in the automation mapping. 

    • If you want to add attributes to the contact profile within the automation mapping, use the "user" subtype and choose the attribute type.
    • If you want to use email parameters within your Whiteboard program, add them in the automation mapping with the "email" subtype.


  6. Finalize the integration setup as needed. Now you are ready to create the Whiteboard.

C) Setup Whiteboard automation

  1. Create an event-based automation in Automations > Whiteboards.
  2. Use the Mapp Connect External Event as your entry event.
  3. Configure the external event.
    1. Define the audience
    2. Select the Mapp Connect integration you want to use. In our example, the integration is called Generic Connection.
    3. Select the required event. In our example, it is the new_account event.
  4. Click Apply.
  5. Proceed with building the automation. For example, send a welcome email to all contacts who have created a new account in your online shop.

D) Test automation

It is good practice to test your automation before the first real calls are sent. To do this, you can set up a test call.

  1. Create an event in your Mapp Connect integration that will be triggered in the external app.

    { 
	"subtype":"automation",
	"email":"user@mapp.com", 
	"externalEvent":"new_account"
}
    CODE

  2. Create a new event-based Whiteboard using the Mapp Connect External Event. Select event name: "new_account".

  3. As the next step, add the job Send Email to test the Whiteboard automation.

    If "user@mapp.com" received the email, the automation works correctly.

API Calls: Use Cases

 Send an email with parameters & change contact custom attribute

In this use case, we will send an email to the user "user@mapp.com" with the email parameter that includes the URL to activate their new account. We will also set a new custom attribute value for this contact.

Procedure


Note: For this procedure, you will need to create a prepared message that uses the required parameters.

  1. Create an automation event in your third-party app.
  2. In Mapp Connect, add "account_URL" to the automation mapping with the email subtype.
  3. Create an event-based Whiteboard with the Mapp Connect External Event. Select the "new_account" event in the configuration.
  4. Add the job Send Email. Use a prepared message that includes the placeholder <%parameter.account_URL%>. For more information, see 
  5. Add the job Change Profile Attribute and finalize the Whiteboard plan.

Call example

POST /integration/<INTEGRATION ID>/event?subtype=automation

JSON Payload (body)

{ 

	"email":"user@mapp.com",
	"externalEvent":"new_account",
	"account_URL":"sample.com/7F000xf"

 }
CODE


Mapping

SourceTargetLocation
"email"userIdautomation
"account_URL"

accountActivationURL

email
 Send messages based on the opt-ins stored in the contact profile

In this use case, we are sending the same message via different channels - SMS, Push, Email - based on the opt-in information for the contact, and deleting contacts without any opt-in. SMS is the priority channel, followed by Push and Email. The Whiteboard processes events from left to right.

Prerequisites

  • Your custom app must have the methods to manage opt-ins for the three channels using Mapp Connect (other options would be API or import).
  • Your custom app must have the handlers to trigger the Mapp Connect automation event.
  • Three prepared messages in Mapp Engage, one for each channel: SMS, Push, and Email.

Procedure

  1. Create events in your app to collect opt-in information for your contacts.
  2. Add external event to your Mapp Connect integration as shown in point B2.
  3. Create an event-based Whiteboard with the Mapp Connect External Event as an Entry Event.


For more examples, see Send Message and Update Contact Profile within one Call.

Related Topics

External Event Setup with Shopware
Mapp Connect External Event