Configuration of transport services used for a message

Use the following generic methods of the SendMsgCmd command to configure the transport services used for the message:

public void setConfigData(String key, String value) public void setNLConfigData(String key, String language, String value)

These generic methods of the SendMsgCmd command allow the user to configure the transport services used for the message. The key parameter refers to the administration name used to identify the attribute to be changed. The value parameter is the value to be assigned. Invoking these methods cause the values that are specified here to override the values assigned in the Administration Console. The latter method allows native language sensitive configuration data to be set. Refer to the table below containing the default transports available to the messaging system, and the attributes that apply to each.

Note: The language parameter represents the LANGUAGE_ID found in the LANGUAGE table. For example, the subject field found in the following table. See the addMember method for an alternative way of setting email recipients. See the API for information about the Messaging class.

Configuration attributes

The table below shows how the key parameter can be used to configure the message. The default transports available to the Messaging System use the attributes listed in the table.

Notes:
  • If the transport you want to use is not in the list, you can develop your own, following the examples in the Sample adapter topic.
  • Attribute keys are case-sensitive
  • For email addresses:
    • Multiple addresses must be separated by a comma.
    • RFC 822 internet email addresses that contain spaces must be enclosed in double quotation marks. For example, "My company<myco@mycompany.com>".
  • All JMS queue names and the queue connection factory name must correspond with the names of the queue names and queue connection factory defined in the WebSphere Application Server Administration Console.

Viewing overridden properties

The value that is overridden by the command that calls the method cannot be viewed from the Administration Console. However, once the message is created, and before it is sent by the SendTransactedMsg scheduler job, it can be viewed:
  1. Open the Administration Console and select Site on the Administration Console Site/Store Selection page.
  2. Navigate to Monitoring > View Unsent Messages.
  3. Select the desired transport with the Delivery status as Pending.
  4. Click Search.
  5. Click the message ID of the last message on the last page.
  6. The overridden properties, with other properties, are displayed at the top of the page.
Transport Attribute key Description
Email adapter username The user name used to log on to SMTP server.
Note: Once the user name is specified, an SSL connection to the SMTP server is required.
password The password that is assigned to authenticate SMTP server usage.
subject The subject of the email. You can specify one subject per locale.
Note: Note: If a custom subject is not used by the system, there might be a default configured for the email sending command.
Use the following statement to search for the entry and delete it:
SELECT * FROM PROFNVSTRG WHERE PROFILE_ID = (SELECT PROFILE_ID FROM PROFNVSTRG WHERE PROFILEATTNAME LIKE 'subject_-%' AND PROFILEATTVALUE = '<your language specific subject>' ) AND PROFILEATTNAME = 'subject_key' AND PROFILEATTVALUE LIKE '_TXT_%'
recipient The email address of the recipients.
sender The email address of the sender.
host Specify the fully qualified host name or IP address of the SMTP server that is used to send the message.
protocol The protocol that is used to connect to the mail host.
port The SMTP port that is used to send the message. (In most systems this is 25)
retryDuration Specify the period in hours in which you want to retry the connection to the server without decrementing the retry count.
sendPartial The behavior if there are invalid email addresses for multiple recipients. This value will be true if email is still sent if some email addresses are not valid. The value will be false if email is not sent if there are invalid addresses.
Note: This property depends on the SMTP server. It is solely the responsibility of the SMTP server to honor this flag.
contentType The content type, for example text/plain or text/html. The default value is text/plain.
BCC The email address or addresses you want to send a blind carbon copy to.
CC The email address or addresses you want to send a carbon copy to.
replyTo The reply-to address for the email.
File adapter location The location of the file to be written.
FileName The name of the file to be written.
mode The type of write to perform.
  • 0 - append, or create if the file does not exist
  • 1 - overwrite
