This section explains how the central processing unit of the Expeditor integrator, the Expeditor integrator Application Control Service (ACS), can be configured to run custom business processes (use cases).

Introduction to the Expeditor integrator Application Control Service

Expeditor integrator Application Control Service (ACS)

The Expeditor integrator Application Control Service covers the functional requirements for the Expeditor integrator which had been initially collected from retail customers and were extended with requirements from other industries (e.g. utilities, health care).
For example, Expeditor integrator provides the file transmission capabilities that are required by retail customers:

• Transmitting files reliably from the store server/4690 POS Controller to the BSB back-end
• Transmitting files from the BSB back-end to the store server and/or the 4690 POS Controllers
• Further available functions are:
• Transferring data to and retrieving data from JDBC database resources (in form of XML-structured DB records for both directions and SQL commands for inbound requests only)
• Forwarding of incoming messages to other local queues (topics) which may be bridged to other external resources. And also, forwarding of messages from local resources to externally bridged message queues. Pub/Sub technology is also supported by the used Expeditor micro broker.
• Accepting HTTP data transmission requests using the Expeditor integrator REST Adapter request schema (which converts these requests to incoming Expeditor integrator messages).

These functions must be put in a reliable transactional context.
The ACS…

• …retrieves its configuration information from the OSGi Config Admin Service (which is fed by the Custom Config Service if the local XPDinteg.xml file is used for configuration purposes)
• …logs status and execution information using the OSGi Log Service and the Event Admin Service. The Custom Log, the Custom Event and the Tivoli Monitoring Service can then filter for interesting events and process them appropriately (as CBE events). The Persistence Service can further persist the filtered events for longer storage.
• …provides triggered data retrieval from connected resources (e.g. retrieves FTP file from the 4690 controllers).
• …ensures triggered data distribution to any connected resource (e.g. XML file is written to XML-capable relational database).

The finally developed Expeditor integrator Application Control Service (ACS) is the (more general) central processing component for all incoming and outgoing messages in the Expeditor integrator. It interprets the messages and triggers further actions to orchestrate use-cases within a transactional unit of work. The successful execution of all Activities within the use-case Flow leads to the committing of a containing unit of work within the Expeditor integrator’s Transaction Service or a rollback otherwise. This flow is described using a flow language and stored on the disk.

The Application Control Service has been designed to be both flexible and simple to operate and with possibilities for future extension. To achieve this, the ACS uses a simple flow language provided in XML files which indicate a series of Activities to be executed in a sequence. This allows the flows to be configured without necessarily having to write code.

The ACS also provides a simple registry pattern for the code implementing each Activity to be made available to flows. The benefits of this approach are two-fold. Firstly, this pattern follows the OSGi/Eclipse model of deploying modular code in loosely coupled bundles and having each implementing bundle register itself when loaded. This means that in the future, new code functionality can be added to the Expeditor integrator without needing a full restart of the platform as per the OSGi ethos. Secondly, the activity can be registered and hence later referenced by a use-case flow with an easily consumable name rather the need to store a complex fully-qualified Java class name. For this release, dynamic addition of XML files is not part of the design, though it could be added later.

Custom use cases can be configured in new flows that contain new combinations of existing Activities. The Application Control Service triggers and maintains the Expeditor integrator flows (flow manager). Any OSGi Event Admin event is used to trigger the ACS flows. This provides a large flexibility for the creation of use cases with the existing components. It only must be ensured that the data type of the input object which is expected by one Activity matches the type of the output object of the predecessor Activity in the flow.

Figure 21 provides an overview of how ACS flows and Activities interact with each other. A message, a file or any other supported resource can fire an OSGi Event Admin event through the Resource Monitor. Besides the Resource Monitor, the Queue Dispatcher Service can be used to route specific types of locally received messages and to publish flow trigger events (topics) with references to the received message.
Corresponding ACS flows are configured to listen to these flow trigger events (subscription to Event Admin Service topic). The flows take the received resource reference and process the configured Activities sequentially in transactional context.


Figure 21: Application Control Service (ACS), Flows and Activities in Lotus Expeditor integrator

ACS Flow Definition Language

The Application Control Service consumes a very simple flow language defined in an XML vocabulary. The XML defines a sequence of activities to be executed and each is read in-order within the XML document.

This vocabulary is defined as follows (see Listing 28).

Listing 28: Flow definition file syntax



Italics indicate user-defined data. The rules for the XML file are as follows:

• A flow definition is contained within a process element. It must have a name defined in its name attribute.
• The process element must contain a trigger attribute indicating the OSGi Event Admin trigger topic for the flow.
• The subsequent child elements consist of zero or more XPDintegActivity elements defining each Activity in the flow populated as follows:
• Each XPDintegActivity element must have a unique name defined in its name attribute.
• Each XPDintegActivity element must have an implementing activity name defined in its activityName attribute. This is the value that is used to retrieve the correct factory from the registry creating the Data Transmission Control Activity instance at runtime.
• XPDintegActivity elements may also specify additional XML attributes to be passed to the activity implementation at runtime as context properties.

ACS Activities

The Application Control Service will provide a set of basic Activity implementations to support the required functionality of the Expeditor integrator within a separate Application Control Service (ACS) Activity bundle separate to the ACS bundle. Each Activity will be initialized with a collection of context properties that are passed in from the Expeditor integrator configuration settings for the ACS Component and any additional attributes on the activity elements in the flow definition as described above. This allows local properties to be stored in the configuration independently of the overall flow definition.

In each case, the specific behavior will of course be driven by the data object flowing through the Activity (within the ACS, the first input object to a flow will be an Event Admin object).

The following table describes each Activity and its configuration (see Table 27). Note that all configuration properties can be provided either in the flow definition or the ACS configuration within the ACS configuration section of the XPDinteg.xml. The ACS configuration properties are passed to (but can be overridden by) the flow context properties. The separation is made here on the more platform specific settings being in the configuration so the flows can be reused across Expeditor integrator runtime locations.
Generally, the overall valid priority schema applies:

1. Highest priority have the all properties in triggering messages (e.g. if DestinationName is provided as JMS custom header property, it will overwrite the DestinationName configured as Activity context parameter in the flow.). The JMS Custom Message Header properties may also be provided by the Resource Mapper (assigned through a given ResourceType).
2. If JMS custom header property is not provided or not applicable (e.g. in the case of the Resource Adapter/Monitor triggering the flow), the configuration of the Activity context parameters will be taken.
3. Lowest priority has the local Expeditor integrator configuration in the Configuration Admin store of each component (or in the XPDinteg.xml configuration file). This configuration is taken if neither the JMS custom header property nor the Activity context parameter is provided.

The in brackets provided Reference Name (see Name column) is the name which is used in the flow definition language to call the specific Activity.

Table 27: Overview of existing Application Control Service Activities

