Journey Integration

Prerequisite

Make sure that the following things are in place:

• Create a journey, entry source and data definition in the Unica Journey. For more information, refer Getting started with Unica Journey.
• Create Journey Rest integration. For more information, refer Creating a new REST integration.
• Create Journey API Channel in the HCL CDP, only if Journey API is not listed in Channels. For more information about create the Journey API table, refer Create Trigger API channel as Journey API.
• Configure the Journey API refresh token to authenticate the Journey API. For more information about refresh token configuration, refer Configure Journey refresh token API.

Create Trigger API channel as Journey API

Before you create the channel, make sure the Journey API feature is not available in the application. To create a new trigger api channel for Journey API, follow the steps below:

1. In the DMPChannel table, add a new entry for JOURNEY Channel using the following query.

   INSERT INTO DMPChannel
               (Name,
                Description,
                DisplayName,
                ECDisplayName,
                Preference,
                Config,
                Type)
   VALUES      ('JOURNEY API',
                'JOURNEY API',
                'Journey API',
                'Trigger API',
                21,
                '{"isSegChannelCap":1}',
                'trapi'); 
   

2. After inserting the Journey channel, in the DMPCampaignChannelMapping table, insert the journey ChannelMapping using the following query.

   INSERT INTO DMPCampaignChannelMapping
       (CampaignId,
        DMPChannelId,
        Status,
        ImpressionCap,
        ImpressionEnabled,
        FrequencyCaps,
        EmailScheduleTimeInMins,
        IcDisabled,
        DMPCampaignChannelMapping)
   VALUES
       (6525,
        31,
        1,
        500,
        0,
        '{"monthly":{"value":1500},"weekly":{"value":1350},"daily":{"value":200,"isPersistent":0},"lifetime":200}',
        10,
        1,
        5);

3. On successful update, the journey api will be listed under the Channels.

Configure Journey refresh token API

Unica Journey uses thirdpartylogin api to generate authentication token to send the data from HCL CDP. To generate authentication token, follow the steps below:

1. Before generating the tokens, encrypt the clientSecret using KMS encrypt api. Use the following curl commands to encrypt the clientSecret.

   curl --location 'https://<base_url>/kms-service/kms/encrypt' \
   --header 'Content-Type: application/json' \
   --data '{
       "kmsKey": "arn:aws:kms:ap-south-1:654654226610:key/8595ade8-8f55-4487-92da-b42183a2b455",
       "data": "8eInFG2JqfLCkYl9o7.GjpmVZlA4.JkW",
       "campaignId": "campaignID", //replace campaignID
       "region": "aps1"
   }'

   Response:

   {
       "val": "+la4fQPzcUtxjl9t+sekbvGnIjUflBHJjmBuvxCDbzwczhiSdjCV/hp9R2XYmhdK",
       "key": "AQIDAHi1hwJPT6CZTmDECgxOuTdLNdmiQDB2pRjyszBH67kWkQFwJukJOvuPFkYdvF7/2K06AAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQM8NyLH08Qj6TdjZ97AgEQgDte70kBTjq9vE1Z4igQAbLh5noiwcPlZSAPbtEM6TDTPQeyt4o4wVBizTQoykaED/0rhXvtbHcZGQmMFA=="
   }

2. Use the Journey's third party login API to generate tokens.
   1. Endpoint: https://unicabeta.hcltechsw.com/journey/api/thirdpartylogin
   2. RequestType: POST
   3. ContentType: application/json
   4. EncPassword: Include the encrypted clientSecret val generated from the above step.
   5. EncKey: Include the encrypted clientSecret key generated from the above step.
   6. Config: JSON corresponding to the request parameters and also the response parsing for ThirdParty token.

   {
       "accessTokenParam": "tokenId", //Response parameter key for the Refresh token"
       "p": { // Request Parameters for JSON body as per the request payload that you need,
           "clientId": "cliendID", //replace with client ID
           "clientSecret": "@PASSWORD@", //PASSWORD macro is decrypted and replaced from EncPassword while generating a fresh token.
       },
       "h": {}, // Request Headers
       "qp": {} // Query Parameters that you want to send if it is a GET request
   }

