Configure the IBM MQ Bridge to Salesforce

We can configure IBM MQ and enter IBM MQ Bridge to Salesforce parameters to create the configuration file and connect Salesforce push topics and platform events to the IBM MQ queue manager.

Before starting

This task takes you through the minimal setup that is needed to create the IBM MQ Bridge to Salesforce configuration file and successfully connect to Salesforce and IBM MQ so that we can subscribe to Salesforce push topics and platform events. For more information on the meaning and options for all the parameters, see the runmqsfb command. We must consider your own security requirements and customize the parameters appropriate to your deployment.

To create the configuration for creating event messages for Salesforce platform events, see Create event messages for Salesforce platform events.

Subscribing to Salesforce push topics and platform events

When the IBM MQ Bridge to Salesforce establishes connections to both Salesforce and IBM MQ, it creates subscriptions to Salesforce push topics and platform events. The push topic or platform event name that the bridge wants to subscribe to, must be included in the configuration file or added in the command line before the connection is made.

One of the configuration attributes is the root of the IBM MQ topic tree and the events are published beneath this root. The bridge accesses this root and adds the full Salesforce topic name, for example, /MQ/SF/ROOT/topic/EscalatedCases. The monitoring topic and applications that are connecting to IBM MQ might look for push topics under /topic/EscalatedCases and platform events under /event/NewCustomer__e.

The published message contains control information and the data structure that contains the requested data fields. For push topics, the data structure is an sobject and for platform events, the structure is payload. The bridge cannot subscribe to a topic or an event if they are not defined in Salesforce. If the bridge encounters an error when it tries to subscribe to a topic, the bridge stops.

A topic object does not need to be defined in IBM MQ but suitable authorities must exist, based on the closest parent element in the tree. The republished message contains only the relevant data structure from the original message by default. The control information is removed. For platform events, the publication has a payload structure. The Publish control data with the payload configuration option in the Behaviour of bridge program set of configuration parameters enables the republication of the entire message, including the control data. For more information, see Configuration parameters.

At-most-once

The bridge does not use the ReplayId for restart. After restart of the bridge, only newly generated push topics and platform events are processed. Applications must be prepared to deal with missing publications. The ReplayId is still tracked by the bridge and hardened to a queue, so the bridge can be restarted with the other quality of service and know the current state.

At-least-once

The ReplayId is tracked by the bridge and hardened to a queue. On restart of the bridge, the persisted ReplayId is used to request the starting point for publications from the server. Provided the gap was no more than 24 hours, older publications are sent. The ReplayId for a topic is not hardened on every message. It is written in a persistent message at regular intervals and when the bridge is shut down. Applications must be prepared to see duplicate publications.

The ReplayId is written as a message to a newly defined queue. We must define this queue, SYSTEM.SALESFORCE.SYNCQ, before the bridge is started. If the SYSTEM.SALESFORCE.SYNCQ does not exist, the bridge does not continue, regardless of the quality of service mode. An MQSC script is provided for creating the queue with relevant attributes. The queue must be configured with the DEFSOPT(EXCL) NOSHARE option to ensure that only one instance of the bridge program can update the SYSTEM.SALESFORCE.SYNCQ queue.

To create the configuration for creating event messages for platform events, see Create event messages for Salesforce platform events.

Procedure

1. Create and start a queue manager.
   1. Create a queue manager, for example SQM1.

      crtmqm SQM1

   2. Start your queue manager.

      strmqm SQM1

2. Optional: Note: To use existing login and security Salesforce credentials and self-signed certificate, skip to step 4. Create a security token for the Salesforce account.
   1. Log in to your Salesforce account.
   2. Create or reset your security token by following the steps in the help article Salesforce help: Reset your security token.

3. Create a self-signed security certificate in Salesforce.
   1. Select Security controls from the Administer menu of our Force.com Home page, then Certificate and Key Management. The Certificate and Key Management page opens.
   2. Click Create Self-Signed certificate. The Certificates page opens.
   3. Enter a name for the certificate in the Label field, press Tab, then click Save. The Certificate and Key Detail information is displayed.
   4. Click Back to list: Certificates and keys.
   5. Click Export to Keystore.
   6. Enter a password for the keystore, then click Export.
   7. Save the exported keystore to your local file system.

4. Use the IBM Key Management GUI to open the keystore you exported from Salesforce and populate the signer certificates.
   1. Run the strmqikm command to open the IBM Key Management GUI. For more information, see Use runmqckm, runmqakm, and strmqikm to manage digital certificates.
   2. Click Open a key database file and browse to the location of the Salesforce keystore.
   3. Click Open, make sure to select JKS from the Key database type options, then click OK.
   4. Enter the password that you created for the keystore in step 3f, then click OK.
   5. Select Signer Certificates from the Key database content options.
   6. Click Populate.
   7. Select the Verisign Inc. check box from the Add CA Certificates list, then click OK.

