Using the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange

To use the HCL® Interact Inbound Gateway for HCL Universal Behavior Exchange, you must configure Interact, configure a UBX subscriber endpoint, and create an endpoint and event in UBX.

Use the following configurations as an example for your configuration.

You can download the subscriber gateway from http://www.ibm.com/support/fixcentral/swg/quickorder?parent=Enterprise%2BMarketing%2BManagement&product=ibm/Other+software/Unica+Interact&release=All&platform=All&function=fixId&fixids=IBM_Interact_OMO_Gateway_for_UBX_Subscriber_2.0&includeRequisites=1&includeSupersedes=0&downloadMethod=http&source=fc.

Configuring Interact for the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange

Use the following steps to configure Interact.

  1. In the Interact | activityOrceshtrator | receivers configuration property, add a new receiver. Set Type to IBMMQ or Custom. If you choose Custom, enter ClassName and ClassPath. If you choose IBMMQ, leave ClassPath and ClassName blank.
  2. Add providerURL, queueManager, messageQueueName, authDS, and asmUserFor...." parameters for your receiver.
  3. In the Interact | activityOrceshtrator | gateways configuration property, add a new gateway. Set ClassPath to the URI of the location of the OMO_InteractGateway_UBX.jar file and ClassName to
    com.ibm.interact.offerorchestration.inboundgateway.ubx.
UBXInboundGateway
  4. Create a Interactubx11 folder under the UBX folder of the inbound gateway and copy the properties files to this new folder. The folder name should match the name of the subscriber endpoint that you created in UBX.
  5. In the interactEventNamemapping.properties file, add an entry to map the value of the payload event field to the Interact event name. For example, recommededOffers=recommendedOffers.
  6. In the interactEventPayloadMapping.properties file, add your field definitions with the names of these parameters set to OMO-conf_inbound_UBX_interactEventNameMapping and OMO-conf_inbound_UBX_interactEventNameMapping, respectively

    For example:

    [SessionID]=(String)interactprofileid
