Version 1 Release 3 October 2015 IBM Interact Omni-channel Message Orchestrator Guide IBM
Note Before using this information and the product it supports, read the information in Notices on page 31. This edition applies to version 1, release 1, modification 0 of IBM Interact Omni-channel Message Orchestrator and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2014, 2015. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents Chapter 1. Overview......... 1 Chapter 2. Prerequisites........ 3 Chapter 3. Deploying Interact Omni-channel Message Orchestrator.. 5 Installing Interact Omni-channel Message Orchestrator into Interact on WebSphere Application Server................ 5 Upgrading Interact Omni-channel Message Orchestrator into Interact on WebSphere Application Server................ 7 Installing Interact Omni-channel Message Orchestrator into Interact on WebLogic..... 9 Upgrading Interact Omni-channel Message Orchestrator into Interact on WebLogic..... 11 Setting up JMS............. 12 Configuring JMS auto reconnect....... 12 Configuring Interact Omni-channel Message Orchestrator with IBM MQ......... 13 Chapter 4. Configuring Interact Omni-channel Message Orchestrator.. 19 Configuring the eventconfig.properties file... 19 Configuring the globalconfig.properties file... 19 Configuring the outboundgatewayconfig.properties file................. 24 Configuring the inboundglobalconfig.properties file................. 25 Configuring the inboundgatewayconfig.properties file................. 25 Configuring the inboundgatewayqueuenameconfig.properties file.. 26 Chapter 5. Sample code....... 27 Notices.............. 31 Trademarks.............. 33 Privacy Policy and Terms of Use Considerations.. 33 Copyright IBM Corp. 2014, 2015 iii
iv IBM Interact Omni-channel Message Orchestrator Guide
Chapter 1. Overview Within IBM Interact offers can only be delivered synchronously to the process that submits an event, which is inherently specific to one inbound channel. For example, you can deliver a web-message back to the web-channel when a web-event occurs in Interact. However, if you want to send an email or mobile push whenever a specific web event occurs, you must write custom code to do so. IBM Interact Omni-channel Message Orchestrator fills this gap with a generic, reusable module that transforms Interact into a cross-channel offer messaging system. The system is capable of delivering any Interact offer through any outbound channel, regardless of the channel on which the inbound event occurred. It is important to note though, that control over which offers to deliver remains within the full control of Interact strategies, and as such, within the marketer s hands. Copyright IBM Corp. 2014, 2015 1
2 IBM Interact Omni-channel Message Orchestrator Guide
Chapter 2. Prerequisites You must complete the following prerequisites before you use IBM Interact Omni-channel Message Orchestrator. v Interact Omni-channel Message Orchestrator offer dispatching to the outbound gateways requires Interact version 8.6.0.8 (or a later 8.x version of Interact) or Interact version 9.1.1 or later. Interact Omni-channel Message Orchestrator is not compatible with Interact version 9.0 or 9.1. Note: If you use the Interact Omni-channel Message Orchestrator Opportunity Detect Inbound Gateway, you must use version 9.1.1.2 of Opportunity Detect. v Any additional outbound gateways or inbound gateways and their products that are used with Interact Omni-channel Message Orchestrator might require more setup. Copyright IBM Corp. 2014, 2015 3
4 IBM Interact Omni-channel Message Orchestrator Guide
Chapter 3. Deploying Interact Omni-channel Message Orchestrator The Interact Omni-channel Message Orchestrator can be deployed into the Interact runtime environment on WebLogic or WebSphere Application Server. If you want to perform an initial installation of Interact Omni-channel Message Orchestrator, see the instructions for installing Interact Omni-channel Message Orchestrator into Interact on WebLogic or WebSphere Application Server. If you previously installed Interact Omni-channel Message Orchestrator and want to upgrade to a newer version, see the instructions for upgrading Interact Omni-channel Message Orchestrator into Interact on WebLogic or WebSphere Application Server. Installing Interact Omni-channel Message Orchestrator into Interact on WebSphere Application Server Interact Omni-channel Message Orchestrator can be installed into Interact on WebSphere Application Server (WAS). Use the following instructions to perform an initial installation of Interact Omni-channel Message Orchestrator. If you previously installed Interact Omni-channel Message Orchestrator, use the upgrade instructions. 1. Download the IBM_Interact_OMO_1.1.zip file, the IBM_Interact_OMO_Utilities_1.1.zip file, and any gateways you plan to use to any directory (for example, c:\omo) on the Interact runtime server. 2. Extract the IBM_Interact_OMO_Utilities_1.1.zip file to the directory where you want to install Interact Omni-channel Message Orchestrator. 3. Run the installomo.bat utility for Windows environments or the installomo.sh utility for Linux environments to extract and install Interact Omni-channel Message Orchestrator. These files are in the OMO\bin\OMO_Utilities directory. Note: Before you can run installomo on Unix, you must run the chmod +x *.sh command. You can use the following syntax for this command. installomo -i <installdir> -z<zipfilelocation> -i --installdir is the absolute path to existing or planned installation. -z --zipfilelocation is the absolute path to the Interact Omni-channel Message Orchestrator Core or Gateway zip files to be installed. This command Installs all zip files found at this location. -? --help prints this help message. 4. Open the administrative console. 5. Select Servers > (Expand Server Types) > WebSphere application servers > server_name > (Expand Java and Process Management) > Process Definition > Java Virtual Machine. 6. In the generic JVM arguments, add the property -Dcom.ibm.interact.offerOrchJar=<OMO install dir>\omo.jar. Copyright IBM Corp. 2014, 2015 5
For example, add the property -Dcom.ibm.interact.offerOrchJar=c:\omo\ OMO.jar. 7. Click OK to save changes to the master configuration. 8. Edit <OMO Install Dir>\conf\outbound\common\globalConfig.properties. a. Change the property value for Event.DefaultInteractionPoint to be the Interact interaction point that you want to use for Interact Omni-channel Message Orchestrator offers. b. If you use in memory offer dispatching, edit the property OfferDispatcher and set the value to com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherMemoryImpl. c. If you use JMS backed offer dispatching, edit the property and set the value to com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherJMSImpl, and install the ActiveMQ JMS server. The default configuration assumes that the JMS server can be accessed at tcp://localhost:61616. This configuration can be changed by editing the property OfferDispatcherJMSImpl.JMSBrokerURL in globalconfig. Note: The default configuration is to use JMS backed offer dispatching. 9. Configure the other properties files in the IBM_Interact_OMO_1.1.zip file depending on your Interact Omni-channel Message Orchestrator configuration. Configure the eventconfig.properties file to enable events for offer dispatching. Configure the outboundgatewayconfig.properties file to register any OutboundGateways. Use the inboundglobalconfig.properties file to process inbound messages that come from the specified JMS server. Configure the inboundgatewayconfig.properties file to register any InboundGateways. Use the inboundgatewayqueuenameconfig.properties file to specify a queue name in your inbound gateway. For more information on the properties files configuration, see Configuring Interact Omni-channel Message Orchestrator. 10. Configure the inbound and outbound gateways you want to use with Interact Omni-channel Message Orchestrator. For more information, see https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/ wiki/w214f7731a379_4712_a1ce_5d7a833d4cca/page/interact%20omnichannel%20message%20orchestrator 11. Run the validateconfig.bat utility for Windows environments or the validateconfig.sh utility for Linux environments to confirm that there are no errors in your properties files. These files are in the OMO\bin\OMO_Utilities directory. The validateconfig utility checks for specific issues within the Interact Omni-channel Message Orchestrator install. v Required jars are present in the proper directory structure. v Required files are present in the proper directory structure. The validateconfig utility checks for specific issues within the associated properties files that are necessary for the Interact Omni-channel Message Orchestrator install. v Required parameters have values. 6 IBM Interact Omni-channel Message Orchestrator Guide
v Required parameters, which require classes, have values. v Any parameter that has a value cannot be equal to <change me>; this represents a field that you must change to configure Interact Omni-channel Message Orchestrator. v Searches parameter values for specific classes. If a class is found, the program is triggered to look for that Interact Omni-channel Message Orchestrator install. Note: validateconfig assumes that your inbound gateway has interacteventnamemapping.properties, interacteventpayloadmapping.properties, and inboundmessageschema.properties (Tealeaf Inbound only) files in conf/inbound/<inboundgatewayname>. If these files are in a lower directory level, validateconfig posts a fatal error that the files are not found in the expected location. This error can be ignored if the files were moved to a lower directory intentionally. 12. Fix any errors that you receive when you run the validateconfig utility. Rerun the validateconfig utility and continue to fix the errors until you have no errors. 13. Edit the Interact log4j property file and add the following to enable Interact Omni-channel Message Orchestrator debug logging. log4j.logger.com.ibm.interact.offerorchestration=debug Note: The Interact log4j property file is typically in /data/ibm/unica/ Interact/conf/interact_log4j.properties, but the path is configurable through the Interact configuration manager. Note: After you have Interact Omni-channel Message Orchestrator running and verified it is working, you can lower the log level to info. 14. Restart Interact runtime server. Upgrading Interact Omni-channel Message Orchestrator into Interact on WebSphere Application Server Use the following steps to upgrade Interact Omni-channel Message Orchestrator to the latest version on WebSphere Application Server. 1. Backup your <OMO Install Dir>\conf directory. 2. Download the IBM_Interact_OMO_1.1.zip file, the IBM_Interact_OMO_Utilities_1.1.zip file, and any gateways you plan to use. 3. Extract the IBM_Interact_OMO_Utilities_1.1.zip file to the directory where you want to install Interact Omni-channel Message Orchestrator. 4. Verify your JVM settings. See Deploying Interact Omni-channel Message Orchestrator into Interact on WebSphere Application Server for more information. 5. Stop the WebSphere Application Server. 6. Run the installomo.bat utility for Windows environments or the installomo.sh utility for Linux environments to extract and install the latest version of Interact Omni-channel Message Orchestrator. These files are in the OMO\bin\OMO_Utilities directory. Note: Before you can run installomo on Unix, you must run the chmod +x *.sh command. Chapter 3. Deploying Interact Omni-channel Message Orchestrator 7
You can use the following syntax for this command. installomo -i <installdir> -z<zipfilelocation> -i --installdir is the absolute path to existing or planned installation. -z --zipfilelocation is the absolute path to the Interact Omni-channel Message Orchestrator Core or Gateway zip files to be installed. This command installs all of the Interact Omni-channel Message Orchestrator zip files that are found in this file location. Therefore, this file location should only contain installation or upgrade files that are new. -? --help prints this help message. -dv disables the validation after the installation. The mergeproperties utility runs automatically with the installation to merge your existing properties files with the newly installed properties files. Note: installomo assumes that your inbound gateway has interacteventnamemapping.properties, interacteventpayloadmapping.properties, and inboundmessageschema.properties (Tealeaf Inbound only) files in conf/inbound/<inboundgatewayname>. If these files are in a lower directory level, installomo posts a fatal error that the files are not found in the expected location. This error can be ignored if the files were moved to a lower directory intentionally. Note: For the Tealeaf Struggle Inbound Gateway, the interacteventpayloadmapping.properties file has the following sample mapping. This sample mapping causes an issue with the mergeproperties utility because the utility looks for the sample when it performs the merge and merges it back into the property file, even if you deleted the sample. browsertype=(string)customfield1 cartvalue=(string)customfield2 usertype=(string)customfield3 The validateconfig utility also runs automatically with the upgrade. The validateconfig utility checks for specific issues within the Interact Omni-channel Message Orchestrator install. v Required jars are present in the proper directory structure. v Required files are present in the proper directory structure. The validateconfig utility checks for specific issues within the associated properties files that are necessary for the Interact Omni-channel Message Orchestrator install. These files are in the OMO\bin\OMO_Utilities directory. v Required parameters have values. v Required parameters, which require classes, have values. The values must be valid class names, which are validated through the jar files. v Any parameter that has a value cannot be equal to <change me>; this represents a field that you must change to configure Interact Omni-channel Message Orchestrator. v Searches parameter values for specific classes. If a class is found, the program is triggered to validate the respective Interact Omni-channel Message Orchestrator install. 7. Fix any errors that you receive when the validateconfig utility runs. Rerun the validateconfig utility and continue to fix the errors until you have no errors. 8. Optional. You can edit your Interact log4j property file to change the debug settings, if desired. 9. Restart the WebSphere Application Server. 8 IBM Interact Omni-channel Message Orchestrator Guide
Installing Interact Omni-channel Message Orchestrator into Interact on WebLogic Interact Omni-channel Message Orchestrator can be installed into Interact on WebLogic. Use the following instructions to perform an initial installation of Interact Omni-channel Message Orchestrator. If you previously installed Interact Omni-channel Message Orchestrator, use the upgrade instructions. 1. Download the IBM_Interact_OMO_1.1.zip file, the IBM_Interact_OMO_Utilities_1.1.zip file, and any gateways you plan to use to any directory (for example, c:\omo) on the Interact runtime server. 2. Extract the IBM_Interact_OMO_Utilities_1.1.zip file to the directory where you want to install Interact Omni-channel Message Orchestrator. 3. Run the installomo.bat utility for Windows environments or the installomo.sh utility for Linux environments to extract and install Interact Omni-channel Message Orchestrator. These files are in the OMO\bin\OMO_Utilities directory. Note: Before you can run installomo on Unix, you must run the chmod +x *.sh command. You can use the following syntax for this command. installomo -i <installdir> -z<zipfilelocation> -i --installdir is the absolute path to existing or planned installation. -z --zipfilelocation is the absolute path to the Interact Omni-channel Message Orchestrator Core or Gateway zip files to be installed. This command Installs all zip files found at this location. -? --help prints this help message. 4. Edit setdomainenv.bat to add the following D parameters to JAVA_PROPERTIES. -Dcom.ibm.interact.offerOrchJar=<OMO install dir>\omo.jar For example, set JAVA_PROPERTIES=(previously set properites) -Dcom.ibm.interact.offerOrchJar=c:\omo\OMO.jar 5. Edit <OMO Install Dir>\conf\outbound\common\globalConfig.properties. a. Change the property value for Event.DefaultInteractionPoint to be the Interact interaction point you want to use for Interact Omni-channel Message Orchestrator offers. b. If you use in memory offer dispatching, edit the property OfferDispatcher and set the value to com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherMemoryImpl. c. If you use JMS backed offer dispatching, edit the property and set the value to com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherJMSImpl, and install the ActiveMQ JMS server. The default configuration assumes that the JMS server can be accessed at tcp://localhost:61616. This can be changed by editing the property OfferDispatcherJMSImpl.JMSBrokerURL in globalconfig. Note: The default configuration is to use JMS backed offer dispatching. 6. Configure the other properties files in the IBM_Interact_OMO_1.1.zip file depending on your Interact Omni-channel Message Orchestrator configuration. Chapter 3. Deploying Interact Omni-channel Message Orchestrator 9
Configure the eventconfig.properties file to enable events for offer dispatching. Configure the outboundgatewayconfig.properties file to register any OutboundGateways. Use the inboundglobalconfig.properties file to process inbound messages that come from the specified JMS server. Configure the inboundgatewayconfig.properties file to register any InboundGateways. Use the inboundgatewayqueuenameconfig.properties file to specify a queue name in your inbound gateway. For more information on the properties files configuration, see Configuring Interact Omni-channel Message Orchestrator. 7. Configure the inbound and outbound gateways you want to use with Interact Omni-channel Message Orchestrator. For more information, see https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/ wiki/w214f7731a379_4712_a1ce_5d7a833d4cca/page/interact%20omnichannel%20message%20orchestrator 8. Run the validateconfig.bat utility for Windows environments or the validateconfig.sh utility for Linux environments to confirm that there are no errors in your properties files. These files are in the OMO\bin\OMO_Utilities directory. The validateconfig utility checks for specific issues within the Interact Omni-channel Message Orchestrator install. v Required jars are present in the proper directory structure. v Required files are present in the proper directory structure. The validateconfig utility checks for specific issues within the associated properties files that are necessary for the Interact Omni-channel Message Orchestrator install. v Required parameters have values. v Required parameters, which require classes, have values. v Any parameter that has a value cannot be equal to <change me>; this represents a field that you must change to configure Interact Omni-channel Message Orchestrator. v Searches parameter values for specific classes. If a class is found, the program is triggered to look for that Interact Omni-channel Message Orchestrator install. Note: validateconfig assumes that your inbound gateway has interacteventnamemapping.properties, interacteventpayloadmapping.properties, and inboundmessageschema.properties (Tealeaf Inbound only) files in conf/inbound/<inboundgatewayname>. If these files are in a lower directory level, validateconfig posts a fatal error that the files are not found in the expected location. This error can be ignored if the files were moved to a lower directory intentionally. 9. Fix any errors that you receive when you run the validateconfig utility. Rerun the validateconfig utility and continue to fix the errors until you have no errors. 10. Edit the Interact log4j property file and add the following to enable Interact Omni-channel Message Orchestrator debug logging. log4j.logger.com.ibm.interact.offerorchestration=debug 10 IBM Interact Omni-channel Message Orchestrator Guide
Note: The Interact log4j property file is typically in /data/ibm/unica/ Interact/conf/interact_log4j.properties, but the path is configurable through the Interact configuration manager. Note: After you have Interact Omni-channel Message Orchestrator running and verified it is working, you can lower the log level to info. 11. Restart Interact runtime server. Upgrading Interact Omni-channel Message Orchestrator into Interact on WebLogic Use the following steps to upgrade Interact Omni-channel Message Orchestrator to the latest version on WebLogic. 1. Backup your <OMO Install Dir>\conf directory. 2. Download the IBM_Interact_OMO_1.1.zip file and the IBM_Interact_OMO_Utilities_1.1.zip file, and any gateways you plan to use. 3. Extract the IBM_Interact_OMO_Utilities_1.1.zip file to the directory where you want to install Interact Omni-channel Message Orchestrator. 4. Verify your JVM settings. See Deploying Interact Omni-channel Message Orchestrator into Interact on WebLogic for more information. 5. Stop WebLogic. 6. Run the installomo.bat utility for Windows environments or the installomo.sh utility for Linux environments to extract and install the latest version of Interact Omni-channel Message Orchestrator. These files are in the OMO\bin\OMO_Utilities directory. Note: Before you can run installomo on Unix, you must run the chmod +x *.sh command. You can use the following syntax for this command. installomo -i <installdir> -z<zipfilelocation> -i --installdir is the absolute path to existing or planned installation. -z --zipfilelocation is the absolute path to the Interact Omni-channel Message Orchestrator Core or Gateway zip files to be installed. This command installs all of the Interact Omni-channel Message Orchestrator zip files that are found in this file location. Therefore, this file location should only contain installation or upgrade files that are new. -? --help prints this help message. The mergeproperties utility runs automatically with the upgrade to merge your existing properties files with the newly installed properties files. Note: installomo assumes that your inbound gateway has interacteventnamemapping.properties, interacteventpayloadmapping.properties, and inboundmessageschema.properties (Tealeaf Inbound only) files in conf/inbound/<inboundgatewayname>. If these files are in a lower directory level, installomo posts a fatal error that the files are not found in the expected location. This error can be ignored if the files were moved to a lower directory intentionally. Note: For the Tealeaf Struggle Inbound Gateway, the interacteventpayloadmapping.properties file has the following sample mapping. This sample mapping causes an issue with the mergeproperties Chapter 3. Deploying Interact Omni-channel Message Orchestrator 11
Setting up JMS utility because the utility looks for the sample when it performs the merge and merges it back into the property file, even if you deleted the sample. browsertype=(string)customfield1 cartvalue=(string)customfield2 usertype=(string)customfield3 The validateconfig utility also runs automatically with the installation. The validateconfig utility checks for specific issues within the Interact Omni-channel Message Orchestrator install. v Required jars are present in the proper directory structure. v Required files are present in the proper directory structure. The validateconfig utility checks for specific issues within the associated properties files that are necessary for the Interact Omni-channel Message Orchestrator install. These files are in the OMO\bin\OMO_Utilities directory. v Required parameters have values. v Required parameters, which require classes, have values. The values must be valid class names, which are validated through the jar files. v Any parameter that has a value cannot be equal to <change me>; this represents a field that you must change to configure Interact Omni-channel Message Orchestrator. v Searches parameter values for specific classes. If a class is found, the program is triggered to validate the respective Interact Omni-channel Message Orchestrator install. 7. Fix any errors that you receive when the validateconfig utility runs. Rerun the validateconfig utility and continue to fix the errors until you have no errors. 8. Optional. You can edit your Interact log4j property file to change the debug settings, if desired. 9. Restart WebLogic. You can set up JMS to work with Interact Omni-channel Message Orchestrator. Follow these steps to set up the server and update the configuration file. 1. Download the ActiveMQ to your dev environment. You can download ActiveMQ from http://activemq.apache.org/activemq-5100-release.html. 2. Extract the files from the zip file into a directory of your choice. 3. Run the following command to start the ActiveMQ server. cd [activemq_install_dir] bin\activemq start You should see info logs on the console. To test the installation, in another command line window, type netstat -an find "61616". You can access the ActiveMQ administration page by going to http://localhost:8161/admin in a web browser. The default user name and password are both admin. Configuring JMS auto reconnect You can configure the JMS server to auto reconnect so you do not need to restart the Interact runtime environment every time the JMS server restarts. 12 IBM Interact Omni-channel Message Orchestrator Guide
If you use JMS backed offer dispatching, the default configuration assumes that the JMS server can be accessed at tcp://localhost:61616. With the default setting, if the JMS server is restarted, you must restart the Interact runtime environment for IBM Interact Omni-channel Message Orchestrator to work properly. It is possible to configure the JMS to perform auto reconnection. Therefore, you do not need to restart the Interact runtime environment. For example, with Apache ActiveMQ, you can use the failover transport so the JMS client (connection) automatically reconnects to the server if there is a socket exception. You can also use a list of URIs to specify which machines to connect to and use discovery to find the servers to connect to. Example: OfferDispatcherJMSImpl.JMSBrokerURL=failover:(tcp://host1:61616, tcp://host2:61616) You can use this setting in other places where JMS is used within IBM Interact Omni-channel Message Orchestrator, such as the inbound gateway. Note: When the failover transport is used, if all JMS servers are down when the application server is started, the application server might not start properly. Make sure that the JMS server is started in this case or refer to the documentation of the JMS providers to configure timeout options. Configuring Interact Omni-channel Message Orchestrator with IBM MQ Prerequisites You must have IBM Interact Omni-channel Message Orchestrator and IBM MQ version 8.0 installed. For more information about IBM Interact Omni-channel Message Orchestrator, see https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/ wiki/w214f7731a379_4712_a1ce_5d7a833d4cca/page/interact%20omni-channel %20Message%20Orchestrator. For more information about IBM MQ v8.0, see http://www.ibm.com/support/ knowledgecenter/ssfksj_8.0.0/com.ibm.mq.helphome.v80.doc/ WelcomePagev8r0.htm. Configuring IBM MQ In IBM MQ, create a queue manager with the following queues. EmailOutboundQueue FileLoggerOutboundQueue NotificationPushOutboundQueue SimplePushOutboundQueue UBXOutboundQueue You must also create additional queues for any inbound channels you have installed. Their default names are as follows: TealeafInboundQueue XtifyInboundQueue UBX OpportunityDetect Chapter 3. Deploying Interact Omni-channel Message Orchestrator 13
If you manage your queue manager using runmqsc scripts rather than the Explore GUI, queue names must be bounded with single-quotes to preserve the correct capitalization. For example: define qlocal( EmailOutboundQueue ) Configuring authentication (IDPWOS) MQ with settings: The following commands should be executed via runmqsc from your queue manager. 1. ALTER QMGR CHLAUTH(DISABLED) If CHLAUTH is enabled, any client with administrator access is automatically blocked from accessing MQ, regardless of all other settings. 2. DEFINE AUTHINFO(OMO.AUTH.IDPWOS) AUTHTYPE(IDPWOS) CHCKCLNT(REQUIRED) Create an AUTHINFO object. CHCKCLNT can be given various values, depending on how strict you want your authentication requirements to be. v NONE - Username and password are not checked at all. v OPTIONAL - Clients can connect with no username and password. However, if they are provided, they must be valid or the connection is blocked. v REQUIRED - All connections are blocked unless clients provide a valid username and password. v REQDADM - Clients with administrator access behave the same as REQUIRED. Non-privileged clients behave the same as OPTIONAL. Note: Even if IBM Interact is installed on the same machine as the MQ server and accesses it via localhost, CHCKCLNT is still used, not CHCKLOCL. 4.ALTER QMGR CONNAUTH(OMO.AUTH.IDPWOS) Ensure that the queue manager is using the correct AUTHINFO object. 5.Refresh secruity Ensure that the updated security settings are used. No restart is required. Note: Not every setup needs to match this exactly. For more detailed information on security and authorization IBM MQ, see the official IBM MQ documentation: http:/www.ibm.com/support/knowledgecenter/ssfksj_8.0.0/ com.ibm.mq.sec.doc/q009710_.htm User groups IBM MQ uses OS-level user groups to determine what level of access a client should have. Clients (both local and remote) must belong to a user group that MQ recognizes in order to connect to queue managers. By default, MQ creates the mqm group, which has full administrative access. Instructions on how to modify user groups on various operating systems can be found here: http://www.ibm.com/support/knowledgecenter/ssfksj_8.0.0/ com.ibm.mq.sec.doc/q010890_.htm. If CHCKCLNT is set to require a password, create an OS-level username and password on the machine that runs the MQ application. Add that user to the mqm group (or another group that you have configured for this purpose). This is the 14 IBM Interact Omni-channel Message Orchestrator Guide
username and password that Omni-channel Message Orchestrator is expected to provide. The username and password cannot be more than 12 characters long. If the OS-level username of the user, which runs Interact's application server, is different from the username created above, that name must also be added to the mqm group on the MQ server machine. This step is necessary no matter how permissive your IDPWOS auth settings are. If this user name is longer than 12 characters, it will be truncated. If any inbound endpoint runs on a different user, that username must also be added to the mqm group on the MQ server's machine, as above. Example: Machine #1 is running Linux. It has a user root, which was used to install and run the IBM MQ application, and a user mq_user01, which was just created with the password Paswd01 to serve as the MQ client. Machine #2 is running Windows. It has a user Administrator, which is running Interact Omni-channel Message Orchestrator and Interact on a WebLogic application server. Machine #3 is running Windows. It has a user DetectAdmin, which is running IBM Opportunity Detect. On Machine #1, mq_user01, DetectAdmin, and Administrato (because Administrator is 13 characters) would all need to be added to the mqm group using the usermod command. Omni-channel Message Orchestrator and Opportunity Detect could then both provide mq_user01 and Paswd01 as their MQ username and password. If Administrato and mq_user01 were in user groups with different MQ access levels, the ADOPTCTX setting would determine which one will be used for any subsequent MQ tasks after the connection is established. ALTER AUTHINFO(OMO.AUTH.IDPWOS) AUTHTYPE(IDPWOS) ADOPTCTX(YES) would result in all commands being processed on the behalf of mq_user01. ADOPTCTX(NO) means that all commands are processed on the behalf of Administrato. Preparing the IBM MQ JAR files The machine that runs Omni-channel Message Orchestrator and Interact must have certain IBM MQ jar files available in order for the connection factories to work. If IBM MQ is already installed on the machine, the JAR files you need are already packaged with the IBM MQ installation. Add the following two JAR files to the system-level CLASSPATH environment variable. In Windows, the JAR files are automatically added when IBM MQ was installed. [MQ_HOME]\java\bin\com.ibm.mq.jar [MQ_HOME]\java\bin\com.ibm.mqjms.jar If IBM 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 Omni-channel Message Orchestrator server and manually add them to CLASSPATH. For instructions on how to install the necessary JAR files, see http:// www.ibm.com/support/docview.wss?uid=swg21376217. Chapter 3. Deploying Interact Omni-channel Message Orchestrator 15
Your application server needs to be running Java 1.7 or higher, as IBM MQ v8 JAR files do not support Java 1.6. Note: WebSphere Application Server comes pre-packaged with IBM MQ support and does not require any additional JAR files. However, due to a classloader conflict, IBM MQ JARs and Interact's ActiveMQ JAR cannot both be active on the application server at the same time. As a workaround, the ActiveMQ JAR can be removed from interactrt.war using the following steps: 1. Navigate to the directory: <WAS_HOME>/AppServer/profiles/<SERVER_NAME>/ installedapps/<node_name>/interactrt_war.ear/interactrt.war/web-inf/lib 2. Back up and delete activemq-all.jar. 3. Restart the application server. Configuring Omni-channel Message Orchestrator producers and consumers Use the following information to configure Omni-channel Message Orchestrator producers and consumers. 1. Locate offerdispatcherconsumer-context.xml and offerdispatcherproducercontext.xml in [OMO_HOME]/conf/outbound/common/IBMMQ. 2. Locate inboundconsumer-context.xml in [OMO_HOME]/conf/inbound/common/ IBMMQ. 3. Each of those three files must be edited as follows. a. Replace [IBM_MQ_HOSTNAME] with the hostname of the IBM MQ server. This can be localhost if Omni-channel Message Orchestrator and MQ are on the same machine. b. Replace [IBM_MQ_LISTENER_PORT] with the listener port associated with the queue manager. This defaults to 1414. c. Replace [IBM_MQ_QUEUE_MANAGER_NAME] with the name of your queue manager. d. If your queue manager is configured to require a username and password, add them to the jmsconnectionfactory bean. Otherwise, leave them as empty strings. 4. Move offerdispatcherconsumer-context.xml and offerdispatcherproducercontext.xml to [OMO_HOME]/conf/outbound/common, replacing the existing files. Rename or back up the existing xml files before replacing the existing files. 5. Move inboundconsumer-context.xml to [OMO_HOME]/conf/inbound/common, replacing the existing file. Rename or back up the existing xml files before replacing the existing files. Verification To verify your IBM MQ configuration, restart the Omni-channel Message Orchestrator AppServer. To verify that the security settings are correct, search the Omni-channel Message Orchestrator AppServer log for Errors or INFO related to security settings. For example, make sure that you do not see any references to ( MQCC_FAILED ) reason 2035 ( MQRC_NOT_AUTHORIZED ) status. If you see INFO: v Check the username/password provided in inbound and outbound xml files. 16 IBM Interact Omni-channel Message Orchestrator Guide
v Check if that user was added to the respective group on the MQ server. Chapter 3. Deploying Interact Omni-channel Message Orchestrator 17
18 IBM Interact Omni-channel Message Orchestrator Guide
Chapter 4. Configuring Interact Omni-channel Message Orchestrator After you deploy Interact Omni-channel Message Orchestrator, you must configure several inbound and outbound properties files. Note: The default encoding for Interact Omni-channel Message Orchestrator properties files is ISO 8859-1 character encoding. Characters that cannot be directly represented in this encoding can be written with Unicode (\uxxxx format). You can use the native2ascii program to convert native encoding to ISO 8859 encoding. See http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/native2ascii.html for more information. Configuring the eventconfig.properties file Use the eventconfig.properties file to enable events for offer dispatching. By default, Interact Omni-channel Message Orchestrator does not send offers for event posts to Interact. To enable an event for offer dispatching, edit the eventconfig.properties file in <OMO install dir>\conf\outbound\common. The key should be the name of the event as it appears in Interact. This is case-sensitive. The value should be the number of offers to request from Interact. A value of 0 disables an event with Interact Omni-channel Message Orchestrator, while a value of 1 or more enables it. The key can also end with a trailing asterisk (*), in which case it matches any event that starts with the value before the asterisk. All events can be enabled by default by editing the globalconfig.properties file and changing the value for the Event.DefaultNumberOfOffersForAllEvent property to be a value greater than 0. The file eventconfig.properties is automatically reloaded. It may take up to five minutes for the changes to take effect. Configuring the globalconfig.properties file Use the globalconfig.properties file to set outbound global variables. The globalconfig.properties file is in <OMO install dir>\conf\outbound\common. Event.DefaultNumberOfOffersForAllEvent Required. This flag enables or disables Interact Omni-channel Message Orchestrator for all events by default. Use 0 to disable Interact Omni-channel Message Orchestrator for all events by default. A positive Copyright IBM Corp. 2014, 2015 19
number enables Interact Omni-channel Message Orchestrator for all events by default. The value is used as the parameter for numberofoffers when calling the Interact API getoffers(). This property can be overridden by the content of the eventconfig.properties on a per event basis. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. Event.DefaultInteractionPoint Required. This name is used as the parameter for interactionpointname when calling the Interact API getoffers(). By default, Interact Omni-channel Message Orchestrator retrieves offers using the interaction point that you configured with this property. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. Event.InteractionPointAttributeName Optional. You can use this parameter to configure Interact Omni-channel Message Orchestrator to look for the name of the interaction point in a postevent session attribute and set the value to the name of the session attribute. This parameter name overrides the default interaction point name. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. ChannelSelector Required. The implementation class name to use to retrieve outbound channel information. The value must be a valid class name including the package name. The default value is =com.ibm.interact.offerorchestration.offerdispatcher. DefaultChannelSelector, which selects one or more channels from the channel attribute of the offer. If you need to use more advanced channel selection heuristics, you can create your own channel selector by writing a java class that implements the com.ibm.interact.offerorchestration.offerdispatcher.channelselector Java interface. Once implemented and added to the classpath, register your implementation in the globalconfig.properties file by editing the value of the ChannelSelector property. You can include your implementing classes in the Interact Omni-channel Message Orchestrator by packaging it in a JAR file and adding that JAR file to <OMO install dir>\lib. The default value for this property is ChannelSelector=com.ibm.interact.offerorchestration.offerdispatcher. DefaultChannelSelector. See Sample code for a sample implementation of a ChannelSelector and the javadoc in <OMO install dir>\javadoc for more information. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. 20 IBM Interact Omni-channel Message Orchestrator Guide
DefaultChannelSelector.OfferChannelAttributeName Required if ChannelSelector=com.ibm.interact.offerorchestration.offerdispatcher. DefaultChannelSelector. By default, Interact Omni-channel Message Orchestrator obtains the channel(s) on which to dispatch an offer using the channel attribute of the offer. To use an offer attribute other than channel, edit this property, and set its value to the name of the offer attribute of your choosing. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. DefaultChannelSelector.MultipleChannelDelimiter Required if ChannelSelector=com.ibm.interact.offerorchestration.offerdispatcher. DefaultChannelSelector. The character to use to delimit multiple values. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. DefaultChannelSelector.maxNumChannels Optional. An integer number that specifies the maximum number of channels on which to deliver an offer. This setting is used if ChannelSelector is set equal to com.ibm.interact.offerorchestration. offerdispatcher.defaultchannelselector. Changes to this property are automatically reloaded. It may take up to 5 minutes to take effect. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. DefaultChannelSelector.SimplePush.requiredConditions, DefaultChannelSelector.NotificationPush.requiredConditions, DefaultChannelSelector.Email.requiredConditions, and DefaultChannelSelector.SMS.requiredConditions Optional. Conditional boolean expression to specify whether a given channel should be used or not for a given offer and/or profile. Offer Attributes should use the offer. prefix and profile attributes should use the profile. prefix. The expressions use the same language as Interact and Campaign flowcharts, with the exception of the additional offer. and profile. prefixes. Changes to this property are automatically reloaded. It may take up to 5 minutes to take effect. Format: DefaultChannelSelector.[channelName].requiredConditions=[condition] [channelname] is the name of a given channel, as specified by an offer (and in the outboundgatewayconfig.properties file ), and [condition] is the expression to evaluate for that channel. Changes to this property will be automatically reloaded. It may take up to 5 minutes to take effect. Chapter 4. Configuring Interact Omni-channel Message Orchestrator 21
Example: DefaultChannelSelector.SimplePush.requiredConditions=profile.xidAttr!= null DefaultChannelSelector.NotificationPush.requiredConditions=profile.xidAttr!= null DefaultChannelSelector.Email.requiredConditions=profile.emailAddress!= null && profile.subscribedmarketingcategories like STRING_CONCAT("%",offer.marketingCategory,"%") DefaultChannelSelector.SMS.requiredConditions=profile.phoneNumber!= null MaximumOOOThreadPoolSize Required. Use this property to change the maximum number of threads for the thread pool to handle Interact Omni-channel Message Orchestrator. Each Interact Omni-channel Message Orchestrator request runs on a new thread from the thread pool. This integer number defines the size of the thread pool. The default value is 20 threads. A restart of the Interact runtime environment is required for changes to this property to take effect. MaximumEndSessionWaitTime Required. Use this property to change the maximum time (in milliseconds) to wait for active Interact Omni-channel Message Orchestrator threads before allowing call to the Interact API endsession() to proceed. When a call to endsession() is made, Interact Omni-channel Message Orchestrator forces the endsession call to wait for any active Interact Omni-channel Message Orchestrator threads to finish retrieving the profile and the offers. It waits for up to the value for this property (in milliseconds), before allowing the endsession() to proceed. Note: It does not wait for the OutboundGateway to finish sending the offer when the JMS backed dispatcher is used. It only waits for the offer message to be placed in the queue and then releases the wait lock. A restart of the Interact runtime environment is required for changes to this property to take effect. OfferDispatcher Required. Interact Omni-channel Message Orchestrator can be configured with either an in memory offer dispatcher or a JMS backed offer dispatcher. Interact Omni-channel Message Orchestrator includes two OfferDispatcher implementations, an in memory dispatcher and a JMS backed dispatcher. You should use the JMS backed dispatcher when possible for performance and reliability reasons. However, you can also provide your own implementation of an OfferDispatcher by subclassing one of the provided implementations or implementing the com.ibm.interact.offerorchestration.offerdispatcher.offerdispatcher java interface. To register your custom implementation, ensure that your implementation is available in the classpath, and edit the OfferDispatcher in the globalconfig.properties file. Set the value to the package qualified name of your implementing class. You can include your implementing 22 IBM Interact Omni-channel Message Orchestrator Guide
classes in the Interact Omni-channel Message Orchestrator by packaging it in a JAR file and adding that JAR file to <OMO install dir>\lib. For example, OfferDispatcher=com.yourcompany.interact.offerorchestration. offerdispatcher.mycustomerofferdispatcher See Sample code for a sample implementation of an OfferDispatch and the javadoc in <OMO install dir>\javadoc for more information. A restart of the Interact runtime environment is required for changes to this property to take effect. OfferDispatcherJMSImpl.JMSBrokerURL Required if OfferDispatcher=com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherJMSImpl. This property can be used to configure the ActiveMQ JMS server. The JMS queue broker URL to point to the JMS queue server. A restart of the Interact runtime environment is required for changes to this property to take effect. OfferDispatcherJMSImpl.JMSMaximumRedeliveries Required if OfferDispatcher=com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherJMSImpl. This property can be used to configure the ActiveMQ JMS server. The maximum number of times a message is redelivered with the JMS queue. A restart of the Interact runtime environment is required for changes to this property to take effect. OfferDispatcherJMSImpl.JMSInitialRedeliveryDelay Required if OfferDispatcher=com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherJMSImpl. This property can be used to configure the ActiveMQ JMS server. The initial redelivery delay in milliseconds when a message is redelivered with the JMS queue. A restart of the Interact runtime environment is required for changes to this property to take effect. OfferDispatcherJMSImpl.JMSUseExponentialBackOff Chapter 4. Configuring Interact Omni-channel Message Orchestrator 23
Required if OfferDispatcher=com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherJMSImpl. This property can be used to configure the ActiveMQ JMS server. This property indicates if the exponential back-off should be used to exponentially increase the timeout. A restart of the Interact runtime environment is required for changes to this property to take effect. OfferDispatcherJMSImpl.JMSBackOffMultiplier Required if OfferDispatcher=com.ibm.interact.offerorchestration.offerdispatcher. OfferDispatcherJMSImpl. This property can be used to configure the ActiveMQ JMS server. The back-off multiplier. A restart of the Interact runtime environment is required for changes to this property to take effect. Configuring the outboundgatewayconfig.properties file Use the outboundgatewayconfig.properties file to register your OutboundGateway. The default Interact Omni-channel Message Orchestrator offer dispatcher dispatches offers on the channel of your choosing. To do so, an OutboundGateway must be registered for each channel returned by the channel selector. To register an OutboundGateway for your channel(s), edit the outboundgatewayconfig.properties file in <OMO install dir>\conf\outbound\common, and add an entry for each of your channels. The key should be the name of the channel. The key is case-sensitive. The value should be the package qualified name of the Java class that implements the OutboundGateway interface. A sample implementation is provided that logs the offer to a file and is registered by default in the outboundgatewayconfig.properties file. FileLogger=com.ibm.interact.offerorchestration.outboundgateway. FileLoggerOutboundGateway Additional gateway implementations, such as mobile push and email, can also be found on the Interact Omni-channel Message Orchestrator developerworks community. For more information, see https://www.ibm.com/developerworks/ community/wikis/home?lang=en#!/wiki/ W214f7731a379_4712_a1ce_5d7a833d4cca/page/Interact%20Omni-channel %20Message%20Orchestrator. You can also implement your own OutboundGateways by implementing the com.ibm.interact.offerorchestration.outboundgateway.outboundgateway Java interface. You can include your implementing classes in the Interact Omni-channel Message Orchestrator by packaging it in a JAR file and adding that JAR file to <OMO install dir>\lib. 24 IBM Interact Omni-channel Message Orchestrator Guide