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.

Usage notes

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.
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 we 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, we 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.
From IBM MQ Version 9.2.0, the usage of the enhanced protection parameters is as follows:

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. We 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. We 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 we 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 we are creating the configuration file, all the values for the parameters we are prompted for are empty.

-n ApplicationInstanceName

If we 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.

To have multiple bridges accessing the same queue manager, and having inbound messages from Salesforce, then we 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: he 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:

1: Default, to use the new protection mode.
0: Use the existing protection mode.

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. We 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, we must use a JNDI or CCDT definition.
JNDI implementation class name: The class name of our JNDI provider. The "queue manager name" parameter refers to the connection factory name when we are using JNDI.
JNDI provider URL: The endpoint of our JNDI service.
IBM MQ UserId
IBM MQ Password

Connection to Salesforce

Parameters relating to Salesforce.

Salesforce Userid (required): Required. Log in email for the Salesforce account.
Salesforce password (required): Required. Password for the Salesforce account.
Salesforce security token (required): Required. Security token that we can generate from the Security controls section of the Administer menu of our 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 application 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 we 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 we are using TLS for the 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 TLS 1.1 and TLS 1.2 protocols are supported for connection to Salesforce. A user certificate is not required. If you 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. We 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.

Bridge unique identifier

The default value is no Bridge unique identifier specified.

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.

Treat unknown Salesforce topic as warning

The default option is N.

We must set this option to Y to continue with a warning, instead of exiting if a push topic or an event is not known to Salesforce during the subscribe.

This option can be useful when creation of the topics in Salesforce is done independently, and might not be available immediately. This allows the bridge to run for the topics that are known.

The bridge still needs restarting, or forced through a reconnection sequence, for example, restarting the queue manager, before it tries to subscribe to the topic again.

Continue to retry after maximum reconnection attempts

The default option is N.

We must set this option to Y to not exit after the final retry timer. Instead, keep retrying at the last interval forever.

At-least-once delivery for IBM MQ publications?

The value can be Y or N, and the default value is not set. The value is inherited from another quality of service attribute.

This attribute determines whether a durable or non-durable subscription is made for IBM MQ publications. It separates the existing quality of service, that is:

At-most-once for a non durable subscription, or
At-least-once for a durable subscription

into different attributes for each direction of flow.

This is useful for situations where we want to have at-most-once inbound messages from Salesforce, not bothering with the ReplayId, but still want to send saved outbound messages from IBM MQ (at-least-once) after an outage.

If not set, the existing quality of service value is used. Note that this happens if you have migrated from an older version without updating the configuration file, that is, run the configuration process.

MQ Replay Status Queue

The default value is SYSTEM.SALESFORCE.SYNCQ.

To have multiple bridges accessing the same queue manager, and having inbound messages from Salesforce, then we must have separate synchronization queue settings for each.

Number of logfiles

The default value is 3.

Allow rotating log files for the output recording. If the value is greater than one, the configured log file name is used as a base with ".0", ".1", and so on,appended or inserted before the filetype.

If we use the default value, do not add an index.

Note that normal stdout and stderr handling is unaffected.

Maximum size of each logfile

The default value is 2097152 bytes (2 MB) .

If you configure more than one log file, this is when the log switch is made.

If you configure only one log file, this parameter is ignored.

-sf file

File containing password protection key.

-sp mode

Password protection mode. The values can be:

1: Default, to use the new protection mode.
0: Use the existing protection mode.

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.