[EventName]=(String)code
[AudienceIDFieldNames]=(String)"CustomerID"
[AudienceIDFieldValues]=(Numeric)interactprofileid
[AudienceLevel]=(String)"Customer"
[InteractChannel]=(String"UBX_MM"
  7. Add the locations of your Interactubx11/interactEven tNameMapping.properties and Interactubx11/interactEven tPayloadMapping.properties as parameters for your gateway under Interact | activityOrceshtrator | gateways | [gatewayname] | Parameter Data.
  8. Create an interactive channel and add an event to the interactive channel.
  9. Add a triggered messages rule with the recommendedOffers event and assign an offer to the rule.
  10. Deploy the interactive channel.
  11. Restart the Interact server.
  12. Post an event to UBX with a REST API client.

    Example event body:

    
{  
  "channel" : "mobile",       
  "identifiers" : [            
    {
      "name" : "interactprofileid",       
      "value" : "55"   
    }
  ],
"events" : [
  {
    "code" : "recommendedOffers",      
    "timestamp" : "2015-12-28T20:16:12Z"
   }
  ]
}
  13. Check the Interact log to see if the triggered messages event is triggered.

Configuring the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint

This is a sample endpoint that you can use as an example.

You should also use the instructions to complete the following configurations.

  • UBX endpoint with IBM MQ
  • Endpoint ubxInboundEndpoint.properties file
  • Endpoint inboundProducerNameConfig.properties file
  • Endpoint inboundQueueNameConfig.properties file
  • Endpoint log4j.properties file

Deploying the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange and endpoint

  1. Download and unzip IBM_Interact_OMO_Gateway_for_UBX_Subscriber_2.0.zip to the directory in which you installed Interact on the Interact runtime server.
  2. Download and unzip IBM_Interact_OMO_Endpoint_for_UBX_Subscriber_2.0.zip to any directory (for example, c:\ubxInboundEndpoint) on a publicly accessible JavaEE enabled application server or web server. This server will post data to the Interact inbound JMS Queue to be later consumed by the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange.

Configuring HCL Interact Inbound Gateway for HCL Universal Behavior Exchange Interact Inbound Gateway endpoint

The HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint is configured to accept requests from Universal Behavior Exchange and send it to the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange.

You must complete the following tasks to configure the Universal Behavior Exchange Subscriber Gateway endpoint

  1. A new Java system property (-DubxInboundEndpointConfigPath) needs to be configured by editing the configuration file in the web server or in the administrative console of application server. The -D property should point to the endpoint install directory in the server. This directory contains configuration files for the target JMS queue and various logging levels for the endpoint. For example -DubxInboundEndpointConfigPath=c:\ubxInboundEndpoint.
  2. Deploy the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint web archive file (ubxInboundEndpoint.war) from the install directory as described in the web server or application server documentation.

To verify that the endpoint was installed correctly, enter the following address into any browser and look for message UBX End Point is UP.

http://[Server]:[Port]/[ContextRoot]/UBXEndPoint
Note: You should protect the publicly accessible HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint by adding necessary firewall rules to accept http request from HCL Universal Behavior Exchange Server only.

For example, you can use the following instructions to configure and deploy HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint on WebSphere Application Server.

  1. Open the administrative console.
  2. Select Servers > (Expand Server Types) > server_name > (Expand Java™ and Process Management) > Process Definition > Java Virtual Machine.
  3. In the generic JVM arguments, add the property-DubxInboundEndpointConfigPath=<Universal Behavior Exchange Subscriber Gateway endpoint install dir on the application server>. For example, add the property -DubxInboundEndpointConfigPath=C:\ubxInboundEndpoint.
  4. Click OK to save the changes to the master configuration.
  5. Restart the application server.

Deploy the endpoint in WebSphere Application Server.

  1. Log in to the administrative console.
  2. Navigate to Applications > Application Types > Websphere enterprise applications. Click Install.
  3. Use the Preparing for the application installation option to locate the endpoint war file (ubxInboundEndpoint.war) to be installed and then click Next.
  4. Click Next in subsequent pages to reach Map context roots for Web modules.
  5. Use the Map context roots for Web modules to locate the Context Root and change value to /UBXEndPoint, this becomes the context root. Click next.
  6. Click Finish.
  7. Once the application finished installing, click Save to keep the changes on the master configuration.
  8. Back in the listed and installed applications, mark the checkbox for ubxInboundEndpoint_war and click Start to load.

Configuring the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint with IBM MQ (optional)

By default, the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint works with ActiveMQ. Use the following instructions to configure the endpoint with IBM MQ.

Preparing the HCL MQ JAR files:

The client that runs the endpoint must have certain HCL MQ JAR files available in order for the connection factories to work.

If HCL MQ is already installed on the endpoint machine, the JAR files you need are already packaged with the HCL MQ installation. Add the following two JAR files to the system-level CLASSPATH environment variable. In Windows, the JAR files are automatically added to the classpath when HCL MQ is installed.

[MQ_HOME]\java\bin\com.ibm.mq.jar
[MQ_HOME]\java\bin\com.ibm.mqjms.jar

If HCL MQ is not installed on the machine, you should instead copy com.ibm.mq.allclient.jar and jms.jar from your MQ server to your endpoint server and manually add them to CLASSPATH.

For more information about installing or relocating IBM MQ JAR files, see http://www.ibm.com/support/docview.wss?uid=swg21376217.

Your application server needs to be running Java 1.7 or higher, as IBM MQ v8 JAR files do not support Java 1.6.

WebSphere Application Server comes pre-packaged with IBM MQ support and does not require any additional JAR files.

Configuring the endpoint

  1. Go to the <endpoint install dir on the application server> directory.
  2. Back up or rename ubxInboundEndpoint-spring.xml and ubxInboundEndpoint.properties.
  3. Navigate to the IBMMQ subdirectory. It will contain alternate versions of the above files.
  4. Add your MQ server connection information to this version of ubxInboundEndpoint.properties.
  5. Copy ubxInboundEndpoint-spring.xml and ubxInboundEndpoint.properties from /ubxInbdoundEndpoint/IBMMQ to the main/ubxInboundEndpoint directory.

Configuring the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint ubxInboundEndpoint.properties file

Use the ubxInboundEndpoint.properties file to configure where to send Universal Behavior Exchange event payload to HCL Interact Inbound Gateway for HCL Universal Behavior Exchange. The ubxInboundEndpoint.properties file is in the <gateway endpoint install dir on the application server> directory.

jmsBrokerUrl
Required - The JMS queue information where the producer writes the data.
jmsMaximumRetries
Required - The maximum number of retries to send a message to the JMS queue.
jmsRetryDelay
Required - The redelivery delay in milliseconds.
maximumEndPointThreadPoolSize
Required - The maximum number of threads for the thread pool to handle HCL Universal Behavior Exchange event data and write to JMS queue. This integer number defines the size of the thread pool.
clientIDFieldName
Optional - The field name used in the payload for the client id (sub category). A sub category is used when this program is running on multiple instances of the same product. For example: clientIDFieldName=clientID

A restart of the gateway endpoint webapp (ubxInboundEndpoint.war) is required in web server or application server for any changes in this file to take effect.

Configuring the HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint inboundProducerNameConfig.properties file (optional)

The HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint sends the event to Interact by writing to a JMS queue. The default event message uses the producer name value UBX. Use the inboundProducerNameConfig.properties file to override the producer name based on the UBX source field value from the payload. This is typically the UBX endpoint name. The inboundProducerNameConfig.properties file is in the <gateway endpoint install dir on the application server> directory.

SOURCE.{UBX source name}={producer name}
Example: SOURCE.CustomerAEndpoint=UBX-CustomerAEndpoint.

A restart of the gateway endpoint webapp (ubxInboundEndpoint.war) is required in web server or application server for any changes in this file to take effect.

Configuring the gateway endpoint inboundQueueNameConfig.properties file (optional)

The HCL Interact Inbound Gateway for HCL Universal Behavior Exchange endpoint sends the event to Interact by writing to a JMS queue. The default queue name is the same as the producer name. Use the inboundQueueNameConfig.properties file to override the default JMS queue name by the producer name. The default producer name is UBX unless it's overridden in the inboundQueueNameConfig.properties file. The inboundProducerNameConfig.properties file is in the <gateway endpoint install dir on the application server> directory.

{producer name}={JMS queue name}
Example:
UBX=UBXInboundQueue.
UBX-CustomerAEndpoint=UBX-CustomerAEndpointQueue

A restart of gateway endpoint webapp (ubxInboundEndpoint.war) is required in web server or application server for any changes in this file to take effect.

Configuring the gateway endpoint log4j.properties file

Use the log4j.properties file to configure different log level for the endpoint. The log4j.properties file is in the <gateway endpoint install dir on the application server> directory.

Description

Set the log level for log4j.logger.com.ibm.x1solution.jms.producer, log4j.logger.com.ibm.web.offerorchestration.inbound.common and log4j.logger.com.ibm.web.offerorchestration.inbound.ubx accordingly.

Configuring the interactEventNameMapping.properties file

Use this file to map the value of the payload event field that is defined in the interactEventPayloadMapping.properties file as [EventName] to the Interact event name. The fallback is to use the event name as it comes in with the Universal Behavior Exchange event payload. The interactEventNameMapping.properties file is in the <Install dir>\conf\inbound\UBX directory.

{UBX event name}={Interact event name}

Example: matchedIdentity=recommendedOfferEven

If support for payload data from specific source is necessary, this file may also be placed in the <Install dir>\conf\inbound\UBX\{source} directory. The value for source should match the value of source field in the Universal Behavior Exchange event payload, typically the Universal Behavior Exchange endpoint name. If support for data using specific versions is necessary, this file may also be placed in the <Install dir>\conf\inbound\UBX\{source}\version-{version} directory. The value for version should match the value of version field in the Universal Behavior Exchange event payload. To support multiple Universal Behavior Exchange instance data, this file may also be placed in the <Install dir>\conf\inbound\UBX\{source}\version-{version}\account-{clientID} directory. The value for clientID should match the value of clientID in the Universal Behavior Exchange event payload.

Configuring the interactEventPayloadMapping.properties file

Use the interactEventPayloadMapping.properties file to map the inbound field to the Interact API parameters. The interactEventPayloadMapping.properties file is in the <Install dir>\conf\inbound\UBX directory.

Interact API parameters: The value must start with a field type definition, followed by either a static value when the value is in double quotes, or a field name from the payload data. (FIELD_TYPE)"STATIC_VALUE" or (FIELD_TYPE)PAYLOAD_FIELD_NAME. FIELD_TYPE can be either String, Numeric, or DateTime.

Example:
[SessionID]=(String)interactprofileid
[EventName]=(String)code
[AudienceIDFieldNames]=(String)"change_me"
[AudienceIDFieldValues]=(String)interactprofileid
[AudienceLevel]=(String)"change_me"
[InteractChannel]=(String)"change_me"

Event data: These properties are used to map the event attributes that can be used in your outbound channel communications. The left side contains the variable names you use in your outbound channel communication.

The value must start with a field type definition, followed by either a static value when the value is in double quotes, or a field name from the payload data. (FIELD_TYPE)"STATIC_VALUE" or (FIELD_TYPE)PAYLOAD_FIELD_NAME. FIELD_TYPE can be either String, Numeric, or DateTime.

If support for payload data from specific source is necessary, this file may also be placed in the <Install dir>\conf\inbound\UBX\{source} directory. The value for source should match the value of source field in the Universal Behavior Exchange event payload, typically the Universal Behavior Exchange endpoint name. If support for data using specific versions is necessary, this file may also be placed in the <Install dir>\conf\inbound\UBX\{source}\version-{version} directory. The value for version should match the value of version field in the Universal Behavior Exchange event payload. To support multiple Universal Behavior Exchange instance data, this file may also be placed in the <Install dir>\conf\inbound\UBX\{source}\version-{version}\account-{clientID} directory. The value for clientID should match the value of clientID in the Universal Behavior Exchange event payload.

Creating an endpoint and event in UBX

This is a sample endpoint and event that you can use as an example.

Use the following steps to create an endpoint and event in UBX.

  1. Use the REST API client to post the requests to UBX.
  2. Register an endpoint in UBX with JSON. See the following example. 
    Method Call: PUT
URL: https://ubx-qa1-api.adm01.com/v1/endpoint
Headers:
Content-Type: application/json
Accept-Charset: UTF-8
Authorization: Bearer 912586bf-190d-48f9-8488-26f1bf532ef3 
(Note: This is the Auth Key generated from the UBX UI.)
Body
 {
   "name":"Interactubxdk1",
   "description":"Interactubxdk1",
   "providerName":"HCL", "
   "url":"http://169.38.71.122:9081/ubxEndPoint/UBXEndPoint",
   "endpointTypes":{
     "event":{
       "source":{
         "enabled":true  
       },
       "destination":{
         "enabled":true,
         "url":"http://169.38.71.122:9081/UBXEndPoint/UBXEndPoint",
         "destinationType":"push"
        }
      }
},
"marketingDatabasesDefinition":{
  "marketingDatabases":[
    {
      "name":"IDSync",
      "identifiers":[
        {
      "name":"interactprofileid",
      "type":"INTERACTID"
          }
        ]   
     }
  ]
}
}
  3. Register an eventtype in UBX with JSON. See the following example.
    Event Registration for Interact Event in UBX
Method Call: POST
URL: https://ubx-qa1-api.adm01.com/v1/eventtype

Headers:
Content-Type: application/json
Accept-Charset: UTF-8
Authorization: Bearer 912586bf-190d-48f9-8488-26f1bf532ef3 
Note: This is the Auth Key generated from the UBX UI.)
Bearer 912586bf-190d-48f9-8488-26f1bf532ef3
Body
{
   "name": "recommendedOffers",
   "description": "recommended offers by OMO",
   "code": "recommendedOffers"
}
  4. Post an event to UBX with JSON. See the following example.
    
{  
  "channel" : "mobile",       
  "identifiers" : [            
    {
      "name" : "interactprofileid",       
      "value" : "55"   
    }
  ],
"events" : [
  {
    "code" : "recommendedOffers",      
    "timestamp" : "2015-12-28T20:16:12Z"
   }
  ]
}