Name (Reference Name)	Parameters	Input	Output	Description
General resource related Activties
ReadDataFromResourceReferenceActivity	Context parameters: PropertyKey	Event Admin event with a ResourceDataReference set as a property with the name specified in the context parameters.	ResourceData	Takes an Event Admin event with a ResourceDataReference attached and simply reads out the underlying ResourceData object for processing further down the process flow.
File resource related Activities
MessageToFileActivity (XPDINTEG_MESSAGE_TO_FILE)	Context parameters: JndiConnectionFactoryKey [Encoding] – local character set encoding for ASCII data. [InvalidMessageFailureAction] [RollbackMessageAction] [DeadLetterJNDIKey] Note: JMS Custom Message Header properties can also be provided by INBOUND Resource Mapper configuration which is assigned by the ResourceType. These Custom Header properties have highest priority and can NOT be overwritten by the Activity’s context parameters.	expects either an OSGi event (1) or a message (2). 1) Event: Queue Dispatcher sends an event when a file is received. 2) Message: Activity receives a ConfigUpdate or an ExecuteScript message that contains the XPDinteg.xml or Script file as payload.	ResourceData (file)	1) If the input is an event, the JNDI name of the queue and the file ID will be retrieved from the event properties. Based on these values, the message is retrieved and the target file is created. 2) The target file (XPDinteg.xml or script file) is extracted from the received message. Whenever the flow fails either of invalid JMS header properties/values or other issues, this activity will take appropriate action on the received messages. In case of invaild JMS heeader values, actions will be taken based on the InvalidMessageFailure. The default value is DISCARD. For all other issues the actions based on the RollbackMessageAction value are performed. The default is PUT_BACK. The other possible value for the action is REMOVE. In the latter case, it will use the RemoveTargetJNDI key to send the message to a nother queue (e.g. the Deadletter queue). The possible actions are: DISCARD: ignores the message by committing all the messages PUT_BACK: rolls the messages back (in inQ) REMOVE: sends the message to another queue (e.g. Deadletter queue)
FileWriteActivity FileWriteToLocalFileSystemActivity (XPDINTEG_FILE_WRITE_TO_FILE_SYSTEM) FileWriteToFtpActivity (XPDINTEG_FILE_WRITE_TO_FTP) FileWriteToSshActivity (XPDINTEG_FILE_WRITE_TO_SSH)	ResourceData headers: JMS_MESSAGES – Vector of the source JMS messages that created the file JMS_SESSION – the source JMS Session that read the messages. Context parameters: RetryAttempts RetryInterval Context parameters if FTP: FtpServer FtpUser FtpPassword [FtpServerPort] [FtpPassive] Context parameters if SSH: SshServer SshUser SshPassword [SshServerPort] [SshType]	ResourceData (file)	ResourceData (file)	Writes a file provided as a ResourceData instance. It creates the target file out of the received messages with the given destination. A number of RetryAttempts can be specified. The RetryInterval specifies the sleep interval between the retry attempts. JMS Custom Message Header properties can also be provided by INBOUND Resource Mapper configuration which is assigned by the ResourceType. These Custom Header properties have highest priority and can NOT be overwritten by the Activity’s context parameters.
FileTransferConfirmationActivity (XPDINTEG_FILE_TRANSFER_CONFIRMATION)	Context parameters: · AdapterName (XPDINTEG_FTP_ADAPTER, XPDINTEG_FILE_SYSTEM_ADAPTER, XPDINTEG_SSH_ADAPTER)	ResourceData (file)	-NIL-	Retrieves the file properties either from the message or configuration store and performs the confirmation activity, i.e. Delete file, recreate file with 0 contents. JMS Custom Message Header properties can also be provided by OUTBOUND Resource Mapper.
FileToMessageWriteActivity (XPDINTEG_FILE_TO_MESSAGE_WRITE)	Context parameters: JndiConnectionFactoryKey JndiDestinationKey MessageSegmentSize CreateHeaderVersion	ResourceData (file)	The original object,	Takes a ResourceData object (a file) and writes 1-n messages according to the configured maximum message size (MessageSegmentSize). CreateHeaderVersion is used to configure this activity with the version of the headers which are sent to back-end. This will use the com.ibm.rcp.integrator.common bundle attributes to determin which of the MessageHeader properties need to be changed before sending the message. JMS Custom Message Header properties can also be provided by OUTBOUND Resource Mapper.
FileReadFtpActivity (XPDINTEG_FILE_READ_FTP)	Context parameters: PropertyKey (or) AdapterName (XPDINTEG_FTP_ADAPTER) FtpServer FtpUser FtpPassword [FtpServerPort] [FtpPassive]	Event Admin event with a ResourceDataReference set as a property with the name specified in the context parameters. Or ResourceData(Message).	ResourceData	1) If the input is Event, it will work as ReadDataFromResourceReferanceActivty. This case happens when the FTP Adapter monitors for a given file and sends the file referene as input to this activity 2) The second case occurs when a file is requested by a message. Then, the message is read from the queue and the requested file is retrieved by this activity JMS Custom Message Header properties can also be provided by OUTBOUND Resource Mapper.
FileReadSshActivity (XPDINTEG_FILE_READ_SSH)	Context parameters: PropertyKey (or) AdapterName (XPDINTEG_SSH_ADAPTER) SshServer SshUser SshPassword [SshServerPort] [SshType]	Event Admin event with a ResourceDataReference set as a property with the name specified in the context parameters. Or ResourceData(Message).	ResourceData	1) If the input is Event, it will works as ReadDataFromResourceReferanceActivty. This case happens when the SSH Adapter monitors for a given file and sends the file referene as input to this activity 2) The second case occurs when a file is requested by a message. Then, the message is read from the queue and the requested file is retrieved by this activity. JMS Custom Message Header properties can also be provided by OUTBOUND Resource Mapper.
FileReadLocalFileSystemActivity (XPDINTEG_FILE_READ_FILE_SYSTEM)	Context parameters: PropertyKey (or) AdapterName ( XPDINTEG_FILE_SYSTEM_ADAPTER)	Event Admin event with a ResourceDataReference set as a property with the name specified in the context parameters. Or ResourceData(Message).	ResourceData	1) If the input is Event, I will work as ReadDataFromResourceReferanceActivty. This case happens when LocalFileSystem Adapter monitors for files and sends the file referene as input to this activity. 2) The second case occurs when a file is requested. Then, the message is read from the queue and the requested file is retrieved by this activity JMS Custom Message Header properties can also be provided by OUTBOUND Resource Mapper.
MessageReadActivity (XPDINTEG_MESSAGE_READ)	Context parameters: PropertyKey (or) MetaData, JndiConnectionFactory, JndiDestinationKey [InvalidMessageFailureAction] [RollbackMessageAction] [RemoveTargetJNDI] Note: JMS Custom Message Header properties can also be provided by INBOUND Resource Mapper configuration which is assigned by the ResourceType. These Custom Header properties have highest priority and can NOT be overwritten by the Activity’s context parameters.	Event Admin event with a ResourceDataReference set as a property with the name specified in the context parameters or the second set of parameters	ResourceData	1) In the first case it reads the message from the message refrence. 2) In the second case, the event contains the keys for the local queus, connections and metadata information. These are used to read the message. This case occurs when a FileRequest message is received and the Queue Dispatcher sends an event to this activity directly. Whenever the flow fails due to either Invalid custom headers other issues this activity will take appropriate action on the received messages. In case of an invaild header property, it will take the action based on the InvalidMessageFailureAction. The default value is DISCARD. For other flow execution errors, the action is based on the RollbackMessageAction value. The default is PUT_BACK. The other possible value for the action is REMOVE. In the latter case it will use the RemoveTargetJNDI key to send the message to a nother queue (e.g. the Deadletter queue). The possible actions are: DISCARD: ignores the message by committing all the messages PUT_BACK: rolls the messages back (in inQ) REMOVE: sends the message to another queue (e.g. Deadletter queue)
Message resource related Activities
MessageWriteActivity (XPDINTEG_MESSAGE_WRITE)	Context parameters: JndiConnectionFactoryKey JndiOutputDestinationKey CreateHeaderVersion [DestinationName] AddDefaultHeaders=”{TRUE | FALSE}” [CopyJmsHeaders=”{TRUE | FALSE}”] [Header=<Operation>::<NewHeaderName>::<Value>::<Type>] with <Operation>={ADD, OVERWRITE, DELETE} <Type>={STRING, INTEGER, LONG} E.g.: Header1="ADD::TestHeader::123::INTEGER" Header3="ADD::TestHeader2::&lt;DestinationName&gt;" Header4="DELETE::DestinationName" (also see ChangeCustomHeaderActivity) Note: For this Activity, the JMS Custom Message Header properties can also be provided by INBOUND and OUTBOUND Resource Mapper configuration. The INBOUND Resource Mapper configuration is processed first and has priority over the OUTBOUND Resource Mapper. The JMS standard headers JMSCorrelationID, JMSType and JMSReplyTo are always maintained if the input object is a message and if the headers exist in the incoming message. JMSDeliveryMode, JMSDestination, JMSMessageID, JMSRedelivered, JMSTimestamp can not be re-used from the incoming message since these are set by the JMS provider when the new target message is created/sent. The Expeditor integrator JMS Custom Header TTL must be provided as relative value in msec. It is converted into an absolute time in msec from 1970 based on the current system time and overwrites any existing TTL value (Expiry=ON is set automatically). Make sure that the changed Expeditor integrator Custom Headers use the correct value type (see chapter 2.3 JMS Custom Header Properties)	Java object, either a byte[], String or Serializable. or MessageResourceData	The original object,	Takes a given Java object, maps it to an appropriate JMS message type (Bytes, Text or Object respectively) and puts it to the destination specified. If the input object is MessageResourceData, it will forward the message to the correct DestinationName depending on the value of it in (1) the message header or (2) in the receiving JMS_Adapter parameters, or (3) in the Inbound Resource Mapper or (4) in the Acivity context parameter JndiOutputDestinationKey. If (1), (2) or (3) do not exist, the JndiOutputDestionationKey must be (!) provided, otherwise this activity will fail. The provided value is stored in the created custom message header DestinationName. With the operation HeaderX::DELETE::DestinationName, the custom header can be removed from the target message again, but the target queue will still be the one which was provided in DestinationName. CreateHeaderVersion is used to configure this activity with the version of the headers which are sent to back-end. This will use the com.ibm.rcp.integrator.common bundle attributes to determin which of the Message Header properties need to be changed before sending the message. AddDefaultHeaders creates the Expeditor integrator default JMS custom header properties (see chapter 2.4.3 JMS Custom Header Creation for Messages from Expeditor integrator to Back-end (outbound)) If CopyJmsHeaders = TRUE, the JMS standard headers JMSExpiration and JMSPriority of the incoming message are maintained. Headerx is only added when it does not exist yet. Headerx context parameter can edit Expeditor integrator JMS Custom Header properties for the created message. ADD operations are executed first. Headerx is only added when it does not exist yet. The added headers are NOT considered for actions in this Activity (e.g. destination for putting the message). These headers will simply be added, changed or removed in the finally written target message (e.g HeaderX::ADD::DestinationName… will not be considered as valid queue destination for this message)
ChangeCustomHeaderActivity (XPDINTEG_CHANGE_CUSTOM_HEADER)	ContextParameters: ActivityLogLevel = "ERROR | WARNING | INFO" HeaderX="HeaderOperation::HeaderName::HeaderValue::HeaderValueType" where - X is the header counter, e.g. X=1,2,3 etc. - HeaderOperation provides possible operations: HeaderOperation="OVERWRITE | ADD | DELETE" - HeaderName is the custom header’s name: HeaderName="<defined_xpdinteg_headers> | <custom_header>" (spaces in name are not allowed) - HeaderValue is the changed or added value of the custom header - HeaderValueType defines the type of the custom header: HeaderValueType="STRING | INTEGER | LONG"	MessageResourceData object	original object (custom headers changed according to Context Parameters)	This activity takes MessageResourceData object and allows adding, changing and removing Custom Message Headers (key-value-pairs). Existing header properties will not be added in case of HeaderOperation=ADD if they already exist, but they will be always added or overwritten in case of the HeaderOperation=OVERWRITE Examples: Header1="OVERWRITE::DestinationName::jms/XPDinteg_LocalDeadletterQ" Header2="ADD::TestHeader:Test header value::STRING" Header3=”DELETE::DestinationPath” Note: The Expeditor integrator JMS Custom Header TTL must be provided as relative value in msec. It is converted into an absolute time in msec from 1970 based on the current system time and overwrites any existing TTL value (Expiry=ON is set automatically). Make sure that the changed Expeditor integrator Custom Headers (message properties) use the correct value type (see chapter 2.3 JMS Custom Header Properties).
JDBC Resource related Activities
MessageToDatabaseSQLActivity (XPDINTEG_MESSAGE_TO_DB_SQL)	ContextParameters: [DBURI] [DRIVER_CLASS] [USER] [PASSWORD] [DATA_SOURCE_KEY] JMS Custom Message Header properties can also be provided by INBOUND Resource Mapper.	Message	DatabaseResourceData	Reads the input message and converts to the payload to a DatabaseResourceData object for performing update operation on a database. The JMS Custom Header parameter ResourceCmd value {SQL} defines the way of the creation of the SQL command to be executed. SQL – the message payload contains complete valid SQL statements which are transparently passed on to the database. The provided SQL statements must be valid SQL scripts (SQL commands separated by ‘;’). The SQL CONNECT and DISCONNECT must not be included since these are created during the Java DB connection. Single SQL commands are passed on as prepared statements.
MessageToDatabaseXPDinegDBXMLActivity (XPDINTEG_MESSAGE_TO_DB_XPDINTEG_XML)	ContextParameters: [DBURI] [DRIVER_CLASS] [USER] [PASSWORD] [DATA_SOURCE_KEY] Note: JMS Custom Message Header properties can also be provided by INBOUND Resource Mapper.	Message	DatabaseResourceData	Reads the input message and converts to DatabaseResourceData object for performing update operation on the database. The JMS Custom Header parameter ResourceCmd value {XPDINTEG_DBXML} defines the way of the creation of the SQL command to be executed. XPDINTEG_DBXML – the message payload contains an Expeditor integrator specific XML structure @nowiki@6which contains sections for SQL commands and data.
MessageToDatabaseXMLActivity (XPDINTEG_MESSAGE_TO_DB_XML)	ContextParameters: [DBURI] [DRIVER_CLASS] [USER] [PASSWORD] [DATA_SOURCE_KEY] SQL Column_i Note: JMS Custom Message Header properties can also be provided by INBOUND Resource Mapper configuration which is assigned by the ResourceType. These Custom Header properties have highest priority and can NOT be overwritten by the Activity’s context parameters.	Message	DatabaseResourceData	Reads the input message and converts to DatabaseResourceData object for performing update operation on a database. The JMS Custom Header parameter ResourceCmd value {XML} defines the way of the creation of the SQL command which needs to be executed. {XML} – the message payload contains an XML structure. This activity contains the SQL context parameter which represents the SQL statements to be executed. The SQL statements are prepared SQL statements which contain the placeholders which values are replaced depending on the input XML and the values of Column_i context parameters. The Column_i context parameter contains the XPath expression or “data”. If it is an XPath expression, this expression will be evaluated based on the XML and the used value for the corresponding column value. The value DATA means the complete XML data is used to fill the corresponding column value.
DatabaseUpdateActivity (XPDINTEG_DB_WRITE)		DatabaseResourceData	NIL	Reads the DatabaseResourceData and updates the database accordingly
DBReadResourceDataActivity (XPDINTEG_DB_READ)	Note: JMS Custom Message Header properties can also be provided by OUTBOUND Resource Mapper.	Message (or) DatabaseResourceDataReference	DatabaseResourceData	Reads the database depending on the input. If the input is an event from the Monitoring Service, it will read the database content. If the input is message then it retrieves the message headers and performs the database read activity. The output of this activity is DatabaseResourceData.
DatabaseSerializationActivcity (XPDINTEG_DB_SERIALIZATION)	Context parameters [Format] [Row] [Column]	DataBaseResourceData	String	The Context parameter Format has three possible values {SIMPLE_XML | XPDINTEG_DBXML | ROW_COLUMN}. The default value is SIMPLE_XML (see chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations). In this case, this activity will seralize the DBReadData (ResultSet) into a simple XML structure (see Listing 5). In the XPDINTEG_DBXML case, the ResultSet is converted into XPDINTEG_DBXML (XML) Format (see Listing 4). If the value is ROW_COLUMN, it will take the then mandatory context parameters Row and Column to identify the return value. E.g. if Row=1 and Column=2, the returned object is the value of the object under Column1/Row2 of the result set.
Helper and Support Activities
CreateEventAdminEventActivity (XPDINTEG_CREATE_EVENT_ADMIN_EVENT)	Context parameters: EventTopic		The original object,	Retrieves the topic name and publishes an event to the OSGi Event Admin Service with the topic EventTopic.
PublishCBEActivity (XPDINTEG_PUBLISH_CBE_ACTIVITY)	Context parameters: CBEStatus CBEInLineProperties (TRUE|FALSE) Additional CBE configuration that overrides the default config	Anything	The original objects	Can be over-ride the default CBE configuration in the Expeditor integrator configuration (XPDinteg.xml)
ObjectToStrngActivity (XPDINTEG_OBJECT_TO_STRING_ACTIVITY)	Context Parameters: [DumpToConsole={TRUE | FALSE}] [DumpToFile] [OutputObject]	Object	Object or String	This activity dumps the input object to the console and to a file depending on the context parameters. If the DumpToConsole value is TRUE, it will dump the input object to console. If the value is FALSE, it will not dump. The default value is “TRUE”. For the file the DumpToFile parameter gives the file location to dump the input object. If this parameter is missing it will not dump to a file. The param “OutputObject” has the following values InputObject then the output of the activity is the same as the input String then the output of this activity is String
SearchAndReplaceStringActivity (XPDINTEG_SEARCH_AND_REPLACE_STRING)	Context Parameters: For MessageResourceData: [SearchString] [SearchStringType] [ReplacementString]	FileResourceData | String	Respective inputDataObject with the “SearchString” replaced by the “ReplacementString”	This activity replaces the “SearchString in a FileResourceData or String with the “ReplacementString”. The context parameter “SearchString” can be a specified as a regular expression or a XPATH expression (XPATH in cases where the FileResourceData has XML content). This is indicated by the SearchStringType – VALUE or XPATH. The “ReplacementString” can be: <NONE> - replaces with empty string “”. @nowiki@8replaces with a JMSHeader if exists in the applicationControlSession Any string value. For a FileResourceData - since, this is a string related activity; this is valid only in case of TransferMode “ASCII” or “BINARY” with UTF-8 encoding. Other cases may give un-expected results.
FileCopyUsingReference (XPDINTEG_FILE_COPY_USING_REFERENCE)	Context parameters: AdapterName (STORE_XPD_FILE_SYSTEM_ADAPTER) SourceLocation CopyLocation CopyMode= OVERWRITE | APPEND	Anything	The original object,	Copies the file specified by SourceLocation to the CopyLocation. The CopyLocation supports dynamic files names - <TIMESTAMP> can be used within the CopyLocation
FileCopyActivity (XPDINTEG_FILE_COPY)	Context parameters: AdapterName (STORE_XPD_FILE_SYSTEM_ADAPTER) CopyLocation CopyMode= OVERWRITE | APPEND	FileResourceData	The original object	Copies the received FileResourceData object to the file location provided under CopyLocation (directory path and file name).
CheckJMSHeaderPropertyActivity (XPDINTEG_CHECK_JMSHEADER_PROPERTY)	Context Parameters: For MessageResourceData: [JMSHeaderPropertyName] [JMSHeaderPropertyValue] [ValueType] [XMLFilePath] For String: [PropertyValue] [ValueType] [XMLFilePath] Note: ValueType can be either “VALUE” or “ConfigProperty”	MessageResourceData | String	inputDataObject	1. Input is MessageResourceData: This activity validates the JMS headers against the context parameters – JMSHeaderPropertyName and JMSHeaderPropertyValue. 2. Input is String: This activity validates the inputDataObject (String) against the value specified with the context parameter – PropertyValue. In both cases, if the ValueType is ConfigProperty, the XMLFilePath parameter is used to specify the location of the XML file path (Eg: config/XPDinteg.xml) and the JMSHeaderPropertyValue/PropertyValue has an XPath expression.
System and Application Control Activities
BrowseQueueActivity (XPDINTEG_BROWSE_QUEUE)	Context parameters: JndiConnectionFactoryKey ResourceData headers: DestinationName	ResourceData (message)	XML String with browse listing	Browses a queue. The name of the queue to browse is provided in the ResourceData header “DestinationName”.
DrainQueueActivity (XPDINTEG_DRAIN_QUEUE)	Context parameters: JndiConnectionFactoryKey ResourceData headers: DestinationName	ResourceData (message)	The original object,	Drains a local queue on the Expeditor integrator. The name of the queue to drain is provided in the ResourceData header “DestinationName”.
BrowseLocalFileSystem DirectoryActivity (XPDINTEG_BROWSE_FILE_SYSTEM_DIRECTORY)	ResourceData headers: DestinationPath	ResourceData (message)	XML String with browse listing	Retrieves a directory listing of the local file system. The name of the directory is provided in the ResourceData header “DestinationPath”.
BrowseFtpDirectoryActivity (XPDINTEG_BROWSE_FTP_DIRECTORY)	Context parameters: FtpServer FtpUser FtpPassword [FtpServerPort] [FtpPassive] ResourceData headers: DestinationPath	ResourceData (message)	XML String with browse listing	Retrieves a directory listing of an FTP file system. The name of the directory is provided in the ResourceData header “DestinationPath”.
BrowseSshDirectoryActivity (XPDINTEG_BROWSE_SSH_DIRECTORY)	Context parameters: SshServer SshUser SshPassword [SshServerPort] [SshType] ResourceData headers: DestinationPath	ResourceData (message)	XML String with browse listing	Retrieves a directory listing of an SSH file system. The name of the directory is provided in the ResourceData header “DestinationPath”.
FileExecuteActivity (XPDINTEG_FILE_EXECUTE)	Context parameters: AdapterName (XPDINTEG_FILE_SYSTEM_ADAPTER) EnableScriptExecution Note: EnableScriptExecution has to be ‘TRUE’ for successful execution.	ResourceData (file)	The original object,	Takes a Resource Data object (file) and executes it on the file system. If no file is provided in the payload, but the file given in DestinationPath/-Name exists, it will be executed. Also, if a file already exists at DestinationPath/-Name, the file in the payload will be overwritten or appended (depending on the DestinationCreationMode) and then executed.
ConfigRetrievalActivity (XPDINTEG_CONFIG_RETRIEVAL_ACTIVITY)	Context parameters: VersionFile (is the location of the XPD integrator version.dat file)	ResourceData (message)	XML String with listing	Retrieves the used values in the Config Admin stores of all Expeditor integrator Appl bundles the list of registered Expeditor integrator ACS flows version.dat file content a list of running plug-ins (incl. their version no) and sends this information back to the back-end using the bridged ResOutQ.
RetrieveAndUpdateConfigurationActivity (XPDINTEG_CONFIGURATION_STORE_RETRIEVE_UPDATE)	-NIL-	ResourceData (message)	ResourceData (File)	If MessagePurpose is Maintenance then ResourceCmd values are {ON, OFF}. Depending on the ResourceCmd value this Activity retrieves the current configuration store properties of all bundles updates their Maintenance Mode property to the ResourceCmd value and creates a file based on the new values. If the MessagePurpose is ConfigUpdate and ResourceCmd contains the bundle specific values, it will retrieve the current Config Admin configuration store of all bundles, will apply the new updates and will store them into a in-memory file.
XMLValidateAndTransformActivity (XPDINTEG_VALIDATE_TRANSFORM_ACTIVITY)	Context parameters: XSDLocation: XSLTLocation OutputXMLLocation InputXMLLocation (Optional)	FileResourceData	FileResourceData	This activity takes the input file resource data (XML Data) and validates and transforms the input xml data using the XSDLocation and XSLTLocation and generates the XML File with the location as the OutPutXMLLocation. If the InputXMLLocation is available then this activity gives the preferences to this XML file rather than the input XML data to this activity.
ConfigStoreUpdateActivity (XPDINTEG_CONFIGSTORE_UPDATE_ACTIVITY)	ContextParameters: InputXMLLocation (Optional)	FileResourceData	NIL	This activity takes the input XML file and updates the Config Admin configuration store transactionally. If the context parameter InputXMLLocation is available then it will give the prefenrece to this file rather than the input FileResourceData for updating the configuration store.
UserAdminStoreUpdateActivity (XPDINTEG_USERADMINSTORE_UPDATE_ACTIVITY)	ContextParameters: InputXMLLocation (Optional)	FileResourceData	same as Input	This activity takes the input XML file and updates the User Admin configuration store transactionally. If the context parameter InputXMLLocation is available then it will give the prefenrece to this file rather than the input FileResourceData for updating the configuration store.
RetrieveAndUpdateUserAdminStore (XPDINTEG_USERADMINSTORE_RETRIEVE_UPDATE)	NIL	ResourceData (message)	ResourceData (File)	If the MessagePurpose is ConfigUpdate and ResourceCmd is UserConfigParamList, it will retrieve the current User Admin store will apply the new updates and will store them into a in-memory file.
HouseKeepingLocalFileSystem (HOUSE_KEEPING_LOCAL_FILE_SYSTEM_ACTIVITY)	Context parameters: AdapterName (STORE_XPD_FILE_SYSTEM_ADAPTER)	Event/FileResourceData	FileResourceData (file-content for the /persistent/housekeeping_<date>.log	performs House-keeping on LocalFilesSystem
HouseKeepingJMS (HOUSE_KEEPING_JMS_ACTIVITY)	Context parameters: JndiConnectionFactoryKey	Event/FileResourceData	FileResourceData (file-content for the /persistent/housekeeping_<date>.log	performs House-keeping on local queues
HouseKeepingSystemResources (HOUSE_KEEPING_SYSTEM_RESOURCES_ACTIVITY)	NIL	Event/FileResourceData	FileResourceData (file-content for the /persistent/housekeeping_<date>.log	performs House-keeping on System-Resources
BundleControlActivity (XPDINTEG_BUNDLE_CONTROL_ACTIVITY)	Context parameters: BundleName Command= START | STOP			Activity starts and or stops the given bundle.
ISACollectorActivity (ISA_COLLECTOR_ACTIVITY)	NIL	Message	String	Runs the ISACollector and generates the ZIP file and the output is the location of generated file
ISACollectorExtensionActivity (XPDINTEG_ISA_COLLECTOR_ADDFILES_ACTIVITY)	Context Parameters: [FileList<i>] [IncludeOutput:{true|false}] [OutputFileThreashold] [TransferType] [Encoding] [TransferPriority]	String	FIleResourceData or NULL	This activity adds more files to the generated ZIP file from the previous activity. The new files are specified like FileList1, FileList2 … After generating the ZIP file the output of this activity can be of type FileResourceData if the IncludeOutput is true and the ZIP file size is within the OutputFileThreashold limit. If the OutputThreashhold is 0 or less than that means do verify the size. The other parameters specify how this file can be transferred.
PlatformRestartActivity (XPDINTEG_PLATFORM_RESTART)	Context Parameters: [LocalScriptFile] [Command:{restart | stop }] [Param:{console,reset}] [ EnableScriptExecution]	JMSDestinationData | FileResourceData	FileResourceData	This activity restarts the Expeditor integrator when installed as a service. The implementation is based on execution of a script. The LocalScriptFile points to the location of this script – usally, “services/XPDintegRestart.bat” on Windows. The context parameters can be over-ridden by the JMSHeader ‘ResourceCmd’. Format: Command:{restart|stop};Param:{console,reset}. If no value is specified for the ResourceCmd as well as the context parameters, this activity does nothing. This behaviour (of doing nothing) is useful for the ConfigUpdate as well as the Maintenance Mode flows – where a ‘restart’ is not always required. Note: EnableScriptExecution must be ‘TRUE’ for successful execution.
ExecuteLocalScriptActivity (XPDINTEG_EXECUTE_LOCAL_SCRIPT)	Context Parameters: [LocalScriptFile] [ EnableScriptExecution]	Any object as long as the ResourceCmd is in the applicationcontrolsession. If no ResourceCmd exists, the context parameter – LocalScriptFile is used.	FileResourceData	This activity executes a local script file existing on the local file system, specified by the context parameter LocalScriptFile. This can be over-ridden by the JMS header – ResourceCmd. Note: EnableScriptExecution must be ‘TRUE’ for successful execution.
BundleControlActivity (XPDINTEG_BUNDLE_CONTROL_ACTIVITY)	Context Parameters: ·BundleName = name_of_the_controlled_bundle_in_the_platform ·Command = [START | STOP | INSTALL | UNINSTALL | UPDATE] ·[BundleInstallSource = “ResourceData” | "DestinationName" | location of the file(s) that hold the bundle(s) for installation / update ·[BundleVersion = version of the bundle for installation] ·[DeleteInstallationSource = TRUE | FALSE]	any object	inputDataObject	TECHNOLOGY PREVIEW CODE! This activity allows controlling OSGi bundles during ACS flows.The following bundle control commands are available for already installed bundles: Update, Delete, Start, Stop. The OSGi Framework BundleContext and Bundle interface are used to access the bundle which needs to be controlled. Installation of a new bundle is also supported. BundleInstallSource must be given in URI format, e.g. file:///tmp/myBundle.jar or folder location file:///tmp in which case all bundles in this folder will be installed. DeleteInstallationSource: If set to TRUE and installation was successful (RESOLVE state reached), the source files will be deleted.
ProvisioningActivity XPDINTEG_PROVISIONING_ACTIVITY	Context Parameters: ·UpdateSiteLocation = file: datatrans/myupdatesites ·[FeatureVersionMatch = PERFECT (default)] ·[ProvisioningType = INSTALL (default) | REPLACE] ·[DeleteInstallSource = FALSE (default) | TRUE]	any object	inputDataObject	TECHNOLOGY PREVIEW CODE! This activity can be used to install or update Eclipse Features during ACS flows using the IBM Expeditor Provisioning API. UpdateSiteLocation is the path in URI format to the folder with one or many update site folders (an update site folder must contain a valid site.xml), e.g. file:/c:/myupdatesites. Update site folders can only hold ONE Feature and must follow this format: + (e.g. myFeature+1.0.0). FeatureVersionMatch allows overwriting the Eclipse version match parameter. Installing and updating features can be controlled using the ProvisioningType . DeleteInstallationSource: If set to TRUE and installation was successful, the source update site folder will be deleted.
ApplyNewMicroAclActivity (XPDINTEG_APPLY_NEW_MICROACL_ACTIVITY)	Context Parameters: ·[ActivateNow = true | false] ·[NewAclFileLocation = new_file_locatoin | ResourceData | DestinationName] ·[BackupAclFileLocation = location of old micro-acl.xml file for backup] ·[NewMBUsersFileLocation: location_of_new XPDintegMBUsers.xml file | ResourceData | DestinaionName] ·[BackupMBUsersFileLocation = location of old XPDintegMBUsers.xml file for backup] ·[DeleteSourceFilesAfterDeployment = true | false]	any object (when micro-axl.xml location is given in NewAclFileLocation or in NewMBUsersFileLocation) FileResourceData (when	inputDataObject	TECHNOLOGY PREVIEW CODE! This activity allows applying a new authentication and authorization configuration to the current micro broker instance. This is done by either deploying a new XPDintegMBUsers.xml file with usernames and passwords for micro broker access (authentication) or by deploying a new micro-acl.xml file which contains specific micro broker resource access definitions (authorization) or by both. NOTE: This Activity operates with simple JAVA file objects and not with XA resources (no transaction safety is available). ActivateNow specifies whether the new micro-acl.xml file is applied and activated by restarting the micro broker instance (otherwise Expeditor integrator must be restarted). NewAclFileLocation contains the location of new micro-acl.xml file that needs to be applied (Optionally: Value “ResourceData” indicates that the activity inputDataObject contains the new micro-acl.xml. Value “DestinationName” means that the session property contains the new micro-acl.xml file location. BackupAclFileLocation: When this parameter is provided, the current/old micro-acl.xml file is backed up, otherwise it is not. NewMBUsersFileLocation is the location of the new file that needs to be applied (see NewMicroAclFileLocation) DeleteSourceFilesAfterDeployment specifies whether the files under NewAclFileLocation and NewMBUsersFileLocation should be deleted after successful deployment.
Retail specific Activities
BuildPriceUpdateFileFooterActivity (XPDINTEG_PRICE_UPDATE_FOOTER_ACTIVITY)	-NIL-	ResourceData (file)	ResourceData (file)	Adds the footer to the content on the ResourceData and passes this data on as Activity output.
BuildMappingDataFileFooterActivity (XPDINTEG_MAPPING_DATA_FOOTER_ACTIVITY)	-NIL-	ResourceData (file)	ResourceData (file)	Adds the footer to the content on the ResourceData and passes this data on as Activity output.

Building the Flow Definitions for Business Use Cases

The following chapters describe the required flow definition files for the example business use cases BUC_1, BUC_2 and BUC_3 from chapter 1.2.2 Example Business Use Cases for Retail - Overview.

File Transfer Back-end -> Expeditor integrator Flow Definition

The Business Use Case BUC_1 from chapter 1.2.2 Example Business Use Cases for Retail - Overview: FTP File Transfer from Back-end to Expeditor integrator runtime location is represented by the Default_PutFtpFiles.flow which is located in the <XPDINTEG_HOME>/flowdefs/default folder.

The Default_PutFtpFiles.flow consists of the following sequence of Activities:

• MessageToFileActivity
• Optional file custom pre-processing activities, e.g. in the retail example: BuildPriceUpdateFileFooterActivity for price update files or BuildMappingDataFileFooterActivity for mapping data files
• FileWriteToFtpActivity

If no ResourceType is set, this flow is triggered by default by an event with the topicwhich is published by the Queue Dispatcher Service as soon as a known FTP FileTransfer message is received in the ReqInQ and dispatched to the configured local in queue, e.g. the MsgToFtpQ (see Figure 22).
If a ResourceType is provided, the following trigger event is published instead:where the <ResourceType> property will be replaced by the corresponding Resource Type of the transferred data (e.g. for the retail example: PriceUpdFile, MappingDataFile, DiscountDataFile). Make sure that an ACS flow subscribed to the trigger topic with your ResourceType exists.


Figure 22: Flows and Activities for FTP File Transfer from back-end to Expeditor integrator (BUC_1)


Listing 29 shows the retail example listing for the buc100_PutPriceUpdate.flow definition file.

Listing 29: Example flow definitions file for retail example: Transfer Price Update File


Note: There is a generic flow definition file Default_PutFtpFiles.flow that can be used to transfer any file to any FTP target server (see <XPDINTEG_HOME>/flowdefs).

The other supported file transfers are also provided by default flows:

• For file transfers to the file system of the Expeditor integrator runtime server: Default_PutLocalFileSystemFiles.flow. This case covers business use case BUC_3 from chapter 1.2.2 Example Business Use Cases for Retail - Overview.
• For file transfers to SSH servers: Default_PutSshFiles.flow

These flows look similar to the Default_PutFtpFiles.flow. Only the FILE_WRITE_TO_LOCALFILESYSTEM / SSH Activity is specific.

File Transfer Expeditor integrator -> Back-end Flow Definition

The Business Use Case BUC_2 from chapter 1.2.2 Example Business Use Cases for Retail - Overview: FTP File Transfer from Expeditor integrator runtime location to Back-end messaging server is represented by the Default_GetFtpFiles.flow which is located in the <XPDINTEG_HOME>/flowdefs/default folder. In this case, FTP Resource Adapters monitor for given files on the source FTP server (see configuration of Resource Adapters in Ref_1). If files are found which match the monitoring criteria the configurable default flow trigger event
is published by the Resource Monitor (see Figure 23). This default trigger event for FTP Resource Adapters will kick off the Default_GetFtpFiles.flow.

The Default_GetFtpFiles.flow is represented by the sequence of these Activities:

• FileReadFtpActivity
• FileToMessageWriteActivity
• FileTransferConfirmationActivity

Figure 23: Flows and Activities for FTP File Transfer from Expeditor integrator to back-end (BUC_2)

Listing 30 shows the retail example flow for retrieving FTP files from the 4690 FTP server (buc101_GetFtpFiles.flow definition file).


Listing 30: Example flow definitions file for retail example: Transfer FTP files from 4690 PoS Controller (e.g. Translog Files) to messaging back-end (Default_GetFtpFiles.flow)


Note: There is a generic flow definition file Default_GetFtpFiles.flow that can be used to transfer any file from any FTP source server to the back-end messaging system (see <XPDINTEG_HOME>\flowdefs).

The other supported file transfers are also provided by default flows:

• For file transfers from the file system of the Expeditor integrator runtime server: Default_GetLocalFileSystemFiles.flow
• For file transfers from SSH servers: Default_GetSshFiles.flow

These flows look similar to the Default_GetFtpFiles.flow. Only the FILE_READ_LOCALFILESYSTEM / SSH Activity is specific.

File Transfer Back-end -> Expeditor integrator for Local File System Files

The Business Use Case BUC_3 from chapter 1.2.2 Example Business Use Cases for Retail - Overview.: Local File System File Transfer from Back-end to Expeditor integrator runtime location is represented by the Default_PutLocalFileSystemFiles.flow which is located in the <XPDINTEG_HOME>/flowdefs/default folder.
The Default_PutLocalFileSystemFiles.flow consists of the following sequence of Activities:

• MessageToFileActivity
• Optional file custom pre-processing activities, e.g. in the retail example: BuildPriceUpdateFileFooterActivity for price update files or BuildMappingDataFileFooterActivity for mapping data files
• FileWriteToLocalFileSystemActivity

If no ResourceType is set, this flow is triggered by default by an event with the topicIf a ResourceType is provided, the following trigger event will be published instead:where the <ResourceType> is set to the corresponding value in the File Transfer message (see Figure 24). Make sure that an ACS flow subscribed to the trigger topic with your ResourceType exists.


Figure 24: Flows and Activities for File Transfer from back-end to the file system of the Expeditor integrator server (BUC_3)

Listing 31 shows a retail example flow definition file for transferring scale data files to the local file system of the Expeditor integrator runtime server.


Listing 31: Example flow definitions file for retail example: Scale Data File transfer (<XPDINTEG_HOME>/samples/flowdefs/buc102_PutScaleData.flow)


Since there are three different inbound queues available in the default configuration for retail use cases that correspond to the 3 different retail relevant files for the Local File System (print and shelf label files, scale data file), three different flow definition files are also provided by default in order to be able to process all three inbound queues in parallel (see <XPDINTEG_HOME>/samples/flowdefs).

In addition to the buc102_PutScaleData.flow in Listing 31, the buc102_PutShelfData.flow and buc102_PutPrintData.flow files also contain their matching queue names and trigger events (for retail use cases):

• Shelf Data event:
  com/ibm/integrator/flowtriggerevent/FileTransfer/LocalFileSystem/ShelfLabelFile/dispatcher
  Shelf Data queue: jms/XPDinteg_shelfLabelQ
• Print Data event:
  com/ibm/integrator/flowtriggerevent/FileTransfer/LocalFileSystem/PrintLabelFile/dispatcher
  Print Data queue: jms/XPDinteg_printDataQ
  

Note: There is a generic flow definition file Default_PutLocalFileSystemFiles.flow that can be used to transfer any file to any local file system directory (see <XPDINTEG_HOME>/flowdefs/default).

Building the Flow Definitions for Additional Use Cases

Additional flow definition files are provided to cover additional use cases. Figure 25 shows the flows of three example use cases which can be triggered by control messages sent to the CtrlQ with

• MessagePurpose=ConfigUpdate
• MessagePurpose=BrowseLocalFileSystem
• MessagePurpose=ExecuteScript

Figure 25: Examples for additionally available system control flow definitions

Currently, the following flow definitions are available (see Table 28).

Table 28: Currently supported Application Control Service flows (in <XPDINTEG_HOME/flowdefs>)

Flow Name	Description
Default file related use case flows	Located in <XPDINTEG_HOME>/flowdefs/default
Default_PutFtpFiles.flow	Flow tht transfers any as FileTransfer message at the ReqInQ received FTP file to any given 4690 PoS Controller or any FTP server
Default_PutSshFiles.flow	Flow transfers any as FileTransfer message at the ReqInQ received SSH file to any given SSH server.
Default_PutLocalFileSystemFiles.flow	Flow transfers any as FileTransfer message at the ReqInQ received file to the local file system of the Expeditor integrator runtime.
Default_ReqFtpFiles.flow	Flow retrieves requested files from any given 4690 PoS Controller or FTP server and sends it to the back-end using the bridged ResOutQ (requested using a FileRequest message).
Default_ReqSshFiles.flow	Flow retrieves requested files from any given SSH server and sends it to the back-end using the bridged ResOutQ (requested using a FileRequest message).
Default_ReqLocalFileSystemFiles.flow	Flow retrieves requested files from given local directory and sends it to the back-end using the bridged ResOutQ (requested using a FileRequest message).
Default_GetFtpFiles.flow	Flow delivers a given (monitored) file from any given 4690 PoS Controller or FTP server and sends it to the back-end using the bridged ResOutQ.
Default_GetSshFiles.flow	Flow delivers a given (monitored) file from any given SSH server and sends it to the back-end using the bridged ResOutQ.
Default_GetFileSystemFiles.flow	Flow delivers a given (monitored) file from any local file system directory and sends it to the back-end using the bridged ResOutQ.
Default JDBC resource related use case flows	Located in <XPDINTEG_HOME>/flowdefs/default
Default_DbRecordSelect.flow	Flow retrieves requested result set from given database resource and sends it to the back-end in the Expeditor integrator default XML format using the bridged ResOutQ (requested using a DBRecordSelect message or triggered by the JDBC Resource Adapter).
Default_DbRecordUpdateUsingSQL.flow	Flow updates any JDBC resource using the provided SQL command(s) in the message payload of the DBRecordUpdate message.
Default_DbRecordUpdateUsingXML.flow	Flow updates any JDBC resource using the provided XML data in the message payload of the DBRecordUpdate message.
Default_DbRecordUpdateUsingXPDintegXML.flow	Flow updates any JDBC resource using the provided Expeditor integrator default XML formatted data in the message payload of the DBRecordUpdate message.
Default Message resource related use case flows	Located in <XPDINTEG_HOME>/flowdefs/default
Default_MessageForward.flow	Incoming message carries another message as payload and is transparently moved to another local queue. Default flow is triggered by Queue Dispatcher for MessageForward messages.
Sample Business use case flows (e.g. for retail customers)	Located in <XPDINTEG_HOME>/samples/flowdefs
buc100_PutPriceUpdate.flow	Flow transfers at the ReqInQ received price update files to any given 4690 PoS Controller or FTP server.
buc100_PutDiscountData.flow	Flow transfers at the ReqInQ received discount data files to any given 4690 PoS Controller or FTP server.
buc100_PutMappingData.flow	Flow transfers at the ReqInQ received mapping data files to any given 4690 PoS Controller or FTP server.
buc102_PutPrintData.flow	Flow transfers at the ReqInQ received print data files to any given local file system directory.
buc102_PutScaleData.flow	Flow transfers at the ReqInQ received scale data files to any given local file system directory.
buc102_PutShelfData.flow	Flow transfers at the ReqInQ received shelf data files to any given local file system directory.
System control flows	Located in <XPDINTEG_HOME>/flowdefs/system
Default_BrowseFtpFiles.flow	Flow retrieves a requested FTP file listing from any given 4690 PoS Controller or FTP server directory and sends a list of file names back to the back-end using the bridged ResOutQ (triggered by control message).
Default_BrowseSshFiles.flow	Flow retrieves a requested SSH file listing from any given SSH server directory and sends a list of file names back to the back-end using the bridged ResOutQ (triggered by control message).
Default_BrowseLocalFileSystemDir.flow	Flow retrieves a requested file listing from any given local file system directory and sends a list of file names to the back-end using the bridged ResOutQ (triggered by control message).
Default_BrowseQueue.flow – Browse local queue / retrieve list of message IDs	Flow retrieves a requested listing of messages from any local queue of the Expeditor integrator and sends this as a list of MessageIds and other custom header value pairs to the back-end using the bridged ResOutQ (triggered by control message).
Default_ConfigUpdate.flow	Flow detaches a new Expeditor integrator configuration file (XPDinteg.xml) to a given local directory and updates the Expeditor integrator component’s configuration stores (triggered by control message).
Default_ConfigUpdateResourceCmd.flow	Flow updates the Expeditor integrator component’s configuration stores with the new configuration values in the message payload (triggered by control message).
Default_UserConfigUpdateResourceCmd.flow	Flow updates the Expeditor integrator component’s User Admin store with the new configuration values in the message payload (triggered by control message).
Default_LocalConfigUpdate.flow	A new version of the Expeditor integrator configuration file (XPDinteg.xml) is manually copied to the <XPDINTEG_HOME>\config\new folder. The content of this file is used now.
Default_LocalUserConfigUpdate.flow	A new version of the Expeditor integrator user-configuration file (XPDintegRoles.xml) is manually copied to the <XPDINTEG_HOME>\config\new folder. The content of this file is applied to the User Admin configuration and is used now.
Default_UserConfigUpdate.flow	Flow detaches a new Expeditor integrator User Admin store configuration file (XPDintegRoles.xml) to a given local directory and updates the Expeditor User Admin configuration store (triggered by control message).
Default_DrainQueue.flow	Flow deletes the content of a given local queue of the Expeditor integrator (triggered by control message).
Default_FileExecute.flow	Flow detaches a script file in the message payload to a given local directory and executes it (triggered by control message).
Default_HouseKeeping.flow	Flow triggers Expeditor integrator house keeping operations (triggered by control message).
Default_MaintenanceUpdate.flow	Flow toggles Expeditor integrator Maintenance mode on or off (triggered by control message).
Default_PlatformRestart.flow	Flow can stop or re-start the Expeditor integrator platform (triggered by control message).
Default_ProblemDetermination.flow	Flow starts IBM Support Assistant and creates ZIP file with support information which can be sent back to the back-end using the bridged ResOutQ (triggered by control message).
ACS sample flows (sample flows, not active)	Located in <XPDINTEG_HOME>/samples/flowdefs
Secured_ConfigUpdate.flow	Configuration Update flow which requires correct credentials in the ConfigUpdate control message for execution.
PutPriceUpdate_wCustomCBE.flow	Price update flow which contains example for the creation of custom CBE events.

Please, contact your IBM representative for additionally available Resource Adapters, Activities and Flow definitions.

Create Custom ACS Flows

Flow definition files can be created manually to configure the Expeditor integrator for additional (business) use cases. Please, look at the catalogue of existing Activities (see Table 27) and combine them in a flow definition file according to the flow language definition of chapter 4.1.2 Example: Create Custom CBE Events within Flows. Make sure to provide a unique Process Name for the local runtime in the flow definition file.

Recommendation:

• Use an existing flow file and extend/change it.
• Make sure to provide a unique Process Name for the local runtime and that the flow is triggered by the correct OSGi Event Admin event.
• Double check the configured folder where the new flow definition files should be stored and which extension it should have (see XPDinteg.xml).
• Look in the <XPDINTEG_HOME>/samples/flowdefs directory for additionally provided flows.

Example: Configure Message Forwarding

This example describes how Expeditor integrator is configured to forward an unknown incoming message in local queue CustomerQ_A to another local queue CustomerQ_B (Expeditor integrator JMS Custom Header properties are not available as selection criteria.). The message transfer from one queue to another is done within an ACS Flow to allow data transfer within transactional context and business (state) monitoring (sending of CBE events).

Chapter 2.4.1.3 Messages are passed on to other Queues/Topics provides an introduction into the MessageForward use case.

These are the required configuration steps:

1. Create local in queue CustomerQ_A and local target queue CustomerQ_B (e.g. in Section_3: QUEUE and TOPIC CONFIG in XPDinteg.xml configuration file, see Ref_1) and provide JNDI keys:
   
   Listing 32: Message forwarding example configuration: queue set-up
   

   <queue purpose="CustomerQ_A">
   

   	<queue-name>XPDinteg_CustomerQ_A</queue-name>
   

   	<jndi-key>jms/XPDinteg_CustomerQ_A</jndi-key>
   

   </queue>
   

   <queue purpose="CustomerQ_B">
   

   	<queue-name>XPDinteg_CustomerQ_B</queue-name>
   

   	<jndi-key>jms/XPDinteg_CustomerQ_B</jndi-key>
   

   </queue>
   

   
   
2. Create JMS_DESTINATION_ADAPTER (e.g. in Section_5/6: RESOURCE MONITOR and ADAPTER Configuration in XPDinteg.xml configuration file; use unique adapter name and ResourceType; see Ref_1)
   
   Listing 33: Message forwarding example configuration: JMS Resource Adapter set-up
   

   <!-- Sample JMS Resource Adapter -->
   

   <adapter type="XPDINTEG_JMS_DESTINATION_ADAPTER" name="Msg_Forwarding_Example">
   

        <!-- async mode -->
   

        <listener>
   

              <topic>com/ibm/integrator/flowtriggerevent/MessageForward/ExampleType/JmsAdapter</topic>
   

   	</listener>
   

        <configuration>
   

              <param name="ResourceType" value="ExampleType"/>
   

             <param name="JndiConnectionFactoryKey" value="jms/XPDinteg_ConnectionFactory"/>
   

             <param name="JndiDestinationKey" value="jms/XPDinteg_CustomerQ_A"/>
   

             <param name="JndiDeadLetterKey" value="jms/XPDinteg_ServerDeadletterQ"/>
   

             <param name="ValidateLocationId" value="OFF"/>
   

       </configuration>
   

   </adapter>
   

   
   
3. Create Resource Mapper configuration which provides further information for the destination queue, Deadletter queue etc. (e.g. in Section_7: Messaging Service in XPDinteg.xml configuration file, see Ref_1)
   
   Listing 34: Message forwarding example configuration: Resource Mapper set-up
   

   <!-- Sample Resource Mapper -->
   

   <resource-mapping type="ExampleType">
   

     	<param name="TransportType" value="MESSAGE"/> 	
   

   	<param name="Description" value="Write messages from CustomerQ_A to CustomerQ_B"/> 	
   

   	<param name="TransferMode" value="ASCII"/> 	
   

   	<param name="DestinationName" value="jms/XPDinteg_CustomerQ_B"/> 	
   

   	<param name="Encoding" value="UTF-8"/>
   

   </resource-mapping>
   

   
   
4. Activate this new configuration:
1. Stop Expeditor integrator if it is running by entering close in the OSGi console
2. Run <XPDINTEG_HOME>/resetscript/XPDintegReset.bat (Caution: Local queues will be re-created and old messages will be deleted.)
3. Start Expeditor integrator by running <XPDINTEG_HOME>/XPDintegStart.bat
   
   
5. Create ACS Flow (e.g. Msg_Forwarding_Example.flow with a unique Process Name). This flow is triggered by this trigger event topic which is published by the Resource Adapter. The flow finally copies messages from CustomerQ_A queue to CustomerQ_B queue within a transaction (CBE status events are also generated, flow configuration is described in chapter 4.1 Introduction to the Expeditor integrator Application Control Service; see example in Listing 35).
   
   The target queue name (CustomerQ_B) could also be provided in the XPDINTEG_MESSAGE_WRITE Activity as context parameter DestinationName (if not set in the Resource Mapper).
   
   The property DestinationName given in the JMS Custom Header or assigned by the Resource Mapper would have priority over the XPDINTEG_MESSAGE_WRITE Activity configuration (e.g. activity context parameter DestinationName="jms/XPDinteg_CustomerQ_A").
   Furthermore, Expeditor integrator JMS Custom Header properties can be edited and new header properties can be added. The example in Listing 35 shows how the JMS header is extended with the custom property PecId. The assigned value of PecId is the value of the Expeditor integrator JMS Custom Header property DestinationName. If none of the Expeditor integrator default JMS custom message header properties should be included in the outgoing message,
   AddDefaultHeaders=”FALSE”
   
   …should be added as activity context parameter to XPDINTEG_MESSAGE_WRITE (see chapter 2.4.3 JMS Custom Header Creation for Messages from Expeditor integrator to Back-end (outbound)).
   
   Listing 35: Message forwarding example configuration: ACS Flow configuration (Msg_Forwarding_Example.flow file, place in <XPDINTEG_HOME>/flowdefs)
   

   <?xml version="1.0" encoding="UTF-8"?>
   

   <Process Name="Msg_Forwarding_Example_Process" Trigger="com/ibm/integrator/flowtriggerevent/MessageForward/ExampleType/JmsAdapter">
   

   	<XPDintegActivity 
   

   		Name="Msg_Forwarding_Example_ReadResource"
   

   		ActivityName="XPDINTEG_MESSAGE_READ"
   

   		PropertyKey="DATA_REFERENCE"
   

   	/>
   

   	<XPDintegActivity 
   

   		Name="Msg_Forwarding_Example_MessageWrite"
   

   		ActivityName="XPDINTEG_MESSAGE_WRITE"
   

   		JndiConnectionFactoryKey="jms/XPDinteg_ConnectionFactory"
   

   		DestinationName="jms/XPDinteg_CustomerQ_A"
   

   		Header1="ADD::PecId::<DestinationName>"/> 
   

   </Process>
   

   
   
6. Activate the new ACS Flow (e.g. Msg_Forwarding_Example.flow) by copying the flow file into the <XPDINTEG_HOME>/flowdefs directory. It will take the configured period of time until the new flow file is picked up (default polling interval: 2 minutes). The OSGi console windows reports the new registered flow if the console logging was switched on (see Installing and Configuring the IBM Lotus Expeditor integrator platform).

Example: Create Custom CBE Events within Flows

Lotus Expeditor integrator ACS flows run in transactional context. CBE events are created to indicate the status of the transaction. These CBE events are published using the OSGi Event Admin Service. Custom subscribers can filter for these events for further processing. Examples for such subscribers are the Expeditor integrator

• Custom Event Service for forwarding business events (e.g. transaction status events) to configured back-end queues (default: EventQ)
• Custom Log Service for forwarding of technical (log) events to configured back-end queues (default: LogQ)
• Tivoli Monitoring Service for forwarding any filtered event to the Tivoli Enterprise Console at the business back-end.

The structure of the Expeditor integrator CBE events can be configured (in the XPDinteg.xml configuration file, see Installing and Configuring the IBM Lotus Expeditor integrator platform, Ref_1).

In addition to this, further fine-grained business monitoring capabilities are supported by the provided XPDINTEG_PUBLISH_CBE_ACTIVITY. This Activity can be transparently injected in any ACS flow. It takes any input data object and passes it transparently on. The PublishCBEActivity allows for customization of CBE attributes and CBE elements (see Listing 36).

It is recommended to leave the…...unchanged, since this fits the Expeditor integrator schema. The TRANSACTION_STARTED, TRANSACTION_FAILED and TRANSACTION_COMPLETED are created by the ACS when a flow is started and finished.


Listing 36: PublishCBEActivity configuration example


The configuration properties of Listing 36 are explained in Table 29. For more details, please refer to the Installing and Configuring the IBM Lotus Expeditor integrator platform, Ref_1.

Table 29: Explaination of CBE configuration example values

Property	Explanation
Attribute.extensionName=name:	String: name of the additional attribute in the CBE header
value:	“my_value” value of the extension attribute. Place holders for Expeditor integrator context variable values are indicated by <jms_custom_header_property> what is represented in XML like this: value:&lt;jms_custom_header_property&gt; (e.g. &lt;TransationId&gt; is the place holder for the JMS Custom Header property TransactionId)
Element.my_element_name=”name:	“my_element_name" String: name of the additional extended data element in the CBE (e.g. DestinationPath)
value:	“my_value” value of for the extended data element. Place holders for Expeditor integrator context variable values are indicated by <jms_custom_header_property> what is represented in XML like this: values:{“&lt;jms_custom_header_property&gt;} (e.g. value:{&lt;DestinationPath&gt;} is the place holder for the JMS Custom Header property DestinationPath)
type:	"string" (type of the extension attribute or element)
mandatory:	"true" OR "false“ defines whether attribute or element must always be included or not

Example: Retrieve data from remote HTTP server and store it as message in local queue

This example shows how XML data is retrieved from HTTP server source and put into an XML message for further processing.

Scenario assumption:

• Remote HTTP Server is available and provides an XML file with the data which needs to be picked up. It is assumed that this HTTP server allows deleting the file from the HTTP source when it is retrieved by Expeditor integrator (HTTP action HttpDelete must be possible). The following example shows how a potential write-enabled directory on the HTTP server is accessed securely with HTTP Basic Authentication and SSL.
• Requirement: Retrieve the most current XML structure as file from the HTTP server (e.g. https://scandium/write_enabled_dir/sample.xml every 2 minutes, put the content in a message, and persist it into local MeterReadInQ.

Required steps:

• Configure local queue for result messages
• Configure HTTP Adapter which polls the HTTP server for the required XML file every 2 minutes.
• Create flow which retrieves the XML file when existent, sticks it into a message and puts the message in the local result queue.

1. Configure local queue for result messages (MeterReadInQ) in XPDinteg.xml or using the Expeditor integrator GUI:
Listing 37: Local queue configuration for HTTP example


2. Configure HTTP Adapter which polls the HTTP server for the required XML file every 2 minutes:
Listing 38: HTTP_ADAPTER configuration for HTTP example


3. Create AMRDataPickup_HttpDataPutInMsg.flow which retrieves data from HTTP server and puts them in local queue (MeterReadInQ, see next Listing):
Listing 39: ACS flow configuration for HTTP example

Example: Activity Configuration for Writing XML to local Database

This example explains how XML structures are mapped to database fields in the XPDINTEG_MESSAGE_TO_DB_XML activity.

The following XML structure in Listing 40 is locally received from an arbitrary source (e.g. local file, HTTP server).

Listing 40: Example of XML structure which is to be written to the local database


This XML structure has one root element MeterData which contains time attributes and the Meter sub structure. The Meter structure comprises multiple Datapoint entries with their own properties.
The example retrieves the values for the first Datapoint “EnergyTotal” and stores them into the database. The following table shows the assumed mapping of the required XML properties to the database fields (table columns; see Table 30).

Table 30: Mapping of XML properties to database fields

Database Field	Mapped XML Property
MSGID	MeterData/ID
DEVICEADDR	MeterData/Meter/ADDR
METERID	MeterData/Meter/ID
MEDIUM	MeterData/Meter/MEDIUM
MANUFACTURER	MeterData/Meter/MFCT
VERSION	MeterData/Version
NAME	MeterData/Meter/Datapoint(1)/Name
DATAPOINT	MeterData/Meter/Datapoint(1)/ID
VALUE	MeterData/Meter/Datapoint(1)/Value
UNIT	MeterData/Meter/Datapoint(1)/Unit
TIME	MeterData/Meter/Datapoint(1)/Time
TIMESTAMP	MeterData/Meter/Datapoint(1)/Timestamp
TIMESOURCE	MeterData/Meter/Datapoint(1)/TimeSource

The XPDINTEG_MESSAGE_TO_DB_XML activity requires access information for the database. These are provided under DBURI and DRIVER_CLASS. Please, note how the SQL statement is created. The order of the database fields in the INSERT statement must collorate with the column numbers in the XPath statements!

For example, the database field MSGID is the first one in the SQL INSERT statement and maps to Column_1 in the XPath statement (see Column_1=xpath:/MeterData/@ID in Listing 41). XML properties are addressed according to their hierarchy (separated by ‘/’) and by the ‘@’ prefix. If multiple entries of one type exist (e.g. Datapoint in the example), each entry is addressed sequentially by index numbers (e.g. first Datapoint in XML structure is addressed with Datapoint[1]).


Listing 41: Configuration example XPDINTEG_MESSAGE_TO_DB_XML activity

Example: Retrieve data from local database and forward as XML message

This example shows how a ResultSet is retrieved from a local database and put into local queue as XML message for further processing.

Scenario assumption:

• Local Derby database AMRDataDB exists: <XPDINTEG_HOME>/inbound/AMRDataDB
• Table AMRData_Meter002 contains records which are periodically added with current time stamps (field TIMESTAMP) by another process
• Requirement: Retrieve the most current record from the table every 15 minutes, write it into a local queue message and write it into local MeterReadOutQ.

Required steps:

• Configure local queue for result messages
• Configure JDBC Adapter for retrieving the record with the youngest time stamp every 15’.
• Create flow which retrieves data from JDBC Adapter and writes it into local queue.

1. Configure local queue for result messages (MeterReadOutQ)
• Configure local queue in XPDinteg.xml or using the Expeditor integrator GUI (see Listing 42).
  
  Listing 42: Local queue configuration for JDBC example
  

  <messaging-service>
  

     <microbroker>
  

        <queues> ...
  

  	<queue purpose="MeterReadOutQueue">
  

  		<queue-name>XPDinteg_MeterReadOutQ</queue-name>
  

  		<jndi-key>jms/XPDinteg_MeterReadOutQ</jndi-key>
  

  	</queue>
  

  ...
  

  
  
2. Configure JDBC Adapter for retrieving data
• Assumption: local Derby database AMRDataDb exists and AMRData_Meter002 table contains records with fields TIMESTAMP and DEVICEADDR.
• This SQL statement retrieves the record with the youngest time stamp and with DeviceAddr=123456 from the local AMR database table AMRData_Meter002:
  SELECT * from APP.AMRData_Meter002 WHERE TIMESTAMP = (SELECT MAX(TIMESTAMP) FROM AMRData_Meter001) AND DeviceAddr='123456'
• Configure JDBC Adapter with polling interval = 15 minutes (=900’000msec), see Listing 43
  
  Listing 43: JDBC_ADAPTER configuration for JDBC example
  

  …
  

  <adapter type="XPDINTEG_JDBC_ADAPTER" name="RetrieveDataFromDb_AMR_Meter002_Adapter">
  

     <polling>
  

  	<interval>900000</interval>
  

  	<startup-delay>90000</startup-delay>
  

  	<!-- Adapter polls every 15' local AMR DB and selects record from table 
  

  	 AMRData_Meter002 with latest timestamp and DeviceAddr=123456
  

  	 triggers AMRDataDB_RecordSelect_using_MeterXML_PutInMsg.flow -->
  

  <meta-data>SQL-select * from APP.AMRData_Meter002 WHERE TIMESTAMP = (SELECT MAX(TIMESTAMP) FROM AMRData_Meter001) AND DeviceAddr='123456'</meta-data>
  

  <topic>com/ibm/integrator/flowtriggerevent/DBRecordSelect/DB/AmrBillingRecord123456/JdbcAdapter</topic>
  

     </polling>
  

     <configuration>
  

  	<param name="ResourceType" value="AmrRecord123456"/>
  

  	<param name="TransferMode" value="ASCII"/>
  

  	<param name="DBURI" value="jdbc:derby:datatrans/inbound/AMRDataDB"/>
  

  	<param name="DRIVER_CLASS" value="org.apache.derby.jdbc.EmbeddedDriver"/>
  

     </configuration>
  

  </adapter>
  

  ...
  

  
  
3. Create flow
• Create the ACS Flow which is triggered by the previously configured JDBC_Adapter. The AMRDataDB_RecordSelect_using_MeterXML_PutInMsg_Process flow retrieves the latest record from the AMRData_Meter002 table. It converts it into a simple XML structure before it is stuck into the MeterReadOutQ as XML message.
• The flow configuration example is given in Listing 44.
  
  Listing 44: Flow configuration for database record retrieval example.
  

  <?xml version="1.0" encoding="UTF-8"?> 
  

  <!--  Licensed Materials - Property of IBM 5724-R09   © Copyright IBM Corp. 2008  All Rights Reserved. --> 
  

  <!-- AMR Example Flow (3/3):      
  

  	Flow is triggered by the JDBC Adapter which periodically polls the local AMR database for the latest record. The database was filled by the predecessor flow:      
  

  	AMRDataDB_RecordUpdate_using_MeterXML_GetFromMsg_Process      
  

  	Now, the record with the most current timestamp is retrieved and put into     
  

  	 jms/XPDinteg_MeterReadOutQ queue (to the back-end Messag Broker). --> 
  

  <Process Name="AMRDataDB_RecordSelect_using_MeterXML_PutInMsg_Process" Trigger="com/ibm/integrator/flowtriggerevent/DBRecordSelect/DB/AmrBillingRecord123456/JdbcAdapter">
  

      <XPDintegActivity  	Name="AMRDataDB_RecordSelect_PutInMsg_Process_DB_Read_Activity" 	
  

  				ActivityName="XPDINTEG_DB_READ" 	PropertyKey="DATA_REFERENCE"  />
  

      <XPDintegActivity  	Name="AMRDataDB_RecordSelect_PutInMsg_Process_DB_Serialization_Activity" 	
  

  				ActivityName="XPDINTEG_DB_SERIALIZATION_ACTIVITY" 	Format="SIMPLE_XML" />
  

      <XPDintegActivity  	Name="AMRDataDB_RecordSelect_PutInMsg_Process_MessageWrite_Activity" 	
  

  				ActivityName="XPDINTEG_MESSAGE_WRITE" 	
  

  				JndiConnectionFactoryKey="jms/XPDinteg_ConnectionFactory" 	
  

  				JndiOutputDestinationKey="jms/XPDinteg_MeterReadOutQ"   />
  

  </Process>