C Managing Message Sequencing

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:

C.1 Overview of Sequenced Message Management

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 needs to 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 needed 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 Section 8.5, "Working with Sequenced Messages" for more details.

C.2 Java Methods for Managing Sequenced Messages

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 Section C.3.1, "Prerequisites for Running Command-Line Tools."

C.2.1 Listing Endpoints With States

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

C.2.2 Listing Pending Sequenced Messages

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:

seqUtil.getSequenceMessagesByTargetAndState("TCP://111.34.121.22:2025","STACKED")

state

The state of the messages to include in the report. Specify one of the following states:

  • PROCESSED: Message processing is complete and is pending for delivery.

  • STACKED: An error has occurred preventing the message from processing.

  • PAUSED: The endpoint is paused.


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:

  • PROCESSED: Message processing is complete and is pending for delivery.

  • STACKED: An error has occurred preventing the message from processing.

  • PAUSED: The endpoint is paused.


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.


C.2.3 Discarding 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:

  • PROCESSED: Message processing is complete and is pending for delivery.

  • STACKED: An error has occurred preventing the message from processing.

  • PAUSED: The endpoint is paused.

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:

  • PROCESSED: Message processing is complete and is pending for delivery.

  • STACKED: An error has occurred preventing the message from processing.

  • PAUSED: The endpoint is paused.


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.


C.2.4 Reprocessing a 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.


C.2.5 Pausing and Resuming and Endpoint

There may be times when sequence message processing needs to 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. Once 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.


C.3 Command-Line Tools for Managing Sequenced Messages

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.

C.3.1 Prerequisites for Running Command-Line Tools

Before you can run the command-line tools, you need to make sure your environment is configured correctly. Do the following before running any commands:

  1. Set the ORACLE_HOME, ANT_HOME, and JAVA_HOME environment variables.

    ORACLE_HOME is your Oracle Fusion Middleware installation directory. For example:

    set ORACLE_HOME=C:\oracle\Middleware
    set ANT_HOME=%ORACLE_HOME%\modules\org.apache.ant_1.7.1 
    set JAVA_HOME=%ORACLE_HOME%\jdk160_18 
    
  2. Create the jndi.properties file.

    cd $ORACLE_HOME\Oracle_SOA\bin
    ant -f ant-hcfp-util.xml b2bcreate-prop
    
  3. Edit the jndi.properties file to include the weblogic password.

Notes:

  • 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
    

C.3.2 Listing Endpoints With States

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.


C.3.3 Listing Pending Sequenced Messages

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:

  • PROCESSED: Message processing is complete and is pending for delivery.

  • STACKED: An error has occurred preventing the message from processing.

  • PAUSED: The endpoint is paused.

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 C-1 Listing Sequenced Messages Based on State and Endpoint

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dstate=STACKED -Dendpoint=Pharmacy01

Example C-2 Listing Sequenced Messages Based on State Only

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dstate=PROCESSED

Example C-3 Listing Sequenced Messages Based on Endpoint Only

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dendpoint=Pharmacy01

C.3.4 Discarding Messages

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:

  • PROCESSED: Message processing is complete and is pending for delivery.

  • STACKED: An error has occurred preventing the message from processing.

  • PAUSED: The endpoint is paused.

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 only need to specify the mode and not the target or state.


Example C-4 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 C-5 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 C-6 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 C-7 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 C-8 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

C.3.5 Reprocessing Messages

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 only need to specify the mode and not the target or state.


Example C-9 Reprocessing a Message

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=reprocess -Dmsgid=32797717

C.3.6 Pausing and Resuming an Endpoint

There may be times when sequence message processing needs to 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. Once 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 C-10 Pausing an Endpoint

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=pause -Dendpoint=Pharmacy01

Example C-11 Resuming an Endpoint

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=resume -Dendpoint=Pharmacy01