Skip to Content

Intro

During development of scenarios with Quality of Service = Exactly Once In Order and involving polling sender adapter types (e.g. SFTP, File/FTP, JDBC, Mail, REST in polling mode), as well as some other adapter types (REST in push mode), it is required to set queue name / sequence ID dynamically, based on data contained in the processed message. Standard functionality of such adapters provides support for fixed queue name that is specified in configuration of a sender communication channel (which means, all messages processed by this communication channel, will be sequenced using a single queue / serialization context, which is often not acceptable / optimal), but it lacks functionality of setting queue name dynamically at runtime. In order to fulfil such described requirement, commonly used solution is to develop a custom adapter module. The approach is based on overwriting sequence ID of a processed XI message using standard API of Adapter Framework of Advanced Adapter Engine (refer to SAP JavaDocs for class com.sap.engine.interfaces.messaging.api.Message), and setting the required sequence ID (commonly, its value is based on value of some payload element that can be accessed using XPath). A custom adapter module has to be placed before the XI message reaches Messaging System (which translates to adding this custom module before standard adapter module CallSapAdapter is called in the module processing sequence of a communication channel).

 

In this blog, I’m not going to dive into details of this approach, since it has already been well described by other SCN community members in the past and examples of corresponding adapter modules have been provided and can be found on SCN – here are just few links and references to materials that have good outlook at this approach and its implementation:

 

Observation of many materials which describe this requirement and solution, and some degree of repeated development in this field undertaken by different teams, motivated me for writing this blog, which aim is to prepare an adapter module that is capable of fulfilling majority of requirements raised in the described area and collected from SCN blogs and forums, as well as those originating from projects I was involved in. Intention is to share with the community the adapter module that is generic enough to be re-used in various projects facing similar requirements, and enable reduction of repeated development efforts.

Adapter module configuration

Module name: Custom_AF_Modules/SetSequenceIdBean.

Below is a list of adapter module parameters. Note that only parameter used to specified XPath expression, is mandatory – all others are optional. Majority of optional parameters are used to further customize determined sequence ID and can be combined in order to achieve the required pattern of the determined sequence ID.

Parameter name Description Possible values Default value / behaviour Mandatory or optional
xpath XPath expression that shall extract required payload element’s value for dynamic sequence ID String value containing valid XPath Mandatory
error.terminate Terminate execution of the module if sequence ID cannot be set, causing also termination of further message processing by a channel. Not recommended to be disabled if dynamic sequence ID generation is a must Boolean or Boolean equivalents (case insensitive):

  • true, yes, 1 – to enable
  • false, no, 0 – to disable
true (enabled) Optional
multipleValues.error Terminate execution of the module if multiple distinct values were extracted from the message payload using specified XPath expression. If disabled, sequence ID is constructed based on the first extracted value. Not recommended to be disabled if unique sequence ID for every distinct object value per message is a must Boolean or Boolean equivalents (case insensitive):

  • true, yes, 1 – to enable
  • false, no, 0 – to disable
true (enabled) Optional
sequenceId.deleteLeadingCharacter Delete leading characters from the extracted value for the specified XPath expression Boolean or Boolean equivalents (case insensitive):

  • true, yes, 1 – to enable
  • false, no, 0 – to disable
false (disabled) Optional
sequenceId.leadingCharacter Leading character String value containing 1 character Optional
sequenceId.replaceInvalidCharacters Replace all invalid (not alphanumeric) characters from the constructed sequence ID with underscore symbol (‘_’) Boolean or Boolean equivalents (case insensitive):

  • true, yes, 1 – to enable
  • false, no, 0 – to disable
false (disabled) Optional
sequenceId.truncate Truncate constructed sequence ID so that its length does not exceed restrictions applicable for sequence ID (which is, 16 characters) – truncation can be either done to trim beginning of the value or its end. If the value retrieved using the specified XPath, is object identifier (e.g. customer number, sales order number, employee ID) that is iteratively increased for every subsequent instance of an object (e.g. sender system uses number range object for it), then truncation from start may be preferable, leaving a value part varying between closely following instances of objects Below values are accepted (case insensitive), all others are ignored:

  • start – to truncate beginning of the value
  • end – to truncate end of the value
