runmqsfb (run IBM MQ Bridge to Salesforce)

Usage notes

1. You 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 you 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. You 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 and -b parameters are optional, the input configuration file is included in the samples directory for the IBM MQ Bridge to Salesforce, /opt/mqm/mqsf/samp.

   runmqsfb [-b][-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.
3. From IBM MQ 9.2.0, the usage of the enhanced protection parameters is as follows:

   Configuration mode

   Newly entered passwords are written to the output configuration file protected with the new key. Note that preexisting passwords are not changed in format.

   A warning is issued when the default key is being used, that is, you have not provided a keyfile.

   Provision of passwords in the batch configuration mode, using environment variables, continues unchanged; that is, the value of the environment variables is given in plain text.

   Runtime mode

   When a password is decrypted, warning messages are issued if the password is found to be in the old format, and the name of the parameter causing the warning is given in the message to encourage you to migrate. However, the bridge continues processing commands.

   Note: The warning message is not issued if you have specified the -sp 0 parameter on the command line, as you explicitly wanted to use old formats.

   A warning is also issued when the default key is being used, that is, you have not provided a keyfile.

   Errors occur if a password cannot be decrypted, for example, if you have specified the wrong keyfile.

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. You 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). You 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). You 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. You 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 you 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.

-n ApplicationInstanceName

If you have multiple instances of the bridge on the same queue manager,this option gives you a way to distinguish each instance in the monitoring. This identifier is added to the $SYS topic as part of the application name, so that monitors like amqsrua can get separate metadata trees.

If this option is not empty, the metadata root topic adds "_" together with the selected value to the application name. For example, setting it to "2" results in publications based on

$SYS/Application/runmqsfb_2/INFO/QMGR/<qmgr>/Monitor/METADATA

Note: There is no coordination between running bridge instances, so it is possible to have two instances with the same identifier. The only confusion this causes is in the monitoring statistics.

-q ReplyStatusQueueName

The default value is SYSTEM.SALESFORCE.SYNCQ.

If you want to have multiple bridges accessing the same queue manager, and having inbound messages from Salesforce, then you must have separate synchronization queue settings for each.

If a bridge instance is not subscribed to any Salesforce topics, the synchronization queue is not used at all.

Note: The synchronization queue is accessed exclusively; that is, the bridge will not start if another instance already has the nominated queue open.

-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 you 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.

-b

Use environment variables to drive the configuration, instead of interactive prompts. This allows the configuration to be set programatically.

The environment variables have the format "runmqsfb_<attribute>" where <attribute> is the JSON field in the generated configuration file. For example:

export runmqsfb_QueueManager=QM1

The environment variables are merged with the configuration specified in the inputConfigurationFile (-f option) to create the outputConfigurationFile.

One way of using this method, is for you to interactively create a configuration file that contains common attributes that are to be used by all instances of the IBM MQ Bridge to Salesforce, and then apply environment variables programmatically for just the few instance-unique parameters.

-sf file

File containing password protection key.

-sp mode

Password protection mode. The values can be:

2

Use the latest password protection mode. This is the default value from IBM MQ 9.2.2.

1

Use the IBM MQ 9.2 password protection mode for compatibility with versions earlier than IBM MQ 9.2.2. This is the default value in versions earlier than IBM MQ 9.2.2.

0

Use the deprecated password protection mode that is compatible with versions earlier than IBM MQ 9.2.

Configuration parameters

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.