How to Create User-Defined Function for Message Mapping Using NWDS

With the release of PI 7.31, the NWDS tool is becoming robust enough to replace the Swing tools used in the Enterprise Service Repository (ESR) and the Integration Directory (ID).  One of the main focuses in PI, with each new SP release, is on improving the NWDS tools.

In developing an integration scenario, we may spend as much as 80-90% of our time in the development of mapping/transformation.  The Swing tool provides us with Message Mapping, which also includes a graphical tool for us to create user-defined function (UDF).  UDF is very important to the development of mapping programs.  It is impossible to expect the default Message Mapping tool to meet 100% of our mapping requirements.  As a result, UDF is there to help us fill the gaps of the special mapping needs which cannot be met with the default tool.

The ability to create UDF is available with the NWDS tool beginning in PI 7.31 SP4.  But, there has been a lack of documentation of how to create an UDF.  So, in this blog I will provide the steps on how to create UDF in NWDS.  In addition, I will use the GUI mapping tool in NWDS to demonstrate it.  This GUI mapping tool is going to be available in PI 7.31 SP6, which is scheduled for release in the beginning of 2013.

With NWDS, UDF must be created in a Function Library.  In our mapping program we can specify the function library(s) we want to use.  Then, the UDFs created in the Function Library will be available to us during mapping.

One big advantage of using NWDS to create UDF is the availability of the Java development environment, e.g. syntax checking, auto-display of methods in a class, etc.  I think these features have been frequently requested for the Swing tool.

In this blog, I am assuming the reader is already familiar with using NWDS with ESR.  If not, please reference the blog: Eclipse Tool for ESR in NW PI

To use as an example for this blog, I am going to write a simple UDF to extract the nth element of a comma-delimited string.  For example, for the string “element1,element2, element3”, the 1st element is “element1”, the 2nd is “element2”, the 3rd element is “element3”.

Steps to create and use an UDF:

1. Create a function library.
2. Create UDF in the function library.
3. In the mapping design, assign function library to the mapping.
4. Design the mapping using the UDF.

Details of the steps:

1. Create a function library:  (or select an existing one)
   1. Right-click on “Function Libraries” and select “New Function Library”.
      
   2. Enter a name for the function library.
      
      (You may need to create or use an existing change list during this step.)
2. Create UDF in the function library:
   1. Double-click on the function library name or right-click on the function library name and select:  “Open With” –> “Function Library Editor”
      
   2. Click on “Edit” in the Function Library Overview:
      
   3. Create a new method in the class.  In this step, we have to create the signature for the method.  In the Swing tool, this is done for us automatically.  But, in java, we have to do this manually.  It is possible, in the future, this will also be done automatically.

      The code for the method is below.  Please note:

      (you will need to make the appropriate changes to your own UDF based on the above information)

      You may need to resolve the undefined references by importing the following:
      import com.sap.ide.esr.tools.mapping.core.Argument;
      import com.sap.ide.esr.tools.mapping.core.ExecutionType;
      import com.sap.ide.esr.tools.mapping.core.LibraryMethod;

      Java code for the method “getElement”:
      @LibraryMethod(title=”getElement“, description=””, category=”MyUDF“, type=ExecutionType.SINGLE_VALUE)
      public String getElement (
          @Argument(title=””)  String num,
          @Argument(title=””)  String source,
          Container container)  throws StreamTransformationException{
              String delimiter = “,”;
              int n = Integer.valueOf(num).intValue();
              String[] temp;
              temp = source.split(delimiter);
              if (n > temp.length)
                  return “ERROR”;
              return temp[n-1];
      }
      

      Sample screenshot:
      
      Save and close the “MyUDF.java” tab.

      • the name of the method is “getElement”
      • there are 2 parameters:  “num” and “source”
      • the function library name is:  MyUDF
   4. In the MyUDF Function Library Overview, you should see the new method:
      
3. Create a Message Mapping and assign the UDF to the Message Mapping:
   1. Create a new Message Mapping and assign the Message Types.
      Assign the UDF to the mapping by click on the “Dependencies” tab and add the function library:
      1. Click on the “Dependencies” tab.
      2. Select “Function Libraries”.
      3. Click on “Add”.

   2. Select the UDF and click “OK”.
      

      The UDF should now show up under “Function Libraries”.
      

4. Use the UDF in Message Mapping:
   Click on the “Definition” tab and use the GUI mapping tool to develop the mapping and use the UDF.  This tool is virtually identical to the one in the Swing tool.

   (Please note on the right-hand side, the “MyUDF” with the method “getElement” is now available for mapping.)
   
   The constant for fld_1 = 1  (to get the 1st element)
   The constant for fld_2 = 2  (to get the 2nd element)

5. Test the mapping.  Please reference the blog below on how to test Message Mapping:
   How to Test Message Mapping Using the Eclipse Tool (NWDS)

   Input:
   

   Output:
   

From my perspective, I still have the following questions.  Once I find the answers, I will update this blog:

1. How to create an UDF without having to manually enter the reference and signature for the method, as described in step 2.c?  (Will there be a “create” like in the Swing tool?)
2. Since we are in the Java development environment, will there be a way for me to test the UDF by itself?