(disabled) Optional
sequenceId.prefix Fixed prefix value for a constructed sequence ID, which will be delimited from remaining sequence ID value part with uderscore symbol (‘_’). Shall not normally contain many characters since it may negatively impact overall length of the constructed sequence ID – optimum is 2-3 characters. From perspective of impact on total sequence ID value length, it is not recommended to use prefix and suffix at the same time. Note that if truncation is enabled for start of the value, prefix may become truncated String value (disabled) Optional
sequenceId.suffix Fixed suffix value for a constructed sequence ID, which will be delimited from remaining sequence ID value part with uderscore symbol (‘_’). Shall not normally contain many characters since it may negatively impact overall length of the constructed sequence ID – optimum is 2-3 characters. From perspective of impact on total sequence ID value length, it is not recommended to use prefix and suffix at the same time. Note that if truncation is enabled for end of the value, suffix may become truncated String value (disabled) Optional

Usage

In all examples below, in the sender communication channel, Quality of Service = Exactly Once In Order was selected and queue name = ‘DEMO’ was provided:

Sender channel - QoS and default queue name.png

XPath expression is the only mandatory parameter for the developed adapter module – so let me start with the basic configuration involving only that parameter:

Module - basic configuration.png

Following payload of the incoming message, against which XPath is applied, is used in this example:

 


<test:GenericObjects xmlns:test='urn:doc.com/Test' xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'>
  <Object>
  <ID>00012345</ID>
  <Text>Test message</Text>
  </Object>
</test:GenericObjects>













 

As it can be seen, at runtime, the fixed sequence ID (‘DEMO’) was overwritten by the one determined based on the message payload (‘00012345’):

Module - basic configuration - result.png

Next example demonstrates combined usage of several additional parameters to fine tune sequence ID determination more precisely:

Module - advanced configuration.png

Following payload of the incoming message, against which XPath is applied, is used in this example:


<test:GenericObjects xmlns:test='urn:doc.com/Test' xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'>
  <Object>
  <ID>0000012345:test-obj</ID>
  <Text>Test message</Text>
  </Object>
</test:GenericObjects>




When executed at runtime, this leads to the following sequence ID determination and overwriting:

Module - advanced configuration - result.png

To give feeling of impact of various other module parameters, some more examples of determined sequence ID based on module parameterization and message payload, are given in the table below. Please note that for parameters expecting Boolean values, I used various acceptable values (true/false, True/False, yes/no, 1/0) in sake of demonstration of different possible alternatives to provide configuration for them – in scenarios, it is advisable to select consistent value alternatives and use them for all Boolean parameters configuration (e.g. only true or false, only yes or no, etc.) in order to make adapter module configuration more readable.

Module parameterization Incoming message payload Determined sequence ID / error Comments
(no module parameterization provided)

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

ModuleException: One or several required adapter module parameters are missing or incorrect Mandatory parameter ‘xpath’ is missing
error.terminate = 0

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

DEMO Mandatory parameter ‘xpath’ is missing, but termination on error is disabled, so channel default configuration (fixed queue name) is used
xpath = /GenericObjects/ID

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

ModuleException: Failure while attempting to set sequence ID Application of the specified XPath to message payload didn’t yield to extraction of any value
xpath = /GenericObjects/Object/ID

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

00012345
xpath = /GenericObjects/Object/ID

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00000000000000012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

ModuleException: Failure while attempting to set sequence ID Constructed sequence ID length is larger than acceptable limit (16 characters)

xpath = /GenericObjects/Object/ID

error.terminate = False

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00000000000000012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

DEMO Constructed sequence ID length is larger than acceptable limit (16 characters), but termination on error is disabled, so channel default configuration (fixed queue name) is used
xpath = /GenericObjects/Object/ID

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

  <Object>

    <ID>00098765</ID>

    <Text>Test message 2</Text>

  </Object>

</test:GenericObjects>

ModuleException: Failure while attempting to set sequence ID Multiple different (distinct) values were retrieved from the message’s payload using specified XPath

