Wednesday, 21 February 2018

Custom function in ICS to extend transformation capabilities

There is always the limitation in the product we use in the IT and all the product do not fill all the requirements. That is the reason we use custom options to extend the capability of products.

Same way ICS is restricted to provide some out of the box function. But if these inbuilt functions don't meet the expectation then we always try to explore some custom program to meet the requirement.

So, in the release of ICS 17.2.5 onwards, ICS has introduced the capability of importing and using custom functions. These functions are created using JavaScript and can be used in transformations, expressions and as an action in Orchestrations.

Let's go forward and see how can we achieve this with the help of a simple example.

For this blog, we have created a simple javascript function which is used to add two integer variable and return the sum of these two.

function sum(first,second)
    var third = first+second
    return third;

To use this function, we have to register this as a library using ICS. Let's save this file with name sum.js and save it to the desktop machine.

Login into the ICS and navigate to the Designer -> Libraries

Click on the Register button 

Register Library popup will get open, provide information and click on Create button
  • Select Library File(.js/.jar): Select the sum.js file
  • Name: Give any library name
  • Identifier: Would be picked up automatically based on the Name entered. However, we can change it
  • Version: Library version
  • Description: Enter description

Before we can use functions within integrations and transformations we need to configure all functions we want to use. For instance, ICS needs to know the input and output types of the JavaScript arguments and in which components we want to make the functions available. In the current version (17.1.3 Early uptake) functions can only be made available in orchestrations, but in the future, we will see the ability to also use functions in transformations using XPath and by adapters.

In this case, the library only has one function name sum which has two integer input arguments (first, second) and one integer output argument (third). When configuring the arguments we can select between three basic data types; boolean, number and string.

Configure the library as shown in the below screenshot  and click on Save button

See the library has been registered successfully

Now we are good to go to use this custom Library in the Orchestration integration.

Let's move forward and create a REST service. This REST service will accept two arguments and produces the JSON output with a single output parameter.

Drop a Trigger REST connection on the canvas and configure the wizard
  • Enter below information and Click Next
    • Name of the endpoint: SumTwoValues
    • Relative URI(must start with /): /sum
    • Select HTTP verb: GET
    • Select Add and review parameter for this endpoint
    • Select, Configure this endpoint to receive the response checkbox: This option allows us to assign response payload in the next step
  • Add two Query parameter(first, second) of integer type and click Next
  • Select JSON sample radio button, Click on inline link and provide payload

  • Drop Function Call activity between the REST adapter and mapper
  • Click on Function link
  • Select sum function
  • With the help of Expression builder, assign the query parameter(first, second) to the JS input variable
  • Edit the mapper and drag output_CallSumFun_third the variable and drop to sum variable
  • Activate the integration and hit REST service