Create event messages for Salesforce platform events

We can configure IBM MQ and enter IBM MQ Bridge to Salesforce parameters to create the configuration file and use the bridge to create event messages for Salesforce platform events.


Before starting

  • You installed the MQSeriesSFBridge package in the IBM MQ installation on an x86-64 Linux platform.


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 create event messages for Salesforce platform events. For more information on the meaning and options for all the parameters, see the runmqsfb command. You must consider your own security requirements and customize the parameters appropriate to your deployment.

To create the configuration for subscribing to push topics and platform events, see Configure the IBM MQ Bridge to Salesforce.

    Create event messages for Salesforce platform events

We can use an IBM MQ application to create messages that are put on a queue manager topic /root/mqtosfb/event/+. The bridge subscribes to the topic, gets content from the messages, and uses it to publish event messages for a Salesforce platform event. For more information on platform events, see Delivering custom notifications with platform events in Salesforce developer documentation. To enable the bridge to create event messages, we must provide two attributes that are additional to those used for subscribing to push topics and platform events:

  • Create and add the name of the MQ Publication Error Queue in the bridge configuration attributes for Connection to Queue Manager.
  • Set the Subscribe to MQ publications for platform events option to Y, in the bridge configuration attributes for defining the Behavior of bridge program.

We need to create a platform event in Salesforce and define the content fields before we can use the bridge to create event messages for that platform event. The platform event name and its contents determine how we need to format the IBM MQ message that is processed by the bridge. For example, if your Salesforce platform event Object name is MQPlatformEvent1 and your two custom defined fields are text fields with the API name MyText__c and Name__c, then the IBM MQ message that is published on the /root/mqtosfb/event/MQPlatformEvent1__e topic must be a correctly formatted JSON, as follows:

{ "MyText__c" : "Some text here", "Name__c" : "Bob Smith" }
See step 7 to create the platform event in Salesforce or skip this step if you already have a platform event that we want to create event messages for. We have to format the IBM MQ message to match the fields that are set in your Salesforce platform event. Fields within the Salesforce platform event can be designated as optional or mandatory. For more information, see Platform Event Fields in the Salesforce developer documentation. When the bridge is running, it subscribes to the designated IBM MQ topic.

  • If you specify the At-most-once quality of service in the bridge configuration, the subscription that the bridge makes is non-durable. Any publications that are made by IBM MQ applications while the bridge is not running are not processed.
  • If you specify the At-least-once quality of service in the bridge configuration, the subscription the bridge makes is durable. This means that the bridge can process publications that are made by IBM MQ applications while the bridge is not running. Durable subscriptions require a known subscription and client ID. The bridge uses D_SUB_RUNMQSFB as the subscription name and runmqsfb_1 as the client ID.

If the bridge is used for subscribing to Salesforce push topics and platform events, and not for creating event messages, it attempts to delete the durable subscription, in case the configuration is changed, and the subscription is now orphaned.

We can remove durable subscriptions that the bridge creates as follows:

    Use the IBM MQ Explorer.
    Open the subscriptions folder for the queue manager that the bridge is using and look for the subscription name that ends in :D_SUB_RUNMQSFB where the topic string is /sf/mqtosfb/event+. Right-click the subscription name and click delete. If you get an error that indicates that the subscription is in use, your bridge might still be running. Stop the bridge and try to delete the subscription again.

    Use runmqsc to find and delete the subscription.
    Start the runmqsc interface and run DISPLAY SUB (*). Look for the subscription name SUB ending in :D_SUB_RUNMQSFB. Issue the delete sub command and include the SUBID of the subscription we want to delete. For example, DELETE SUB SUBID(414D5120514D312020202020202020205C589459987E8620)

    Stop, then start the bridge with the At-most-once quality of service.
    If you started the bridge with the At-least-once quality of service At-least-once delivery? (Y/N) :[Y], the subscription that is created is durable. To delete the subscription, change the quality of service to At-least-once delivery? (Y/N) :[N] in your configuration file and restart the bridge. The durable subscription is deleted and a non-durable subscription is created.


Procedure

  1. Create and start a queue manager.
    1. Create a queue manager, for example PEQM1. 
      crtmqm PEQM1
    2. Start your queue manager. 
      strmqm PEQM1

  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 and error queues on the queue manager. 
    cat /opt/mqm/mqsf/samp/mqsfbSyncQ.mqsc | runmqsc PEQM1
    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. The error queue must be created before we can use the bridge to create event messages for platform events. The error queue is used for messages that cannot successfully be processed by Salesforce. We must add the error queue name in the bridge configuration parameter section Connection to Queue Manager as shown in step 8.a.
  7. Optional: Create a platform event object in your Salesforce account.
    1. Select Platform Events from the Develop menu of your Force.com Home page, then click New Platform Event. The New Platform Event page opens.
    2. Complete the Label and Plural Label fields.
    3. Click Save. The Platform Event Definition Detail page opens.
    4. Define the Custom Fields & Relationships. For example, you might add two text fields with labels MyText and Name and set the Data Type field lengths to Text(64) and Text(32) respectively.

    You created a platform event and defined Custom Fields and Relationships for it. Use the platform event Platform Object name or the API name as the IBM MQ topic to which we can put messages that we want the bridge to process. For example, you might use the AMQSPUBA sample to add the following JSON formatted message to the /sf/mqtosfb/event/Salesforce Platform Object Name/API name topic:

    { "MyText__c" : "Some text here", "Name__c" : "Bob Smith" }
    We can run the AMQSPUBA sample to create messages after the bridge started. From the MQ installation location/samp/bin directory, issue the following command:
    ./amqspub /sf/mqtosfb/event/Salesforce Platform Object Name/API name PEQM1
    At the prompt, enter the message in JSON format.
  8. 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 PEQM1: Minimum values that are needed for the connection are queue manager name, IBM MQ base topic root, error queue name, and channel name.
      Connection to Queue Manager
---------------------------
Queue Manager or JNDI CF   : []PEQM1
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: If we are connecting locally, the channel name is not required. 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 userid, 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/PEQM1/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: We must change the Subscribe to MQ publications for platform events option from the default N, to Y, to use the bridge to create event messages. You also 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) : [Y]
Publish control data with the payload? (Y/N) : [N]
Delay before starting to process events : [0]
Runtime logfile for copy of stdout/stderr : []

  9. 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 PEQM1
  10. Optional: Follow instructions in Getting started with the IBM MQ Console to set up the IBM MQ Console.
  11. Optional: 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. Select Bridge Status, from the Resource class, drop-down menu.
    7. Select MQ-created Platform Events, from the Resource type, drop-down menu.
    8. Select Total MQ-created Platform Events, from the Resource element, drop-down menu.
    9. Click Save.

    You configured the IBM MQ Console for showing the total number of IBM MQ created platform events. When the bridge is running and you start putting messages on the /sf/mqtosfb/event/Salesforce Platform Object Name/API name topic, the widget shows the number of total message events that the bridge created.

Parent topic: Configure IBM MQ for use with Salesforce push topics and platform events