xpath = /GenericObjects/Object/ID

multipleValues.error = no

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

  <Object>

    <ID>00098765</ID>

    <Text>Test message 2</Text>

  </Object>

</test:GenericObjects>

00012345 Multiple different (distinct) values were retrieved from the message’s payload using specified XPath, but termination for such cases is disabled, so the first of those values was used when constructing sequence ID

xpath = /GenericObjects/Object/ID

sequenceId.deleteLeadingCharacter = true

sequenceId.leadingCharacter = 0

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

12345

xpath = /GenericObjects/Object/ID

sequenceId.deleteLeadingCharacter = true

sequenceId.leadingCharacter = 00

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

00012345 Leading characters were not deleted, because incorrect value was specified in parameter ‘sequenceId.leadingCharacter’ (multiple characters instead of an expected one leading character)

xpath = /GenericObjects/Object/ID

sequenceId.deleteLeadingCharacter = true

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

00012345 Leading characters were not deleted, because leading character was not specified was not specified (parameter ‘sequenceId.leadingCharacter’ missing)

xpath = /GenericObjects/Object/ID

sequenceId.truncate = start

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

00012345 Determined sequence ID value is already less than 16 characters long, so its truncation is not required and was skipped

xpath = /GenericObjects/Object/ID

sequenceId.truncate = end

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>TEST_OBJECT_123456789</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

TEST_OBJECT_1234

xpath = /GenericObjects/Object/ID

sequenceId.truncate = begin

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>TEST_OBJECT_123456789</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

ModuleException: Failure while attempting to set sequence ID Incorrect value specified for parameter ‘sequenceId.truncate’ (only ‘start’ and ‘end’ are valid values)

xpath = /GenericObjects/Object/ID

sequenceId.replaceInvalidCharacters = true

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>TEST%OBJECT-01</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

TEST_OBJECT_01

xpath = /GenericObjects/Object/ID

sequenceId.prefix = v

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

V_00012345

xpath = /GenericObjects/Object/ID

sequenceId.suffix = r2

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

00012345_R2

xpath = /GenericObjects/Object/ID

sequenceId.deleteLeadingCharacter = yes

sequenceId.leadingCharacter = 0

sequenceId.prefix = v

sequenceId.suffix = r2

sequenceId.truncate = start

<test:GenericObjects xmlns:test=’urn:doc.com/Test’ xmlns:soapenv=’http://schemas.xmlsoap.org/soap/envelope/‘>

  <Object>

    <ID>00012345_TEST_OBJECT</ID>

    <Text>Test message</Text>

  </Object>

</test:GenericObjects>

5_TEST_OBJECT_R2 Even though set initially, prefix, as well as part of the original value retrieved using XPath expression, are truncated, because truncation from start was enabled and constructed sequence ID value after deleting leading symbols and adding prefix and suffix turned to be longer than 16 characters

Source code and deployable

Source code of the adapter module and corresponding accompanying development artifacts are available at

GitHub repository for SetSequenceIdBean

 

Compiled and built latest version of the adapter module, assembled into deployable EAR file, is available at

Latest release of SetSequenceIdBean

 

The adapter module has been compiled in compliance to JDK 1.6, and has been successfully tested in PO 7.31 and PO 7.4 systems.

Outro

I will highly appreciate your feedback left in comments to this blog and encourage you sharing ideas about demanded, but yet missing functionality of this adapter module. This will help a lot on the way of enriching future versions of the module with new features based on your suggestions, and increasing module’s re-usability.

To report this post you need to login first.

9 Comments

