X

The Integration blog covers the latest in product updates, best practices, customer stories, and more.

  • September 18, 2018

Using a Library in OIC

Introduction

A library is a file or a collection of multiple files bundled in a JAR that contain Javascript functions. Library is used within an integration and is executed by a Javascript engine on the server as part of an integration flow.

This document describes the following:

  1. Requirements that a Javascript function needs to meet to be used within integration.
  2. How to create Javascript file or collection of Javascript files that are suitable to be used in creating a Library.  

1. Javascript function requirements

Following are the requirements based on which Javascript function should be written so that it can be registered and works correctly in OIC.

1.1 Function return values should be named

Consider this example

function add ( param1, param2 ) {
  return param1 + param2;
}

Even though the above example is a perfectly valid Javascript function it can't be registered as a library in OIC because without a named return value the library metadata editor is unable to identify parameters returned by this function so that it could be used in mapper for mapping downstream activities in an integration.

OIC requires you to change the above function and name the return parameter like this example.

function add ( param1, param2 ) {
  var retValue = param1 + param2;
  return retValue;
}

In this case the return parameter is named retValue. This change will let the user map the return parameter to a downstream activity.

1.2 Inner functions

If your Javascript function defines another function within it, the inner function will not be identified by the library metadata editor in OIC so no metadata will be created for the inner function. When metadata is not created for a function it can't be used in OIC. However, the inner function can be used within the outer function.

function parseDate(d) {
 function foo(d) {
    if(typeof d === 'string') { 
       return Date.parse(d.replace(/-/g,'/')); 
    }
    if(!(d instanceof Array)) { 
       throw new Error("parseDate: parameter must be arrays of strings"); 
    }
    var ret = [],k;
    for(k=0;k<d.length;k++) { 
       ret[k] = foo(d[k]); 
    }
    return ret;
 }
 var retVal = foo(d);
 return retVal;
}

In the above example, foo() is defined within function parseDate(). So the metadata UI editor ignores foo() and you will be able to configure only the outer function parseDate(). However, foo() is used within parseDate() which is perfectly valid.

1.3 Long running functions

Javascript function execution should not exceed 1500ms. If a function execution including it's dependencies exceeds this time limit the process is automatically killed by the server; log messages will indicate the flow was killed because it exceeded 1500ms.

1.4 Input parameter types

OIC currently has support for String, Number, Boolean input and return value types. If your Javascript function uses a different object type like an Array or a Date type the incoming parameter which would be either of the supported types will have to converted to the type that the function expects. Here is an example of how an input of type Array should be handled.

1.4.1 Array Input Type

Consider the following array processor example

function myArrayProcessor(myArray) {
 var status = 'FAILED';
 for (i=0; i<myArray.length; i++) {
 
 }
 return status;
}

Because the supported parameter types don't include an Array type this code will have to be changed as in the following example

function myArrayProcessor(myArray) {
 var status = 'FAILED';
 var data = myArray.replace(/'/g, '"');
 myArray = JSON.parse(data);
 for (i=0; i<myArray.length; i++) {
 
 }
 return status;
}

While configuring metadata for this function mark the input type as String and while using the function in an integration the incoming string will be parsed and converted to Array within the function.

2. Creating library using a Javascript file or multiple files

2.1 Using single Javascript file

Creating a library using single Javascript file is straight forward. All dependency are contained within the single file. If a function depends on another function the dependent function should be present within the same file. When you register the library it would be enough to configure metadata only for the function that needs to be used within integration. Other functions if present to satisfy dependency need not be configured.

Consider the following interdependent Javascript function example

function funcOne(param1) {
 return param1;
}
function funcTwo(param2){
 return param2
}
function myFunc(param1, param2) {
 var ret = funcOne(param1) + funcTwo(param2);
 return ret;
}

In this example, funcOne() and funcTwo() are used by myFunc(). While configuring metadata for this library it is enough to configure myFunc() function so that it could be used within integration.

2.2 Using multiple Javascript files

A library can be created based on multiple Javascript files. When multiple files are involved you should bundle all files into a JAR file and register the JAR file as a library.

For an example consider an EncodeAndDecode library where-in encoding and decoding is done using a Base64 encode and decode scheme. 

The library consist of two files Base64.js which contains the Base64 encode and decode logic and Encrypt.js which contains wrapper function that depends on functions within Base64.js. The encode and decode wrapper functions are used within integrations. Both the files are contained within a JAR file and the library is created with this JAR.

To use the library configure metadata for encode and decode functions within Encrypt.js as shown in the image above.

3. Debugging Javascript in a library

Over time it may be possible the Javascript library grows in size and complexity. Usually debugging a Javascript library is to test Javascript in a browser and once found working satisfactorily roll the code as a library. This may not always work because browsers are regularly updated with newer execution engines that support latest Javascript version and in general browser engines are more liberal in terms of ignoring many code errors; Javascript engine within OIC is stricter.

To debug Javascript code use an instance of CXConsole() like in the sample code below.

function add ( param1, param2 ) {
 var console = new CXConsole();
 var retValue = param1 + param2;
 console.log("# retValue: ", retValue);
 console.warn("# retValue: ", retValue);
 return retValue;
}

The log messages written by the above code goes into server-diagnostic.log file.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha
Oracle

Integrated Cloud Applications & Platform Services