Adapter for IBM MQ factory Specify the JMS name of the queue connection factory.
inQueue The inbound queue that is used for receiving reply messages when the sendReceiveImmediate sending service is used (by some commands).
errorQueue Specify the JMS name of the error queue in which messages are placed that could not be processed.
outQueue Specify the JMS name of the outbound queue, in which the outbound messages are placed.
timeOut Specify the amount of time in seconds you want the messaging system to wait for a response if send/receive mode (mode = 1) is specified. If no response is received in the specified amount of time, the system returns with a null message. The default value is 60 seconds.
mode The mode of outbound message that is being handled. The default value is 0, which is outbound only. This should be used with the sendImmediate sending service. If 1 is used, the sendReceiveImmediate sending service is used by the invoking command and the command waits for a reply message until "timeOut" is reached. Otherwise, the timeOut value will not be used.
JMSExpiration The time in seconds starting from the dispatch time of a message, which the target JMS service provider should keep before removing it from a queue. Default value of 0 implies that the message does not expire and is kept until it is removed by a JMS application.
JMSPriority The priority of the message. The value ranges 0 - 9, where 9 is the most urgent. The default value is 4.
JMSDeliveryMode Specifies the delivery mode of the message. The message is delivered in persistent mode when the value is set to 2 and is delivered in non-persistent mode when the value is set to 1. The default value is queue-dependent. When the message is sent in persistent mode, the message is persisted to the MQ server and is available upon restart. For more information, refer to your JMS provider documentation.
JMSHeaderPropertyN (where N is an arbitrary unique identifier, for example, 1, 2, 3) Special fields used to store provider-specific header information. If more than one JMSHeaderProperty is needed, a unique digit or other identifier should be appended to the end of the "Admin" attribute of the EditableProperty node (for example from JMSHeaderProperty1 to JMSHeaderPropertyN).
HTTP Connector and Web Service over HTTP Connectors URL The URL to which the message should be transported
contentType The content type of the message
userName The user name to be used for authentication. For HTTP over Web Services, this is the user name for the web service.
password The password to be used for authentication. For HTTP over Web Services, this is the password for the web service.
errorLifeExpectancy As a feature of this particular connector, when an exception occurs when it executes the request based on the connection properties, this connector waits this specified time (in seconds) before it allows the same request to execute again. This prevents the backend system from being flooded with a series of requests when it is unavailable or unresponsive. Certain communication exceptions are caught and assigned this timeout value. When requests based on the same connection information are made, the cached exception is thrown instead of executing the request. When the timeout expires, the request is made as usual. The purpose of this is to provide the caller with an exception while trying to avoid making repeated requests to a backend system that currently is not responding.
connectTimeout The timeout, in seconds, for setting up a connection to the URL. Either do not specify a value, or specify 0 if you want an infinite timeout period.
readTimeout The timeout, in seconds, when reading from input streams when a connection is established to a URL. Either do not specify a value, or specify 0 if you want an infinite timeout period.
Web Service over JMS Connector factory The JMS queue connection factory name.
inQueue The inbound queue that is used for receiving reply messages when the sendReceiveImmediate sending service is used (by some commands).
errorQueue Specify the JMS name of the error queue in which messages are placed that could not be processed.
outQueue The outbound queue where the outbound messages are put.
userName The user name to be used for basic authentication.
password The password to be used for basic authentication.
timeOut The timeout value (in seconds) used to wait for an optional reply message from an external system. The default value is 60.
mode The mode of outbound message being handled. The default value is 0, which is outbound only. This should be used with the sendImmediate sending service. If 1 is used, the sendReceiveImmediate sending service is used by the invoking command and the command waits for a reply message until "timeOut" is reached. Otherwise, the timeOut value will not be used.
JMSExpiration The time in seconds starting from the dispatch time of a message, which the target JMS service provider should keep before removing it from a queue. Default value of 0 implies that the message does not expire and is kept until it is removed by a JMS application.
JMSPriority The priority of the message. The value ranges 0 - 9, where 9 is the most urgent. The default value is 4.
JMSDeliveryMode Specifies the delivery mode of the message. The message is delivered in persistent mode when the value is set to 2 and is delivered in non-persistent mode when the value is set to 1. The default value is queue-dependent. When the message is sent in persistent mode, the message is persisted to the MQ server and is available upon restart. For more information, refer to your JMS provider documentation.
JMSHeaderPropertyN (where N is an arbitrary unique identifier, for example, 1, 2, 3) Special fields that are used to store provider-specific header information. If more than one JMSHeaderProperty is needed, a unique digit or other identifier should be appended to the end of the "Admin" attribute of the EditableProperty node (for example from JMSHeaderProperty1 to JMSHeaderPropertyN).
targetService The port operation to be invoked. For example, "InventoryServices". The target services can be found in the WSDL for the service provider.
Notes:

To set the JMSExpiration, JMSPriority, and other JMS provider-specific header fields of an outbound JMS message, new EditableProperty nodes must be added to the InteractionSpec definition of JCAJMSInteractionSpec:

  • setJMSExpiration
  • setJMSPriority
  • setJMSDeliveryMode
  • setJMSHeaderProperty

This definition is found under the OutboundConnector named JMS.

  1. Backup of your HCL Commerce configuration file. Should you want to reverse this fix, you need to restore the original XML configuration file.
  2. Add the following section to it: 
    