5. Optional: Generate OAuth consumer key and secret by creating an app connection for IBM MQ Bridge to Salesforce in your Salesforce account. You need the Consumer Key and Consumer Secret codes when we are using the IBM MQ Bridge to Salesforce in production environments.
   1. Select Create, then Apps from the Build menu of our Force.com Home page. The Apps page opens.
   2. Click New from the Connected Apps section. The New Connected App page opens.
   3. Enter a name for the IBM MQ Bridge to Salesforce in the Connected App Name, for example MQBridgeToSalesforce.
   4. Enter the API Name. If you tab through to the next field, the Connected App Name is copied into the API Name name field.
   5. Enter your Contact Email.
   6. Select the Enable OAuth Settings option in the API (Enable OAuth Settings) section. Further options in that section are then presented.
   7. Add your Callback URL, for example https://www.ibm.com.
   8. Select the Full access (full) option from the Available OAuth Scopes list in the Selected OAuth Scopes subsection, then click Add, to add full access to the Selected OAuth Scopes list.
   9. Click Save.
   10. Click Continue.
   11. Take note of our Consumer Key and Consumer Secret codes.

6. Create the required synchronization queue on the queue manager.

   cat /opt/mqm/mqsf/samp/mqsfbSyncQ.mqsc | runmqsc SQM1

   The synchronization queue maintains event state across application or queue manager restarts. The queue depth can be small as only a single message is expected on the queue. Only one instance of the bridge can run at a time against this queue, so the default options are set for exclusive access.
7. Create a configuration file with connection and security parameters for IBM MQ, Salesforce, and the IBM MQ Bridge to Salesforce behavior.

   runmqsfb -o new_config.cfg

   The existing values are shown inside the brackets. Press Enter to accept existing values, press Space then Enter to clear values, and, type, then Enter to add new values.
   1. Enter values for the connection to queue manager SQM1: Minimum values that are needed for the connection are queue manager name, IBM MQ base topic root, and channel name.

      Connection to Queue Manager
      ---------------------------
      Queue Manager or JNDI CF   : []SQM1
      MQ Base Topic              : []/sf
      MQ Channel                 : []A channel you have defined or for example SYSTEM.DEF.SVRCONN
      MQ Conname                 : []
      MQ Publication Error Queue : [SYSTEM.SALESFORCE.ERRORQ]
      MQ CCDT URL                : []
      JNDI implementation class  : [com.sun.jndi.fscontext.RefFSContextFactory]
      JNDI provider URL          : []
      MQ Userid                  : []
      MQ Password                : []

      Note: Channel name is not required if we are connecting locally. You don't have to provide the queue manager name and base topic in the configuration file as they can be included on the command line later, when you run the bridge.
   2. Enter values for connection to Salesforce: Minimum values that are needed for the connection are Salesforce user ID, password, security token, and login endpoint. In production environments, we can add the consumer key and secret for OAuth security.

      Connection to Salesforce
      ------------------------
      Salesforce Userid (reqd)   : []salesforce_login_email
      Salesforce Password (reqd) : []salesforce_login_password        
      Security Token (reqd)      : []Security_Token 
      Login Endpoint             : [https://login.salesforce.com]
      Consumer ID                : []
      Consumer Secret Key        : []
      

   3. Enter values for certificate stores for TLS connections: Minimum values that are needed for TLS connections are the path to the keystore for TLS certificates and keystore password. If no trusted store path or password is provided, the keystore and password parameters are used for the trusted store and password. If we are using TLS for the IBM MQ queue manager connection, we can use the same keystore.

      Certificate stores for TLS connections
      --------------------------------------
      Personal keystore for TLS certificates : []path_to_keystore, for example: /var/mqm/qmgrs/SQM1/ssl/key.jks
      Keystore password          : []keystore_password
      Trusted store for signer certificates : []
      Trusted store password     : []
      Use TLS for MQ connection  : [N]
      

   4. Enter values to configure the behavior of the IBM MQ Bridge to Salesforce: You do not have to change or provide any of these values but if you know your push topic or platform event names, add them here. They can also be added later, in the command line, when we are ready to run the bridge. We must specify the log file, in the configuration file or on the command line.

      Behaviour of bridge program
      ---------------------------
      PushTopic Names          : []
      Platform Event Names     : []
      MQ Monitoring Frequency  : [30]
      At-least-once delivery? (Y/N) : [Y]
      Subscribe to MQ publications for platform events? (Y/N) : [N]
      Publish control data with the payload? (Y/N) : [N]
      Delay before starting to process events : [0]
      Runtime logfile for copy of stdout/stderr : []

8. Optional: Create the IBM MQ service to control the execution of the program. Edit the sample mqsfbService.mqsc file to point to the newly created configuration file and make any other changes to the command parameters.

   cat modified mqsfbService.mqsc | runmqsc SQM1

9. Optional: Follow instructions in Getting started with the IBM MQ Console to set up the IBM MQ Console.
10. Optional: Note: Before we can see any data about the bridge in MQ Console, we must run the bridge at least once so that when it is started, it makes the connections to Salesforce and IBM MQ. The meta-topics for the bridge are published at bridge start up. Add and configure widgets in the IBM MQ Console instance to view Salesforce data.
    1. Click Add widget. The new widget opens.
    2. Select Charts
    3. Click Configure widget icon in the title bar of the new widget.
    4. Optional: Enter a Widget title.
    5. Select Salesforce Bridge, from the Resource to monitor, Source drop-down menu.
    6. Click Save.

Results

What to do next

Related information

• runmqsfb (run IBM MQ Bridge to Salesforce)
• Tracing the IBM MQ Bridge to Salesforce
• Monitor the IBM MQ Bridge to Salesforce