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

{

                "sum":1

}

• 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

File Upload Process in Integration Cloud Services REST API

File upload is a very common aspect of each and every technology we used in our day to day projects as part of the REST service. This is very common requirement to upload a file that resides in the local computer and send it to the remote computer.

Sometimes we need to expose a REST service which should allow to upload files, process the data and store it some repository like a database, FTP etc..

In this blog, we are going to show how to use ICS REST adapter feature to upload a file and save the file as it is on some FTP location.

Below are the steps to achieve the use case:

• Create REST Adapter as Trigger
• Create FTP Adapter as Invoke
• Create Orchestration Integration
• TEST the Integration

Create REST Adapter as Trigger

There is one dedicated blog that explains, how to configure REST Adapter in Oracle ICS. Please have a look at the blog

Create FTP Adapter as Invoke

This has also been explained in another blog that shows, how to configure FTP Adapter in Oracle ICS. Please have a look at the blog

Create an Orchestration Integration

Create an Orchestrated Integration using steps:

• Login into ICS console
• Click on the Integration tile from ICS home page
• Click on Create button from upper right corner
• Select Orchestration pattern from the dialog box
• Enter Below information and click on Create button
• Select Application event or business object radio button
• Enter Integration Name in What do you want to call your integration text box
• An Identifier would be picked up automatically from Integration name, however, we can edit it
• Let the Version as it is
• Enter the description in What does this integration do input box
• Leave the package input box as it is

• Drag the TEST_REST_Conn Connection on the canvas from REST connection

• Enter below information and Click Next
• Name of the endpoint
• Relative URI(must start with /)
• Select HTTP verb as POST
• Select Configure a request payload for this endpoint checkbox- This option allows us to assign payload in the next step

• Select Accept attachments from request and Request in HTML form checkboxes then click Next and Done button

• Drag & Drop the FTP connection on the canvas

• Enter the Name in What do you want to call the endpoint input box and click Next button
• Enter below information and click Next button
• Select Operation: Select Write File
• Select a Transfer Mode: Choose ASCII
• Specify an Output directory: Enter the directory where you want to save the uploaded file
• Specify a File Name Pattern: Enter the file name

• Choose No under the Do you want to define a schema for this endpoint and click Next -> Done button

• Edit the mapper and map the below
• execute -> attachments -> attachment -> attachmentReference to ICSfile -> FileReference
• partName -> fileName

partName element would contain the file name that will be uploaded

That configuration completes the integration.

Let's test the integration using POSTMAN tool:

Check the FTP location output directory that has been given during configuring FTP adapter.

Integration to Publish Messages to Oracle Integration Cloud Service

Oracle ICS allows us Out Of The Box messaging Queue which can be use to send messages. This is one of the most useful feature of Oracle ICS.

We can create integrations that enable us to publish message to Oracle Integration Cloud Service. Messaging publishing can be achieved through the use of Oracle Integration Cloud Service Messaging.

Oracle ICS provides Publish To ICS Style/Pattern that allows us to create an integration to send message to ICS inbuilt queue without setup any messaging service.

Let's go step by step on how to create such type of an integration.

• Login into ICS console and Click on Integration tile from the home page
• Click on Create button from upper right corner and select Publish To ICS Style/Pattern

• Enter information on the opened dialog box and click Create button

• In the integration designer, drag an adapter from the Connections panel on the right to the trigger (source) area of the canvas. In this example we are dropping REST connection that we created in out previous blog

• Enter below information and Click Next
• Name of the end point
• Relative URI(must start with /)
• Select HTTP verb
• Select Configure a request payload for this endpoint checkbox- This option allows us to assign payload in the next step

• Select Json Sample Radio button: This option allows us to take input in json format. Select inline link to give sample payload

• Enter sample payload and click OK

{  
   "employeeId":"ABC@123",
   "firstName":"Ankur",
   "lastName":"Jain",
   "Qualification":"MCA",
   "Designation":"Sr. Manager"
}

• Click Next and Done button

• After above steps our integration will look like

• Click on Action button and then Tracking option. This option allows us to track our integration with Business identifier.

