The Mapp Connect Automation Event allows you to trigger Whiteboard automations from your 3rd party integrations. 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. 

Background Information

There is a new API endpoint that allows third-party systems to send POST requests to Mapp Engage. The endpoint is protected by authentication.

Example

{
  "commandCode": 5,
  "email" : "newbie@mapployalty.com",
  "message" : "Welcome to the customers club",
  "loyaltyPointsBalance" : 100
  "expirationDate" : "2022-07-23T18:25:43.511Z"
}
CODE

In this example, we defined that the command code 5 means that a new participant was registered in the loyalty program. This event can be used in Whiteboards to set up a customer journey, for example, to send them a welcome message. Once Mapp receives the external event and successfully puts it in the event engine queue, the OK response is sent to the third-party system.

External Event Setup with Shopware

With a functional Shopware integration in Mapp Connect, you can create Whiteboards using the external event without any prior configuration.

In Shopware, events are predefined and they are also readily available within Mapp Connect. All you have to do, is create the Whiteboard automation using the Mapp Connect External event.

For more information, see the Shopware section in our documentation.

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 3rd party apps. For Shopware, as described above, no setup is needed, because the events are predefined and automatically available in Engage.

For other 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

{ 
   "id":"6d329d9b-201a-4188-a429-7e45d9a674a8",
   "timestamp":1555401662153,
   "integrationId":"47291122-e5bb-4865-a107-a68ec9957325",
   "type":"Import",
   "subtype":"automation",
   "email":"user@mapp.com",
   "external_event":"new_account",
   "value1":"account_URL
}
CODE

Parameters

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

A parameter for Whiteboard to list all incoming automation event types.

"value1"

An attribute that can be used as an email parameter or/and contact attribute (any type).

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

  • 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 3rd party app online help.


B) Add external event to Mapp Connect 

  1. Open the integration you want to configure for external events: Data Management > Mapp Connect.
  2. (optional) In the Overview section, under Automations (whiteboard) settings, tick the checkbox "Trigger Whiteboard automations on user mapping attributes change". 


  3. In the Overview section under Automations (whiteboard) settings, add the events.
    1. Enter the event name.
    2. Click ADD.
  4. Go to the Mapping tab and configure the automation mapping. For more information see  Add Mapping.
  5. 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.

    { 
    
    "id":"6d329d9b-201a-4188-a429-7e45d9a674a8",
    "timestamp":1555401662153,
    "integrationId":"47291122-e5bb-4865-a107-a68ec9957325",
    	"type":"Import",
    	"subtype":"automation",
    	"email":"user@mapp.com", 
    	"externalEvent":"test"
    
    }
    CODE
  2. Create a new event-based Whiteboard using the Mapp Connect External Event. Select event name: "test".

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


API Calls: Use Cases

 Send an email with parameters
  • Call example

    { 
    
    "id":"6d329d9b-201a-4188-a429-7e45d9a674a8",
    "timestamp":1555401662153,
    "integrationId":"47291122-e5bb-4865-a107-a68ec9957325",
    	"type":"Import",
    	"subtype":"automation",
    	"email":"user@mapp.com",
    	"externalEvent":"new_account",
    	"value1":"account_URL"
    
     }
    CODE
  • Mapping

    emailemail (no subtype)
    value1

    value1  (subtype email)

  • Procedure
    1. Create an automation event in your 3rd party app
    2. In Mapp Connect, add value1 to the automation mapping with the email subtype
    3. Create an event-based Whiteboard with the Mapp Connect External Event. Select the "new_accout" event in the configuration.
    4. Add the job Send Email. Use a prepared message with the expression <%parameter.value1%>.
 Store attributes under the contact profile
  • Call

    { 
    
    "id":"6d329d9b-201a-4188-a429-7e45d9a674a8",
    "timestamp":1555401662153,
    "integrationId":"47291122-e5bb-4865-a107-a68ec9957325",
       "type":"Import",
       "subtype":"automation",
       "email":"user@mapp.com",
       "externalEvent":"interest_form",
       "birthday":"09-12-1980",
       "main_interest":"sport"
    
    }
    CODE
  • Mapping

    emailemail (no subtype)
    birthday (subtype user, atribbute type : core)  
    main_interestinterest (subtype user, atribbute type : custom) 
  • Procedure
    1. Create automation event in 3rd party plugin and triggered on the external app event
    2. Add birthday and main_intrest a to automation mapping with user subtype
    3. Add new Event-based Whiteboard plan with External event block and choose "intrest_form" event
    4. Add send an email block and use the prepared message (attributes are stored under contact profile for the user with the email value)

Related Topics