You must be Logged on to comment or reply to a post.

  1. Brett Wells

    Hi Vadim,

    Excellent Blog. Exactly what I was looking for. Really easy to follow and understand. I have implemented this module in our Dev and Test environments and it is working brilliantly.

    Regards

    Brett

    (0) 
  2. Syed Farhaan Abdul Khader

    Dear Vadim,

     

    First of all thanks for your excellent blogs. It is very helpful.

     

    I tried to implement your code using NWDS and i get the below error:

    Multiple markers at this line
    – CHKJ2017E: This class must implement javax.ejb.SessionBean (EJB 2.0: 7.5.1,
    7.10.2).
    – CHKJ2050W: The ejbPassivate() method must exist (EJB 2.0: 7.5.1).
    – CHKJ2050W: The ejbCreate() method must exist (EJB 2.0: 7.8).
    – CHKJ2050W: The ejbRemove() method must exist (EJB 2.0: 4.2.2, 7.5.1).

     

    Can you advise me on what I am doing wrong?

     

    Thanks in advance.

    (0) 
    1. Vadim Klimov Post author

      Hi Syed,

      Markers that you provided look to me as those produced by Java EE Validator functionality in Eclipse. I can see from them, that validation was executed against EJB 2.0 standard, where it was mandatory for session beans to implement interface SessionBean (as highlighted in error marker in your listing), as well as provide appropriate implementation of several bean lifecycle methods of that interface (as highlighted in warning markers). In more recent revisions of EJB specification (3.x), implementation of interface SessionBean is not mandatory anymore, it was changed to optional and can be replaced by functionality achievable via dependency injection mechanisms and callback methods. When developing this adapter module, I followed EJB 3.0 specification and didn’t use implicit implementation of the interface SessionBean, which, as mentioned earlier, is compliant with EJB 3.x (and shall not produce errors if you validate the project against that EJB release standards), but is a compliance issue for EJB 2.0 (and results into errors that you observe). Latest releases of SAP NetWeaver Application Server Java (such as 7.3x, 7.4, 7.5) are fully compliant with Java EE 5 standards, hence, are compatible with EJB 3.0.

      Regards,

      Vadim

      (0) 
      1. Syed Farhaan Abdul Khader

        Dear Vadim,

         

        Thanks a lot for your reply. I was able to deploy the EAR successfully.

         

        I am facing different issues now though, my scenarios is JDBC to Proxy with a 1:n mapping and my objective is to send the messages with different queue names(based on payload) to ECC.

         

        First of all, if there are more than one record matching the select statement in JDBC Sender Channel, the messages is failing in the channel.

         

        Secondly, even if I pick just one record using SELECT TOP(1)  how do I UPDATE just that one record so that the other record gets picked next time.

         

        Also, since it is a 1:n mapping, PI is creating two messages.

        First from DB to PI with the Queue Name from the payload and the Second one from PI to ECC with a different queue name like SUBSEQ_0322 and the message is received in ECC with this Queue Name whereas i want the message to be received in ECC with the Queue Name created from Payload.

        I hope you can advise me on these problems.

        Thanks again.

        Syed Farhaan Abdul Khader

        (0) 
        1. Vadim Klimov Post author

          Hi Syed,

          In the adapter module, the default logic implies raising an error if the XPath expression you specify for looking for sequence ID, yields to several different values. This has been done with intention: since sequence ID can only be a single value (and not an array), and it is very unlikely multiple discrete values that are found, can be safely concatenated (due to length restriction of the sequence ID), it might be confusing if the sequence ID is set following the first found value, and will be assigned to messages that potentially contain different object values for the attribute used for sequence ID. This can be changed via adapter module parameter ‘multipleValues.error’, by setting its value to ‘false’. In latter case, should the module find multiple different values for sequence ID, it will use the first of them.

          Message split and assignment of the newly determined sequence ID is done by means of standard pipeline step of Messaging System, which takes place already after sender adapter (and the described custom adapter module) execution – hence, it is not possible to control setting of sequence ID for this kind of scenarios (for split messages) from within the adapter module configured in the sender channel. To be more precise, in message split scenarios with QoS = EOIO, child messages are assigned sequence ID following pattern ‘SUBSEQ_<4 digit random number>’. For some adapters, SAP introduced enhancement that allows restoring the original sequence ID (of a parent message) and setting it in the delivered message. In particular, this is for example available in IDoc adapter and SOAP adapter with XI protocol / proxy (which makes it relevant for your scenario, too) – please check SAP Note 2125230 for more details about this configuration for SOAP-XI by means of adapter module parameter ‘XI.restoreParentQueueId’.

          Regards,

          Vadim

          (0) 

Leave a Reply