• Drag employeeId from left pane and drop on the first row in Tracking Field column. Select Done button

• Select Save and Close button from upper right corner

Now integration is completed and it's time to activate the integration.

• Select on the Activate button from integration screen

• Select Enable Tracking & Include Payload check boxes and click Activate button

If everything goes fine, integration will be activated successfully.

That ways we have developed an integration that will publish a message on ICS queue. Now we can have one or more subscriber that will subscribe the above integration to consume the messages.

Let's see my next blog that will subscribe the above integration and consume the messages.

Integration on ICS to expose REST service

This blog is very useful for those who is keen to know, how to create REST services in ICS. This is very straight forward.

After this blog you have learned to how to develop REST service in ICS.

Use Case: Develop REST service that exposes the below json and inserts the same in Oracle DB table.

{  
   "employeeId":"ABC@123",
   "firstName":"Ankur",
   "lastName":"Jain",
   "Qualification":"MCA",
   "Designation":"Sr. Manager"
}

This Use case requires only simple 4 steps to complete:

1. Create REST connection
2. Create DB connection
3. Create an Integration
4. Activate the Integration

Let's go step by step

1. Create REST connection: The REST connection we are gonna to create will work as a Trigger point. We have already showcased the same in one of my blog. Please check it out before moving forward.
2. Create DB connection: DB connection will work as a Target point. We have already showcased the same in one of my blog. Please check it out before moving forward.
3. Create an Integration: Follow below steps to create an Integration

• Login into ICS console
• Click on the Integration tile from ICS home page

• Click on Create button from upper right corner
• Select Orchestration pattern from the dialog box

• Enter Below information and click on Create button
• Select Application event or business object radio button
• Enter Integration Name in What do you want to call your integration text box
• An Identifier would be picked up automatically from Integration name however you can edit it
• Let the Version as it is
• Enter the description in What does this integration do box
• Leave the package box as it is

• Integration pane will look like

• Drag the TEST_REST_Conn Connection on the canvas from REST connection

• Enter below information and Click Next
• Name of the end point
• Relative URI(must start with /)
• Select HTTP verb
• Select Configure a request payload for this endpoint checkbox- This option allows us to assign payload in the next step

• Select Json Sample Radio button: This option allows us to take input in json format. Select inline link to give sample payload

• Enter payload and click OK

• Click Next and Done button

• Click Invokes from right navigation, Select Oracle Databases, drag and drop the TEST_DB_Conn below PostEmployee

• Enter below information and Click Next
• Enter endpoint name in What do you want to call your endpoint
• Select Run a SQL Statement from What operation do you want to perform drop down

• Enter below insert query in SQL query box and Click Validate SQL query to validate the entered query and Click Next button

INSERT INTO apps.employee_info(employee_id, first_name,last_name,qualificatoin,designation) values(#employee_id,#first_name,#last_name,#qualification,#designation)

• Click Done
• Click on Map to InsertEmployee mapper and click Edit button

• Map the source and target field as shown in the below scree shot. Click Validate and Close button

• Select Action icon and click on Tracking. This is mandatory step and can’t activate integration without this step. Basically this allows us to track the Instance with configured parameter. In our case we will select employeeId field.

• Drag & Drop the employeeId from left panel to first row in Tracking Field and click Done button

• Click Save and Close button from upper right corner

Now our integration is completed and now turn to activate the integration.

      4. Activate Integration

• Click on Activate button

• Select Enable tracking and Include payload check boxes button. This option is useful if we want to see payload in the logs. Click Activate button

• As soon as, integration will be activated, ICS will show you the service end point on the upper side as shown in the below screen shot. Alternatively, you can click on the info icon near to the activate button that will show you the service end point.

This is the time to test the service and see the data in database table. We will use POSTMAN tool to test the REST service

      5. Test the REST service

• Open postman tool
• Enter service end point
• We have to add Basic Auth as ICS service is automatically secured. We need to provide ICS console credentials.

• Enter payload and hit Submit button

• Open database and see record should be inserted into the database

That's done !