Some tips and tricks for adapter modules lifecycle management

Recently I was involved in migrating lot of adapter modules from a PI 7.0 system to a PI 7.4 environment. Creating a custom adapter module is not too complicated but like anything else, we need to be clear of all the components involved and their implications. There is a very good SDN document about the steps to create one. However, in my experience keeping the following points i makes the development process much smoother.

1. Understanding the descriptor files:

Most of the issues with adapter modules occur as one of the descriptors is wrong. Let’s go through them.

a) ejb-j2ee-engine.xml: This file will be in the EJB project. This links the EJB name with the JNDI name. Hence, if you are getting a module not found error, most likely you need to check your jndi-name.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”no”?>

<ejb-j2ee-engine

  xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

  xsi:noNamespaceSchemaLocation=”ejb-j2ee-engine.xsd”>

  <enterprise-beans>

  <enterprise-bean>

  <ejb-name>ToUpperCase</ejb-name>

  <jndi-name>ToUpperCase</jndi-name>

  </enterprise-bean>

  </enterprise-beans>

</ejb-j2ee-engine>

b) ejb-jar.xml : This is in the EJB project as well . This has the actual class name, EJB interface names, bean type etc. The key thing here is to check the ejb-name and the class name. The home,local, remote and local-home names always stay the same.( to standard SAP values ). This causes a lot of errors as normally people just accept the default provided names for these interfaces and it causes errors.

c) application-j2ee-engine.xml : This file is in the EAR project and stays the same, unless the project needs additional libraries.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”no”?>

<application-j2ee-engine

  xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

  xsi:noNamespaceSchemaLocation=”application-j2ee-engine.xsd”>

  <reference

  reference-type=”hard”>

  <reference-target

  provider-name=”sap.com”

  target-type=”service”>engine.security.facade</reference-target>

  </reference>

  <reference

  reference-type=”hard”>

  <reference-target

  provider-name=”sap.com”

  target-type=”library”>engine.j2ee14.facade</reference-target>

  </reference>

  <reference

  reference-type=”hard”>

  <reference-target

  provider-name=”sap.com”

  target-type=”service”>com.sap.aii.af.svc.facade</reference-target>

  </reference>

  <reference

  reference-type=”hard”>

  <reference-target

  provider-name=”sap.com”

  target-type=”interface”>com.sap.aii.af.ifc.facade</reference-target>

  </reference>

  <reference

  reference-type=”hard”>

  <reference-target

  provider-name=”sap.com”

  target-type=”library”>com.sap.aii.af.lib.facade</reference-target>

  </reference>

  <reference

  reference-type=”hard”>

  <reference-target

  provider-name=”sap.com”

  target-type=”library”>com.sap.base.technology.facade</reference-target>

  </reference>

  <provider-name>sap.com</provider-name>

  <fail-over-enable

  mode=”disable”

  xsi:type=”fail-over-enableType_disable”/>

</application-j2ee-engine>

This file has references of libraries etc. when the application is running. A good way to check that the references are correct is by going to Java Class Loader on the application server and give the component name.

In the below screen-shot we’re able to fins component type “service” with name “engine.security.facade” as updated in application-j2ee-engine.xml .

Addiing additional references:  If we’re using additional libraries, we need to update the reference in the below way.

– Add the client libraries to allow compilation. Many of the libraries are already available in NWDS plugins ( e.g. JCO 2/3 libraries ). However, in some cases they will need to be obtained from SAP PI application server.

– Refer Javadoc to understand the DC that contains the class. Taking interface ApplicationPropertiesAccess as an example. Javadoc at

http://help.sap.com/javadocs/NW73/SPS05/CE/en/com.sap.en/com/sap/engine/services/configuration/appconfiguration/ApplicationPropertiesAccess.html

gives the DC as:

[sap.com] tc/je/appconfiguration/api

Hence, the deployment descriptor will need to be updated as:

<reference reference-type=“hard”>

    <reference-target provider-name=“sap.com”

target-type=“service“>

      tc~je~appconfiguration~api

    </reference-target>

</reference>

2. Renaming adapter module name: We need to update a module name many a times. Some of the reasons could be:

– While testing, we gave a “test” name and want to change the module name without rewriting the whole project.

– Create a new version and test it out in some scenarios before changing configuration everywhere.

The adapter module name that we configure in adapter modules is actually the JNDI name in ejb-j2ee-engine.xml. So initially the ejb and jndi names were the same.

In the below screenshot, I changed the JNDI name to Convert2Up

After making only the JNDI name, I sent a test message after updating the adapter module config parameters and it works fine.

3. Adding software component information: The adapter module can be deployed directly from NWDS by running the EAR project on the application server. However, it is better to organise custom software components like SAP delivered software components in its own namespace so that it’s easier to track the inventory and get all the benefits of application lifecycle management.

Without the software component information, we can verify the bean is successfully deployed by checking JNDI browser.

However, if there are multiple beans, we need to know their names.  It’s better to organise in their own namespace. We need to go through the below process : EAR –> SDA –> SCA

The steps required are :

– Convert EAR to SDA file ( which is EAR file along with SAP specific manifest info in SAP_MANIFEST.MF file )

– Add SDA file to a SCA file along with the software component information

The easiest approach is to use nwpacktool . Update the batch file with JAVA_HOME and NWPACKTOOLLIB.

Then lanuch the batch ( or .sh ) file. As an example, to create a SDA file from the EAR.

Now, add component information and create a SCA file.

Now, deploy the SCA file .  We can display all custom modules created under the same component.In the below screen-shot, two beans are deployed under SC “AdaptModules” with the first bean having version 3.

,

It’s easier to deploy to any system as well since there is only one SCA file to be updated .

4. Retrieving old version of an adapter module.

If deployed via SDM, it will be in the path – /usr/sap/<SID>/<server>/SDM/root/origin/sap.com/<EAR_Name>/localhost/<number>