This appendix provides information about the command-line and Java-based tools provided by Oracle SOA Suite for healthcare integration to monitor and manage message sequencing. You can use these functions in custom clients.
This appendix includes the following topics:
Messages processed through Oracle SOA Suite for healthcare integration are sequenced through the B2B sequence manager. The message sequencing information is stored in the B2B_SEQUENCE_MANAGER database table in order to preserve the correct order of messages. At times, the process of sequencing messages must be managed. For example, if a message in an endpoint becomes stacked and cannot be processed, it can block all other messages for that endpoint from being processed. In this case, manual intervention is required in order to remove or resubmit the message and restart sequencing.
Using the tools provided with Oracle SOA Suite for healthcare integration to monitor and manage message sequencing, you can do the following:
View all endpoints along with their current state
View messages by state, endpoint, or a combination of both
Discard messages by state, endpoint, message ID, or state and endpoint
Resubmit messages that had errors
Pause and resume message sequencing for an endpoint.
Note:
You can view the sequenced messages in the Oracle SOA Suite for healthcare integration console. See Working with Sequenced Messages for more details.
You can use the Java methods provided for sequence message management to create your own clients to monitor and manage the messages in the B2B_SEQUENCE_MANAGER table.
To use the Java methods, create an instance of SequenceManagerUtility
using the jndi.properties
file as a parameter. For example:
private static Properties getProperties(String s) throws IOException { Properties properties; FileInputStream fileinputstream = new FileInputStream(s); properties = new Properties(); properties.load(fileinputstream); return properties; } SequenceManagerUtility seqUtil = new SequenceManagerUtility(getProperties("/tmp/jndi.properties")); seqUtil.listSequenceTargets();
For information on creating the jndi.properties
file, see Prerequisites for Running Command-Line Tools.
You can generate a report that lists the messages that are pending in the sequence table with a specific state and for a specific endpoint. The resulting report includes the message IDs and the corresponding state for each.
The syntax of this method is:
public java.util.List<java.lang.String> listSequenceTargets() throws java.lang.Exception
You can generate a report of pending sequenced messages based on the state and endpoint of the messages, based solely on the state, or based solely on the endpoint. This command lists the messages that are pending in the sequence table based on the options you specify. The resulting report includes the message IDs and the corresponding state for each. There are four methods you can use to list sequenced messages, depending on the criteria you want to use.
Listing Pending Sequenced Messages Based on State and Endpoint
The syntax of this method is:
public java.util.List<java.lang.String> getSequenceMessagesByTargetAndState(java.lang.String target, java.lang.String state) throws java.lang.Exception
Parameter | Description |
---|---|
target |
The name (or the IP address and port number) for the endpoint for which you want to list messages. For example:
|
state |
The state of the messages to include in the report. Specify one of the following states:
|
Listing Pending Sequenced Messages Based on State
The syntax of this method is:
public java.util.List<java.lang.String> getSequenceMessagesByTarget(java.lang.String state) throws java.lang.Exception
Parameter | Description |
---|---|
state |
The state of the messages to include in the report. Specify one of the following states:
|
Listing Pending Sequenced Messages Based on Endpoint
The syntax of this method is:
public java.util.List<java.lang.String> getSequenceMessagesByTarget(java.lang.String target) throws java.lang.Exception
Parameter | Description |
---|---|
target |
The name (or IP address and port number) for the endpoint for which you want to list messages. |
You can delete sequenced messages from the B2B_SEQUENCE_MANAGER table based on the following criteria combinations:
State and endpoint of the messages
State of the messages
Endpoint of the messages
Endpoint direction (for endpoint pairs with both inbound and outbound)
Message ID
First message only for an endpoint
The discard methods let you manage the messages in the B2B_SEQUENCE_MANAGER table. This is useful in cases where a message is stacked and is blocking other messages from being processed or when there is an issue with a specific message that means it should not be processed sequentially.
Note:
Discarding messages from the sequence manager table does not delete any of the business messages.
Discarding Sequenced Messages Based on State and Endpoint
The syntax of this method is:
public java.util.List<java.lang.String> discardSequencedMessageByStateAnDendpoint(java.lang.String target, java.lang.String state) throws java.lang.Exception
Or:
public java.util.List<java.lang.String> discardSequencedMessageByStateAnDendpoint(java.lang.String target, java.lang.String state, java.lang.String direction) throws java.lang.Exception
Parameter | Description |
---|---|
target |
The name (or IP address and port number) for the endpoint associated with the messages to delete. |
state |
The state of the messages to delete. Specify one of the following states:
|
direction |
The direction of the messages in the endpoint pair for which you want to discard messages. Specify INBOUND or OUTBOUND. Only use this option if you are deleting messages for one direction of an endpoint pair. |
Discarding Sequenced Messages Based on State
The syntax of this method is:
public java.util.List<java.lang.String> discardSequencedMessageByState(java.lang.String state) throws java.lang.Exception
Parameter | Description |
---|---|
state |
The state of the messages to discard. Specify one of the following states:
|
Discarding Sequenced Messages Based on Endpoint
The syntax of this method is:
public java.util.List<java.lang.String> discardSequencedMessageByTarget(java.lang.String target) throws java.lang.Exception
Or:
public java.util.List<java.lang.String> discardSequencedMessageByTarget(java.lang.String target, java.lang.String direction) throws java.lang.Exception
Parameter | Description |
---|---|
target |
The name (or IP address and port number) of the endpoint for which you want to discard messages. |
direction |
The direction of the messages in the endpoint pair for which you want to discard messages. Specify INBOUND or OUTBOUND. Only use this option if you are deleting messages for one direction of an endpoint pair. |
Discarding Sequenced Messages Based on Message ID
The syntax of this method is:
public java.util.List<java.lang.String> discardSequencedMessageByMessageId(java.lang.String msgId) throws java.lang.Exception
Parameter | Description |
---|---|
msgId |
The message ID of the message you want to discard. |
Discarding the First Message for an Endpoint
The syntax of this method is:
public java.util.List<java.lang.String> discardFirstSequemceMessageByTarget(java.lang.String target) throws java.lang.Exception
Parameter | Description |
---|---|
target |
The name (or IP address and port number) of the endpoint for which you want to discard the first message. |
Reprocessing messages is a useful option to make sure messages are processed in sequence after there is an issue with an endpoint (for example, if the endpoint goes down and then resumes processing).
The syntax of this method is:
public boolean processSequenceMessageByMessageId(java.lang.String messageId) throws java.lang.Exception
Parameter | Description |
---|---|
messageId |
The message ID of the message to reprocess. |
There might be times when sequence message processing must be paused for a specific endpoint, such as when an external system fails. In this case, the endpoint can be paused until the system is restored. After the system is restored, you can resume processing for the endpoint. For endpoint pairs, you can pause or resume the endpoint for both inbound and outbound, only for inbound, or only for outbound.
Pausing an Endpoint
The syntax of this method is:
public boolean pauseSequenceTarget(java.lang.String target) throws java.lang.Exception
Or:
public boolean pauseSequenceTarget(java.lang.String target, java.lang.String direction) throws java.lang.Exception
Parameter | Description |
---|---|
target |
The name (or IP address and port number) for the endpoint you want to pause. |
direction |
The direction of the messages in the endpoint pair you want to pause. Specify INBOUND or OUTBOUND. Only use this option if you are pausing one direction of an endpoint pair. |
Resuming an Endpoint
The syntax of this method is:
public boolean resumeSequenceTarget(java.lang.String target) throws java.lang.Exception
Or:
public boolean resumeSequenceTarget(java.lang.String target, java.lang.String direction) throws java.lang.Exception
Parameter | Description |
---|---|
target |
The name (or IP address and port number) for the endpoint you want to resume |
direction |
The direction of the messages in the endpoint pair you want to resume. Specify INBOUND or OUTBOUND. Only use this option if you are resuming one direction of an endpoint pair. |
The command-line tools are run using Apache ant.
These tools are for administrator use only. No security or permission checks are performed to prevent the logged-in user from viewing or discarding data.
Before you can run the command-line tools, you must make sure your environment is configured correctly. Do the following before running any commands:
Note:
After running any command-line tool, restart the healthcare integration user interface or B2B Console. This is because the interfaces cache some metadata and any command-line action that updated the metadata could lead to invalid cached data.
All of the command-line tools can be run without any JNDI credentials. To restrict the command-line tools from anonymous use, enter the following information in the jndi.properties
file:
java.naming.security.principal=weblogic
java.naming.security.credentials=weblogic_password
You can generate a report that lists all the endpoints and their respective states to help you determine the health of each endpoint.
The syntax of this command is:
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=listTargets
Option | Description |
---|---|
-Dmode |
The mode in which to run the command. For this purpose, set this option to listTargets. |
You can generate a report of pending sequenced messages based on the state and endpoint of the messages, based solely on the state, or based solely on the endpoint. This command lists the messages that are pending in the sequence table based on the options you specify. The resulting report includes the message IDs and the corresponding state for each.
The syntax of this command is:
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dstate=message_state -Dendpoint=endpoint_name
Option | Description |
---|---|
-Dmode |
The mode in which to run the command. For this purpose, set this option to report. |
-Dstate |
The state of the message to include in the report. Specify one of the following states:
To generate a report with all states, do not use this option when running the command. |
-Dendpoint |
The name (or IP address and port number) of the endpoint for which you want to list messages. To generate a report for all targets, do not use this option when running the command. |
Example - Listing Sequenced Messages Based on State and Endpoint
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dstate=STACKED -Dendpoint=Pharmacy01
Example - Listing Sequenced Messages Based on State Only
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dstate=PROCESSED
Example - Listing Sequenced Messages Based on Endpoint Only
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dendpoint=Pharmacy01
You can delete sequenced messages from the SEQUENCE_MANAGER database table based on the following criteria combinations:
State and endpoint of the messages
State of the messages
Endpoint of the messages
Message ID
First message only for an endpoint
Discard mode lets you manage the messages in the B2B_SEQUENCE_MANAGER table. This is useful in cases where a message is stacked and is blocking other messages from being processed or when there is an issue with a specific message that means it should not be processed sequentially.
Note:
Discarding messages from the sequence manager table does not delete any of the business messages.
The syntax of this command is:
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dstate=message_state -Dendpoint=endpoint_name -Dmsgid=message_id
Option | Description |
---|---|
-Dmode |
The mode in which to run the command. For discarding messages, set this option to discard. If you are discarding only the first message in an endpoint, set this option to discardFirst and only specify the endpoint. |
-Dstate |
The state of the messages to discard. Specify one of the following states:
To discard messages of all states, do not use this option when running the command. |
-Dendpoint |
The name (or IP address and port number) of the endpoint for which you want to list messages. To discard messages for all targets, do not use this option when running the command. |
-Dmsgid |
The message ID of a specific message to delete. When you use this option, you must only specify the mode and not the target or state. |
Example - Discarding Sequenced Messages Based on State and Endpoint
This example deletes all messages from the sequence manager for the Pharmacy01 endpoint with a state of PROCESSED.
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dendpoint=Pharmacy01 -Dstate=PROCESSED
Example - Discarding Sequenced Messages Based on State
This example deletes all messages from the sequence manager with a state of PROCESSED.
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dstate=PROCESSED
Example - Discarding Sequenced Messages Based on Endpoint
This example deletes all messages from the sequence manager for the Pharmacy01 endpoint.
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dendpoint=Pharmacy01
Example - Discarding the First Sequence Message of an Endpoint
This example deletes the first message for the Pharmacy 01 endpoint from the sequence manager.
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discardFirst -Dendpoint=Pharmacy01
Example - Discarding Sequenced Messages Based on Message ID
This example deletes a single message from the sequence manager, as specified by the message ID.
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dmsgid=OAE851ED131B3D6103A00000152F97E9
You can reprocess sequenced messages by using the hcfpsequencemanager
utility.
The syntax of this command is:
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dmsgid=message_id
Option | Description |
---|---|
-Dmode |
The mode in which to run the command. For this purpose, set this option to reprocess. |
-Dmsgid |
The message ID of a specific message to reprocess. When you use this option, you must only specify the mode and not the target or state. |
Example - Reprocessing a Message
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=reprocess -Dmsgid=32797717
There might be times when sequence message processing must be paused for a specific endpoint, such as when an external system fails. In this case, the endpoint can be paused until the system is restored. After the system is restored, you can resume processing for the endpoint.
The syntax of this command is:
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dendpoint=endpoint_name
Option | Description |
---|---|
-Dmode |
The mode in which to run the command. For this purpose, set this option to pause or resume. |
-Dendpoint |
The name (or IP address and port number) for the endpoint you want to pause. |
Example - Pausing an Endpoint
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=pause -Dendpoint=Pharmacy01
Example - Resuming an Endpoint
ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=resume -Dendpoint=Pharmacy01