<OutboundConnector default="true"
id="3"
name="JMS"
retries="3">
<JNDI JndiName="eis/JCAJMS"
display="false" />
...

    
<InteractionSpec ClassName="com.ibm.commerce.messaging.adapters.jcajms.JCAJMSInteractionSpec"
default="true">
...

    
<EditableProperty Admin="JMSExpiration"
display="false"
editable="Yes"
name="setJMSExpiration"
value="60" />

    
<EditableProperty Admin="JMSPriority"
display="false"
editable="Yes"
name="setJMSPriority"
value="4" /> <!-- the value ranges from 0 to 9. The default value is 4. -->

    
<EditableProperty Admin="JMSDeliveryMode"
display="false"
editable="Yes"
name="setJMSDeliveryMode"
value="2" /> <!-- the value is 2 for persistent, 1 for non-persistent -->

    
<EditableProperty Admin="JMSHeaderProperty1"
display="false"
editable="Yes"
name="setJMSHeaderProperty"
value="JMS_IBM_MsgType='2'" /> <!-- sample value only -->

    
<EditableProperty Admin="JMSHeaderPropertyN"
display="false"
editable="Yes"
name="setJMSHeaderProperty"
value="JMS_IBM_Format='IBM JMS'" /><!-- sample value only -->

    Any outbound messages that are sent through this connector have, by default, a JMSExpiration value of 60 seconds. This value can be customized under Administration Console when a message type is assigned to the MQ Transport.

    Note: The value that is specified in the Admin attribute must be unique under the InteractionSpec node. Multiple EditableProperty elements are allowed and optional. If more than one JMSHeaderProperty is needed, a unique digit or other identifier should be appended to the end of the "Admin" attribute of the EditableProperty node (for example from JMSHeaderProperty1 to JMSHeaderPropertyN). You need to modify the value attribute with the required name-value pair. The value within the name-value pair should be quoted with a single quotation mark (').
  3. Re-assign the message type to the MQ transport method again. This ensures that the outbound messages that are sent under this message type have the corresponding header properties set.
The following additional transports are available as part of HCL Commerce version 7:
Transport Attribute key Description
SMS-HTTP APIKey The parameter name of the API identifier.
APIValue The unique service API identifier associated with the account.
CharacterLimit The maximum number of characters in a message. The default value is 160.
CustomParameters Additional parameters to be passed to the HTTP API.
Note: These URL parameters must be manually encoded.
Endpoint The URL location of the telecommunication service HTTP API.
MaxRecipients The maximum number of recipients sent to the gateway in a single request. For gateways that do not support bulk messaging, the value should be set to 1.
MessageKey The parameter name of the Message identifier.
MessageValue The default message if not overridden by a custom JSP file.
Password The Password used for authentication to the service. Passwords are stored as encrypted values by using the merchant's key.
PasswordKey The parameter name of the Password identifier.
RecipientDelimiter The delimiter character for multiple recipients in the recipient parameter.
RecipientKey The parameter name of the Recipient identifier.
RecipientValue The destination number of the recipient(s).
SenderKey The parameter name of the Sender identifier.
SenderValue The name or number of the sender.
usePostMethod Indicates whether the HTTP-POST method is used. If false, the HTTP-GET method is used.
UserNameKey The parameter name of the UserName identifier.
UserNameValue The UserName identification for the service.
SMS-WS CharacterLimit The maximum number of characters in a message. The default value is 160.
Endpoint The URI of the Parlay X 3.0 gateway service.
Message The default message if not overridden by a custom JSP file.
Password The Password used for authentication to the service. Passwords are stored as encrypted values using the merchant's key.
Recipient The destination number of the recipient(s).
SenderValue The name or number of the sender.
UserNameValue The registered username of this Web Service.
Notes:

When you integrate SMS transports in HCL Commerce:

  • The provided attribute keys are generic name-value pairs common to most gateway services that support the HTTP API interface. Some of the provided fields can be optional depending on varying available service configurations. The customParameters field provides further customization options, increasing compatibility with various gateway services.
  • The provided attribute keys are URL encoded and valid for transmission through a URL string unless specifically stated. Alternatively, the CustomParameters value is not URL encoded, allowing for greater flexibility when managing custom values. Therefore, the customParameters URL parameters must be manually encoded.
  • The SMS HTTP adapter is configurable to work with several third-party telecommunication gateway services that support the HTTP interface. Requests are initiated by using an HTTP POST request, with the parameter values complying with their individually specified HTTP API.
  • The message content corresponding to the MessageKey parameter, and the recipient address corresponding to the RecipientKey parameter are dynamically generated, depending on the message type and customer identity. These fields are passed to the adapter for message delivery after being generated.
  • The RecipientDelimiter is used for SMS gateways that support bulk messages with the addresses concatenated into a complete address list, which is separated by the specified delimiter. This configuration depends on the gateway's handling and interpretation of the delimiter. For example, some gateways support a semicolon as the delimiter, while others support a comma or pipe characters as the delimiter. Therefore, this character is not URL encoded.

The SMS HTTP adapter is configurable to work with other third-party telecommunication gateway services supporting the HTTP interface. An example of a third-party gateway that supports an HTTP API is the Clickatell gateway.

The request is initiated using an HTTP POST request, with the correct parameter values in compliance with their individually specified HTTP API. The following is an example of a request made to the Clickatell gateway:

http://api.clickatell.com/http/sendmsg?api_id=someAPI&user=someUser&password=somePassword&to=5552221234,5552225678,5552220987&from=someSender&text=This+is+some+message+from+the+SMS+HTTP+adapter&queue=1&concat=2
The parameters should be assigned the following values to send the HTTP POST request by using the Clickatell gateway:
Parameter values used to send the HTTP POST request by using the Clickatell gateway
Parameter Value
APIKey api_id
APIValue someAPI
CharacterLimit 160
CustomParameters &queue=1&concat=2
Endpoint http://api.clickatell.com/http/sendmsg
MaxRecipients 100
MessageKey text
Password somePassword
PasswordKey password
RecipientDelimiter ,
RecipientKey to
SenderKey from
SenderValue someSender
UserNameKey user
UserNameValue someUser
usePostMethod true