runmqsfb (run IBM MQ Bridge to Salesforce)

Configure and run the IBM MQ Bridge to Salesforce.


Syntax

The diagram shows the syntax for the runmqsfb command usage as described in note 1.

runmqsfb  -f InputFileName  -r logFile
  •  -o outputConfigFile
  •  -m QMgrName
  •  -t TopicString
  •  -e EventName
  •  -p PushtopicName
  •  -d DebugLevel
  •  -i interval
  •  -w WaitTime
  •  -k killFile


  • Usage notes

    1. We can run the runmqsfb command to start the IBM MQ Bridge to Salesforce and connect to Salesforce and IBM MQ. When the connections are made, the bridge receives Salesforce generated events and publishes them to an IBM MQ network, or create event messages for Salesforce platform events.
      runmqsfb -f configFile -r logFile -m QMgrName -t TopicString -e EventName -p PushtopicName -d debugLevel -i interval -w WaitTime -k killFile
      When we use the command for runtime processing, the required parameters are -f, with the name of the previously created configuration file, and -r with the name of the log file. When the other command parameters are also given on the command line, they override the values in the configuration file. The option allows a core default configuration to be created and provides a simple way to handle minor variations such as the queue manager name.
    2. We can also use the runmqsfb command to generate a configuration file that is used to define the parameters that are needed to connect to Salesforce and IBM MQ. When you are creating the configuration file, the -f parameter is optional, the input configuration file is included in the samples directory for the IBM MQ Bridge to Salesforce, /opt/mqm/mqsf/samp.
      runmqsfb -[f inputConfigFile] -o outputConfigFile
      When you run the command in this way, you are prompted to enter values for each of the configuration parameters. To keep an existing value press Enter. To remove an existing value press Space, then Enter. For more information, see Configuration parameters.


    Command line parameters

      -m QMgrName or ConnFactoryName
      Queue manager or Connection Factory name.
      -r logFile
      Required. Location and name of the log file for trace information. We can specify the log file path and name in the configuration file or on the command line.
      -t TopicString
      IBM MQ topic root.
      -e EventName
      Salesforce platform event name (can repeat). We can specify multiple -e entries on the command line, one for each event type that the bridge listens for. You must provide the base part of the event name. The bridge automatically adds "/event" or "/topic" prefixes when it connects to Salesforce. Multiple -e parameters can be comma-separated.
      -p PushtopicName
      Salesforce push topic name (can repeat). We can specify multiple -p entries on the command line, one for each topic type that the bridge listens for. You must provide the base part of the topic name. The bridge automatically adds "/event" or "/topic" prefixes when it connects to Salesforce. Multiple -p parameters can be comma-separated.
      -i interval
      Monitor interval. Enter 0 to disable monitoring.
      -f inputConfigFile
      Configuration file. The -f parameter is required when you are running the runmqsfb command to start the IBM MQ Bridge to Salesforce, as described in usage note 1. We can optionally use the -f parameter to reuse some of the values from an existing inputConfigFile, as described in usage note 2, and also enter some of the new values. If we do not specify the -f parameter when you are creating the configuration file, all the values for the parameters you are prompted for are empty.
      -o outputConfigFile
      New configuration file. When you run the command with the -o parameter, runmqsfb command loads existing configuration values from the -f file and prompts for new values for each configuration parameter.
      -k killFile
      A file to cause the bridge to exit. When you run the command with the -k parameter and specify a file, if the file exists, it causes the bridge program to exit. Using this file is an alternative way to stop the program when we don't want to use Ctrl+C or kill command. The file is deleted by the bridge on startup in case it exists. If the deletion fails, the bridge abends but monitors for the recreation of the file.
      -d debugLevel
      Debug level, 1, or 2.

        1
        Terse debug information is displayed.

        2
        Verbose debug information is displayed.

      -w WaitTime
      Wait before fully starting.


    Configuration parameters

    When you run the runmqsfb command to create the configuration file, the parameters are stepped through in four groups. Passwords are obfuscated and are not displayed as you type. The generated configuration file is in JSON format. You must use the runmqsfb command to create the configuration file. We cannot edit the passwords and security certificate information directly in the JSON file.

      Connection to queue manager
      Parameters relating to the IBM MQ queue manager.

        IBM MQ Queue manager or JNDI CF
        Required.
        IBM MQ Base Topic
        Required. All events are published by using the topic root as the prefix to the Salesforce event name.
        IBM MQ Channel
        Blank channel implies local bindings.
        IBM MQ Conname
        Uses standard connection name format of "host(port), host(port)" to enable multiple destinations such as for multi-instance queue managers. Blank conname implies local bindings.
        IBM MQ Publication Error Queue
        Required for creating platform event messages. IBM MQ error queue for processing bad input messages. The default queue SYSTEM.SALESFORCE.ERRORQ is created when you run the mqsfbSyncQ.mqsc script command that also creates the required synchronization queue on the queue manager.
        IBM MQ CCDT URL
        If a TLS connection is required to the queue manager, you must use a JNDI or CCDT definition.
        JNDI implementation class name
        The class name of your JNDI provider. The "queue manager name" parameter refers to the connection factory name when you are using JNDI.
        JNDI provider URL
        The endpoint of your JNDI service.
        IBM MQ UserId
        IBM MQ Password

      Connection to Salesforce
      Parameters relating to Salesforce.

        Salesforce Userid (required)
        Required. Log in email for your Salesforce account.
        Salesforce password (required)
        Required. Password for your Salesforce account.
        Salesforce security token (required)
        Required. Security token that we can generate from the Security controls section of the Administer menu of your Salesforce Force.com Home page.
        Login Endpoint
        Salesforce login endpoint URL, https://login.salesforce.com.
        Consumer key
        The consumer key that you generate when you add the IBM MQ Bridge to Salesforce as a connected app in your Salesforce account. For more information, see step 5 in Configure the IBM MQ Bridge to Salesforce
        Consumer secret
        The consumer secret that is generated along with the consumer key.

      OAuth consumer key and secret values are optional but must be considered for production systems.

      Certificate stores for TLS connections
      Parameters relating to certificate stores for TLS connections.

        Personal keystore for TLS certificates
        Required. The keystore that you create in your Salesforce account. For more information, see Step 3 in Configure the IBM MQ Bridge to Salesforce.
        Keystore password
        Required. The password that you create when you are exporting the keystore from your Salesforce account.
        Trusted store for signer certificates
        Required. If we do not add the trusted store, the personal keystore for TLS certificates is used.
        Trusted store password
        Required. If the personal keystore for TLS certificates is used, this is the password for the keystore for TLS certificates.
        Use TLS for MQ connection
        If you are using TLS for your IBM MQ connectivity, we can use the same keystore that we used to connect to Salesforce.

      For the Salesforce connection, a truststore must be available and contain at least the signer certificates to validate the Salesforce system. Only TLS1.1 and TLS1.2 protocols are supported for connection to Salesforce. A user certificate is not required. If we don't provide a truststore parameter, the keystore is used for both roles. The stores can be the same as the one configured for the IBM MQ connection in the CCDT or JNDI.

      Behavior of bridge program
      Parameters relating to the behavior of the IBM MQ Bridge to Salesforce.

        Push topic names
        We can provide one push topic name at a time and then move on to the next parameter by pressing enter.
        Platform event names
        We can provide one platform event name at a time and then move on to the next parameter by pressing enter.
        Monitor frequency
        IBM MQ Monitoring frequency.
        At least once delivery
        Quality of service. At-least-once or at-most-once delivery.
        Subscribe to IBM MQ publications for platform events
        Required. The default option is N. You must enter Y to enable the bridge feature for creating event messages for Salesforce platform events.
        Publish control data with the payload
        On republish, send full message not only subject.
        Delay before starting to process events
        Delay before the bridge starts to process events.
        Runtime logfile for copy of stdout/stderr
        Path to and name of the log file for the tracing information.

    Push topic names and Platform event names can be entered individually or as a comma-separated list, in the same way as the command line -p and -e parameters are entered. The Startup wait interval provides an option to delay the initial processing of events. For example, if the bridge and the IBM MQ applications that use it are all run as services, the order in which they start cannot be sequenced. Therefore, events might be republished before applications are prepared to receive them. When you delay the bridge startup, you give the applications the time to start and subscribe to events and push topics.

    The configuration is only read on startup of the bridge process. Changes to the configuration require a restart, such as through the IBM MQ Service definitions.


    Examples

    The -f parameter is optional when we use the runmqsfb to create the configuration file as described in the usage note 2.
    runmqsfb -f inputConfigFile -o outputConfigFile
    In this example, the outputConfigFile is created:
    runmqsfb -o outputConfigFile
    The -f parameter is required when we use the runmqsfb command to run the IBM MQ Bridge to Salesforce, as described in the usage note 1.
    runmqsfb -f inputConfigFile -r logFile