3. In the DMPTriggerApiAuthDetails table, add above prepared refresh token entry. Use the following SQL query.

   INSERT INTO DMPTriggerApiAuthDetails
               (id,
                Name,
                CampaignId,
                Endpoint,
                RequestType,
                ContentType,
                EncPassword,
                EncKey,
                Config)
   VALUES      (51,
                ‘journeyThirdpartyToken’,
                6335,
                https://unicabeta.hcltechsw.com/journey/api/thirdpartylogin ',
                POST,
                application/json ',
                iYTY0M0srD82xP9E7oNeBSRMn8GK9EyFbOjPFnnbf+WR6isz4dCz64n1wyH2e/A7',
   ‘bmotc2FtcGxlOnZhdWx0OnYxOjZtbGhab0NlbGJrYThpcjJacHJ0NEs0VXN1WEVqNGYvN1orUzM1MkVyN05WYjZjMEZrT0xQNURXSm1COXg4STF1TDZvRnhqMEF5MnU2UVc1’
                ,
   '{"accessTokenParam":"tokenId","p":{"clientId":"yAzVN1zDl4RhTeaEge42Ipbw30Mp.oO8","clientSecret":"@PASSWORD@"},"h":{},"qp":{}}'
   ); 

Configure Journey API

To configure journey API, follow the steps below:

1. Navigate to Channels > Journey API. Or Navigate to Segments > ALL SEGMENTS > select a segment and click Journey API.
2. Click +Add New Journey API, and add BASIC DETAILS.
   1. Name: Name your journey API. This name cannot be editable once it is saved.
   2. Description: Enter the description of your API.
   3. Journey API Details:
      1. URL: Enter the unica journey rest api url.

         Adding dynamic path parameters in the URL:

         If you have a path parameter that will change each time you trigger an engagement, you can configure it dynamically by defining the variable in {{variable}}.

      2. Payload: Select either the Global Level or Engagement Level option to define the user profile payload details. For more information, refer Payload.
      3. In the Optional Field drop-down, select Yes or No. For more information, refer Optional Field.
3. Click Save Details to create Journey API.
4. Enter the payload, and click Test Configuration to verify the journey api connectivity. Before testing the configuration, make sure to run the following queries in VRM database.
   1. Get the API ID from the database using the following query. In the below query, replace "JourneyApiname" with the created journey api name. The result of this query returns the API ID.

      SELECT Id FROM DMPTriggerApiDetails WHERE NAME='JourneyApiname'

   2. For the newly created Journey API, update the DMPTriggerApiAuthDetailsId and AuthType from DMPTriggerApiDetails to get a dynamic refresh token by providing API ID. Use the below query to update the authentication for the Journey API. In the below query, replace <ID> with the API ID obtained in the previous step.

      UPDATE DMPTriggerApiDetails
      SET DMPTriggerApiAuthDetailsId=51, AuthType='ACCESSKEY'
      WHERE Id= <ID>

5. On successful testing of API, create an engagement. For more information, refer Create Engagement.

Payload

User can define the payload either at global level or engagement level.

Global Level

In the global level, you define the payload for the API by entering the JSON payload in the code block. Ensure the JSON is valid, as any invalid JSON will trigger an error in the UI. If the payload is correct, a tree view will be displayed. In this view, you can add static or dynamic fields, create variables, and flexibly assign display terms. The tree structure allows you to organize parameters based on parent and child objects, making it easy to assign values.

Engagement Level

In the engagement level, you can set a custom payload for each engagement, and helps for campaigns that need different payloads. You can send personalized data for each engagement, making it flexible for different needs.

{
"entrySourceCode": "ES-00000815",
"data": [
{
"Name": "john",
"Email": "john.smile@hcl-software.com",
"Mobile": "9398357962",
"Age": "35",
"City": "Dallas",
"productName": "Term Life Insurance"
}
]
}

Expand the data tree and select a variable name to include a static or dynamic value. Use macros to insert dynamic values. Enter @ in the text box to view the list of macros available. Enter the default value that assigns value to the variable by default, if the value is not provided by the user, or in the case of Macro when the system fails to replace it with a value. For example, to use a user's email address, type @ and select the EMAIL macro from the list.

Optional Field

1. If you wish the field to be mandatory, select No.
2. Select Yes, if the field needs to be optional. In such a case, you have to define how to handle the payload when that particular key (param1 in the example) is not provided with a value.

Option 1:Send Empty Value (do nothing).

The parameters will be empty, and the default value will be shown here in all the engagements.

The payload will be:

{
"details": {
"data": {
"param1": " ",
"param2": "Sample Value 2"
}
},
"token": "abc123"
}

Option 2:Drop data $#$0

On Choosing drop data, the parent node (Data) will be dropped. The grandparent node (details) and ( Token) will be considered as objects.

The payload will be:

{
"details": {},
"token": "abc123"
}

Option 3: Drop data (Grandparent Node)

On Choosing drop details, the grandparent parent node (Data) will be dropped along with its child ( Data). Only (Token) will be considered as objects.

{
"token": "abc123"
}

Option 4: Drop the whole Object

On choosing to drop the whole object, the entire payload will be dropped and the API won't get triggered.