How to update a jExperience profile using events and APIs

November 14, 2023

Context

Customer data is usually spread across different systems within organisations. While StackConnect offers many no code connectors to integrate with CRMs or Marketing Automation Platforms, there might also be cases where it is needed to updated visitor profiles from the javascript data layer or from custom on premise systems. This document is meant to explain how to simply update a visitor profile when StackConnect is not suitable / does not offer a connector. 

From the data layer / in javascript

To update a visitor profile from the data layer, there are 2 main steps : 

  • Create and send an event 
  • Create a rule that will copy the information from the event to the profile

Creating a form event 

To update a profile, it is either possible to use a custom event type or to use a form event. Here, we'll use a form event to update the first name and the last name of a profile:

var myFormEvent = wem.buildFormEvent("myForm");

// Set the form event properties - the submit is mandatory, don’t forget it
myFormEvent['properties'] = {"myFormId": "Submit"};
myFormEvent.properties.theFirstName= "Antoine" ;
myFormEvent.properties.theLastName= "Dupont";

// Send the event to jCustomer
wem.collectEvent(myFormEvent);

Creating the rule to copy the event properties to the profile

Then, it will be required to register a rule in jCustomer that will ensure that the relevant event properties will be copied to profile properties. The reason why it is not possible to update a profile direcly is security: it is required to have a control over which properties are copied, and not authorize anyone to update another profile.

Below is an example of a rule that is matching the form event above: a rule triggered for form events and copying the first name and the last name. Note that the rule below only applies for events: 

  • With the type "form"
  • Called "myForm"
  • On the site (scope): digitall 

To register the rule below, you'll need the jCustomer / Unomi karaf username and password and do an API call to the folllowing URL: 

https://myjCustomer.com/cxs/rules

 

{
  "metadata": {
    "id": "form-mapping__myForm",
    "name": "myForm",
    "scope": "digitall",
    "systemTags": [
      "formMappingRule"
    ]
  },
  "priority": -1,
  "condition": {
    "type": "booleanCondition",
    "parameterValues": {
      "operator": "and",
      "subConditions": [
        {
          "parameterValues": {
            "formId": "myForm"
          },
          "type": "formEventCondition"
        },
        {
          "parameterValues": {
            "operator": "or",
            "subConditions": [
              {
                "parameterValues": {
                  "scope": "digitall"
                },
                 "type": "sourceEventPropertyCondition"
              }
            ]
          },
          "type": "booleanCondition"
        }
      ]
    }
  },
  "actions": [{
        "parameterValues": {
            "setPropertyName": "properties(firstName)",
            "setPropertyStrategy": "alwaysSet",
            "setPropertyValue": "eventProperty::properties(theFirstName)"
        },
        "type": "setPropertyAction"
    }, 
{
        "parameterValues": {
            "setPropertyName": "properties(lastName)",
            "setPropertyStrategy": "alwaysSet",
            "setPropertyValue": "eventProperty::properties(theLastName)"
        },
        "type": "setPropertyAction"
    }]
}