OIC on DecipherMiddleware

Tips and Tricks for handling numbers in BPEL or OIC

Sat, 28 Aug 2021 17:52:00 +0000

While integrating with multiple systems and moving data from one system to the other, we generally come across scenarios, wherein we need to change the format of the number or perform operations like floor, ceil, round, divide, multiply, add, etc. on numbers. We will be going through various mathematical functions available in XSLT 1.0, which would be helpful in such scenarios, and also some generic errors which we encounter usually.

Mathematical Operations

Divide
Multiply
Add
Subtract
Square-root
Round
Floor
Ceil
Advanced Number formatting

Common Errors

Mathematical Operations 🔗

1. Divide 🔗

To divide 2 numbers, we can use the div operator to divide two numbers.

Syntax:

$num1 div $num2

Example:

Let us assume we want to divide 120 by 7.

XSL:

<divide><xsl:value-of select="120 div 7"/></divide>

Output

<divide>17.14285714285714285714</divide>

2. Multiply 🔗

To multiply 2 numbers, we can use the * operator.

Syntax:

$num1 * $num2

Example:

Let us assume we want to multiply 120 by 7.

XSL:

<multiply><xsl:value-of select="120 * 7"/></multiply>

Output

<multiply>840</multiply>

3. Add 🔗

To add 2 numbers, we can use the + operator.

Syntax:

$num1 + $num2

Example:

Let us assume we want to add 120 and 7.

XSL:

<add><xsl:value-of select="120 + 7"/></add>

Output

<add>127</add>

4. Subtract 🔗

To subtract one number from another, we can use the - operator.

Syntax:

$num1 - $num2

Example:

Let us assume we want to subtract 7 from 120.

XSL:

<subtract><xsl:value-of select="120 - 7"/></subtract>

Output

<subtract>113</subtract>

5. Square Root 🔗

To find a square root of a number, we can use the oraext:square-root function.

Syntax:

oraext:square-root($number)

Example:

Let us assume we want to find a square root of 121.

XSL:

<square-root><xsl:value-of select="oraext:square-root(121)"/></square-root>

Output

<square-root>11</square-root>

6. Round 🔗

To round a number to the nearest integer we can use the round($number) function available in XSLT.

Syntax:

round($number)

XSL:

<roundInt><xsl:value-of select="round(17.64285714285714285714)"/></roundInt>

Output

<roundInt>18</roundInt>

What if we want to round the number to 2 or 3 decimal places. Since the round function only takes one argument, we cannot pass the number of decimal digits we want to round the number to. To do so we can try the below-mentioned method.

We can multiply the number by 10m, round the number, and then divide the result by 10m. Here, m denotes the number of decimal places.

Pseudo Code:

(round($number * 10 m) )/ 10 m

Example

Let us assume we want to round to two decimal places. Here, the value of m will be 2. 10m will be equal to 100.

XSL:

<roundDec1><xsl:value-of select="round(17.64285714285714285714 * 100 ) div 100"/></roundDec1>

Output

<roundDec1>17.64</roundDec1>

7. Floor 🔗

To return the largest integer less than or equal to the number we can use the floor($number) function available in XSLT.

Syntax:

floor($number)

XSL:

<floorInt><xsl:value-of select="floor(17.64285714285714285714)"/></floorInt>

Output

<floorInt>17</floorInt>

What if we want to perform floor operation on the number and have output with 2 or 3 decimal places. Since the floor function only takes one argument, we cannot pass the number of decimal digits we want to floor the number to. To do so we can try the below-mentioned method.

We can multiply the number by 10m, floor the number, and then divide the result by 10m. Here, m denotes the number of decimal places.

Pseudo Code:

(floor($number * 10 m) )/ 10 m

Example

Let us assume we want to floor the number to three decimal places. Here, the value of m will be 3. 10m will be equal to 1000.

XSL:

<floorDec1><xsl:value-of select="floor(17.64285714285714285714 * 1000 ) div 1000"/></floorDec1>

Output

<floorDec1>17.642</floorDec1>

8. Ceil 🔗

To return the largest integer greater than or equal to the number we can use the ceiling($number) function available in XSLT.

Syntax:

ceiling($number)

XSL:

<ceilInt><xsl:value-of select="ceiling(17.14285714285714285714)"/></ceilInt>

Output

<ceilInt>18</ceilInt>

What if we want to perform ceiling operation on the number and have output with 2 or 3 decimal places. Since the ceiling function only takes one argument, we cannot pass the number of decimal digits we want to ceil the number to. To do so we can try the below-mentioned method.

We can multiply the number by 10m, ceiling the number, and then divide the result by 10m. Here, m denotes the number of decimal places.

Pseudo Code:

(ceiling($number * 10 m) )/ 10 m

Example

Let us assume we want to ceiling the number to three decimal places. Here, the value of m will be 3. 10m will be equal to 1000.

XSL:

<ceilDec1><xsl:value-of select="ceiling(17.14285714285714285714 * 1000 ) div 1000"/></ceilDec1>

Output

<ceilDec1>17.143</ceilDec1>

9. Advanced Number formatting 🔗

We may come across the scenarios especially when dealing with financial or accounting integrations, wherein we want the numbers like 1234.56 , 45 to be formatted like 1,234.56 , $45.00 , etc. One common way, while developing integration which we opt for, is multiple substrings and then multiple concatenations. There is a built-in function format-number, which can come in really handy in such situations.

Syntax:

format-number($number,$format,[$decimal-format])

Note: Here $decimal-format parameter is optional and we have not used it in examples.

Format Character Table

S.No.	Character	Description
1	0	Representation for digit. For 0 after the decimal and before the number, it is present. For example, the number 1 with the format as ‘00.0’ will give 01.0
2	#	Representation for digit. For 0 after the decimal and before the number, it is absent. For example, the number 1 with the format as ‘##.#’ will give 1
3	.	Separator for decimal.
4	,	Group Separator. Suppose we want to separate thousands, we may use like #,###.##, When 1000 is passed as input, the output becomes 1,000.
5	%	Represent number in %
6	;	Separator to define different formats for negative and positive numbers.

Format number performs the round operation by default(which is banker’s rounding) to the number of decimal places defined in format. To understand more on how can we use various formats. Please find below the table consisting of various use cases

S.No.	Use Case	Format	Input Number	Formatted Number
1	Always having two Decimal digits	#.00	123.456	123.46
			123.4	123.40
2	Having a maximum of 2 decimal digits	#.##	123.456	123.46
			123	123
3	Creating a number in Currency Format	$#,###,###.00	123456.789	$123,456.79
4	Display number in percentage	0.13245	##.##%	13.25%
5	Having different formats for positive and negative numbers.	#.000;(#.000)	132.45	132.450
			-132.45	(132.450)

XSL:

<format1><xsl:value-of select="format-number(123.456, '#.00')"/></format1>
<format1-1><xsl:value-of select="format-number(123.4, '#.00')"/></format1-1>
<format2><xsl:value-of select="format-number(123.456, '#.##')"/></format2>
<format2-1><xsl:value-of select="format-number(123, '#.##')"/></format2-1>
<format3><xsl:value-of select="format-number(123456.789, '$#,###,###.00')"/></format3>
<format4><xsl:value-of select="format-number(0.13245, '##.##%')"/></format4>
<format5><xsl:value-of select="format-number(132.45, '#.000;(#.000)')"/></format5>
<format5-1><xsl:value-of select="format-number(-132.45, '#.000;(#.000)')"/></format5-1>

Output

<format1>123.46</format1>
<format1-1>123.40</format1-1>
<format2>123.46</format2>
<format2-1>123</format2-1>
<format3>$123,456.79</format3>
<format4>13.25%</format4>
<format5>132.450</format5>=
<format5-1>(132.450)</format5-1>

Common Errors 🔗

We get XPath errors when the data type doesn’t match the numeric data type.
We get NaN(Not a Number) error when we explicitly try to convert a string or any other data type to a number using the number() function and the string contains some invalid characters apart from what is accepted by the number data type.

XSL to explain NaN errors:

<errors>
 <error><xsl:value-of select="number('123 1')"/></error>
 <error><xsl:value-of select="number('abc')"/></error>
 <error><xsl:value-of select="number('123b')"/></error>
</errors>

Resources: 🔗

XSLT file containing all the XSL statements used in the blog – Link
The output of the above file – Link

Please share your valuable feedback 😊😊😊

Using REST APIs to manage Connections in OIC

Sun, 20 Jun 2021 06:10:00 +0000

In cases, when we have many connections created on the OIC instance, it becomes hard to manage connections using the OIC console. Also, to achieve automation, manually going and updating each and every connection is never a feasible task. OIC provides various REST APIs to fetch connection details, update connection properties and delete connections. With the help of these APIs, we can overcome such scenarios.

In this blog, we will be discussing how to use various OIC connections REST APIs. A postman collection in the public workspace, which contains some of the use cases for this and can be forked, updated, and used accordingly.

Below are various REST APIs, that are covered in this blog.

Retrieve Connections
Retrieve a Connection
Update a Connection
Test a Connection
Refresh Metadata for a Connection
Delete a Connection

In this blog, we will be using Postman to test and run various APIs. Below is the link to the Postman collection, which will be helpful to try and test different REST APIs.

Authentication for REST APIs 🔗

To invoke OIC connections REST APIs, BASIC AUTH can be used to authenticate and authorize calls. The user whose credentials are used to call these APIs must have access to edit the connection.

OAuth can also be used to authenticate to REST APIs. In this blog, we will be using Basic Auth to authenticate/authorize API calls.

1. Retrieve Connections 🔗

[GET] {oic_host}/ic/api/integration/v1/connections

{oic_host} - Host URL for OIC instance

This API lets to get all available connections available on the OIC instance. This API provides support for pagination also. The default number of connection information returned without using the limit query parameter is 101.

We can use the limit query parameter to limit the number of records returned. For example:

As in the above example, we have kept the limit as 5, if we want to get the next 5 connection details, we need to update the request as below

[GET] {oic_host}/ic/api/integration/v1/connections?limit=5 &offset=5

This will return the connections 6-10.

To make this response even more readable, we have added a Visual table using the Postman visualizer. Once you click the Visualize under the response the section after sending the request from this Postman collection, the below tabular representation is shown.

2. Retrieve a Connection 🔗

[GET]{oic_host}/ic/api/integration/v1/connections/ :id

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API lets you fetch connection details of a specific connection by adding Connection ID as a path parameter to the request URL.

To make this response even more readable, we have added a Visual table using the Postman visualizer. Once you click the Visualize under the response section after sending the request from this Postman collection, the below tabular representation is shown.

3. Update a Connection 🔗

[POST]{oic_host}/ic/api/integration/v1/connections/ :id

{oic_host} - Host URL for OIC instance.
:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API helps to update the connection properties of a particular connection in the OIC instance. Let’s take an example to update the REST Connection properties that include Base path and Basic Auth user credentials.

Request Headers: 🔗

X-HTTP-Method-Override: PATCH

Request:

{
 "connectionProperties": {
 "propertyGroup": "CONNECTION_PROPS",
 "propertyName": "connectionUrl",
 "propertyType": "URL",
 "propertyValue": "{{CONN_REST_URL}}"
 },
 "securityPolicy": "BASIC_AUTH",
 "securityProperties": [
 {
 "propertyGroup": "CREDENTIALS",
 "propertyName": "username",
 "propertyValue": "{{CONN_USERNAME}}"
 },
 {
 "propertyGroup": "CREDENTIALS",
 "propertyName": "password",
 "propertyValue": "{{CONN_PASSWORD}}"
 }
 ]
}

Here, {{CONN_REST_URL}} will be the base URL of the REST endpoint. {{CONN_USERNAME}} and {{CONN_PASSWORD}} will be the credentials for BASIC Authentication for invoking the REST endpoint.

4. Test a Connection 🔗

[POST]{oic_host}/ic/api/integration/v1/connections/:id/test

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API is an alternative to the TEST button on OIC Connection page for a particular connection. Below is an example of successful testing of a Connection.

5. Refresh Metadata for a connection. 🔗

[POST] {oic_host}/ic/api/integration/v1/connections/:id/metadata

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

Sometimes, we may cache metadata for a connection, and if for some reason metadata is changed but our connection is still referring to old metadata. This API can come in handy. Below is the sample invocation of REST API in postman to refresh the metadata of a connection.

6. Delete a Connection 🔗

[DELETE] {oic_host}/ic/api/integration/v1/connections/ :id

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API can be used to delete a connection available on the OIC instance. This API saves a lot of time to perform delete operations rather than going to UI and manually deleting a connection. All you need to know is the connection id of the connection. Below is an example of the successful deletion of Connection by triggering the API using Postman.

To Validate if the Connection is deleted or not we can use a retrieve a connection API and check if the connection is available or not.

References: 🔗

https://docs.oracle.com/en/cloud/paas/integration-cloud/rest-api/api-integrations-connections.html

Please share your valuable feedback in the comments section below 😊

XML to String and String to XML conversion

Thu, 24 Sep 2020 00:00:00 +0000

Use Cases 🔗

Many a times, we may need to convert xml data and pass it as a string inside an XML tag.
Sometimes from source, we get data which is in string format but actually is xml encoded in string format.

To do so in Oracle BPEL 12c or OSB 12c we can use built in functions.

XML data to String 🔗

Sample input 🔗

<inRoot>
 <t1>Hello</t1>
 <t2>World</t2>
 <t3>One</t3>
</inRoot>

Sample output 🔗

<outRoot> <t1>&lt;inRoot&gt;&lt;t1&gt;Hello&lt;/t1&gt;&lt;t2&gt;World&lt;/t2&gt;&lt;t3&gt;One&lt;/t3&gt;&lt;/inRoot&gt;</t1>
</outRoot>

XSLT 🔗

This can be accomplished by using the function oraext:get-content-as-string(element as node-set). This function is really helpful when we are working on BPEL as we can use this function in ASSIGN activity or in TRANSFORM activity using XSLT.

xmlns:oraext=“http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc"

element as node-set: xml data(can be variable, xpath, or a function that returns xml data)

Example: 🔗

<outRoot>
 <t1><xsl:value-of select="oraext:get-content-as-string(/ns0:inRoot)"/></t1>
</outRoot>

XQuery 🔗

Xquery too have a function to convert xml to string i.e. fn-bea:serialize($arg as item()*) as xs:string. This function is really helpful when we are dealing with OSB.

xmlns:fn-bea=“http://www.bea.com/xquery/xquery-functions"

$arg: Variable containing XML data.

Example: 🔗

$input contains xml data that needs to be converted and assigned to one tag in output payload.

<outRoot>
 <t1>{fn-bea:serialize($input)}</t1>
</outRoot>

String to XML 🔗

Sample input 🔗

'&lt;inRoot&gt;&lt;t1&gt;Hello&lt;/t1&gt;&lt;t2&gt;World&lt;/t2&gt;&lt;t3&gt;One&lt;/t3&gt;&lt;/inRoot&gt;'

Sample output 🔗

<inRoot>
 <t1>Hello</t1>
 <t2>World</t2>
 <t3>One</t3>
</inRoot>

As we can see in above example that < and > are replaced with < and >. In xml < and > are invalid characters and escaper characters are used in place of these.

XSLT 🔗

In xslt, we can use built in function oraext:parseXML(stringData).This function is really helpful when we are working on BPEL as we can use this function in ASSIGN activity or in TRANSFORM activity using XSLT.

xmlns:oraext=“http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc"

stringData: string value of xml data.

Example: 🔗

<xsl:copy-of select="oraext:parseXML('&lt;inRoot&gt;&lt;t1&gt;Hello&lt;/t1&gt;&lt;t2&gt;World&lt;/t2&gt;&lt;t3&gt;One&lt;/t3&gt;&lt;/inRoot&gt;')"/>

Note: we have used copy-of instead of value-of as we need all the xml nodes to be copied to the target file. If we want to extract the data from xml without xml tags then we can use value-of.

XQuery 🔗

In xquery, we can use fn-bea:inlinedXML($arg as xs:string) as node()*. This function is really helpful when we are dealing with OSB.

xmlns:fn-bea=“http://www.bea.com/xquery/xquery-functions"

$arg: variable containing xml data in string format.

Example: 🔗

fn-bea:inlinedXML('&lt;inRoot&gt;&lt;t1&gt;Hello&lt;/t1&gt;&lt;t2&gt;World&lt;/t2&gt;&lt;t3&gt;One&lt;/t3&gt;&lt;/inRoot&gt;')

Remove Empty tags using XSLT

Sun, 13 Sep 2020 00:00:00 +0000

While performing xslt transform on source XML, we may need not to include empty tags in the output xml payload.

Sample scenarios: 🔗

Target system doesn’t want empty tags to come.
Size of xml payload has become huge due to unwanted empty tags.

Source XML 🔗

<inRoot>
 <t1>Hello</t1>
 <t2></t2>
 <t3>World</t3>
</inRoot>

Output XML 🔗

<outRoot>
 <a1>Hello</a1>
 <a3>World</a3>
</outRoot>

The optimal way to achieve above result is to use conditional if statement in xslt i.e. xsl:if

Sample XSLT 🔗

<xsl:if test="/inRoot/t2!=''">
 <a2>
 <xsl:value-of select="ns0:C1"/>
 </a2>
</xsl:if>

If we have some whitespaces included between tags, the above if-statement may fail and in such scenarios, we may use normalize-space() function in xslt and test condition will become : “normalize-space(/inRoot/t2)!=’’”

Sometimes, we just want to remove empty elements from already transformed xml. Such cases have same input and output schemas. In such scenarios we can take leverage of identity transform using xsl templates and copy methods. See the below sample xslt identity transform to remove empty tags.

Sample XSLT: 🔗

<xsl:template match="node()|@*">
 <xsl:if test="normalize-space(.) !='' or ./@* !=''">
 <xsl:copy>
 <xsl:copy-of select="@*"/>
 <xsl:apply-templates/>
 </xsl:copy>
 </xsl:if>
</xsl:template>

If we are using xslt in JDev, we need to specify input and output schemas and replace xsl:template tag with the above xsl template code.

Format String oraext:format-string

Sat, 05 Sep 2020 00:00:00 +0000

In our integration world, sometimes target system requires the data from source system to be formatted in some specific format which may require data from various input fields along with custom data. To do so we generally use concat() function to concatenate data from various fields and some user specific inputs.

Lets take the below example

Suppose we have a predefined format for the output string:

The abc with employeeID: 1234567 has been successfully registered in the system.

Here, name of the employee($empName=‘abc’) and employee id($empId=‘1234567’) are dynamic values. One way to accomplish this, is to use concat().

concat('The ',$empName,' with employeeID: ',$empId,' has been successfully registered in the system.')

Another way we can achieve this, is using oraext:format-string(string,string,string…)

oraext:format-string ('The {0} with employeeID: {1} has been successfully registered in the system.',$empName, $empId)

In above example, first string defines the output format containing place holders({0},{1}). These place holders will be replaced by the subsequent string values($empName=‘abc’, $empId=‘1234567’). In future, if we need to change the position of these dynamic value in output string, all we need to do is to move the position of these placeholders.

Note: Maximum of 10 arguments are supported for this function.

DateTime formatting using xp20:format-dateTime()

Wed, 02 Sep 2020 00:00:00 +0000

xs:dateTime Format 🔗

In XML, we generally use xs:dateTime(xs:xmlns=“http://www.w3.org/2001/XMLSchema") data type to store date time data. The generic representation of date time, that is supported by xs:dateTime in xml:

YYYY-MM-DDThh:mm:ss[.SSS][Z|(+|-)hh:mm]

Example: 🔗

2019-09-11T10:16:31.943+05:30

Code	Description	Example
YYYY	represents a 4-digit year	2019
MM	represents a 2-digit month	09
DD	represents 2-digit date	11
hh	represents 2-digit hours	10
mm	represents minutes in 2-digits	16
ss	represents seconds in 2-digits	31
SSS	represents milliseconds	943
T	represents time separator	T
Z	represents UTC time zone or 0 time zone offset
(+\|-)	hh:mm represents time zone offset	+5:30

Few more valid examples: 2019-09-11T21:32:52, 2019-09-11T21:32:52+02:00, 2019-09-11T19:32:52Z, 2019-09-11T19:32:52+00:00, 2019-09-11T21:32:52.11179

While working with different systems, we may come across such systems, which require date time in some different formats other than default format as supported by xs:dateTime. To over come such scenarios, function is available in OIC(Oracle Integration Cloud) and Oracle SOA

Format DateTime 🔗

xp20:format-dateTime($dateTime as string, $format as string) xmlns:xp20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20"

$dateTime should contain date time value as per xs:dateTime data type as as string eg: ‘2019-09-11T10:16:31.943+05:30’

$format should contain output format to which we need to convert to. For e.g. if we want output to be ‘11/09/2019’ then value of $format should be [D01]/[M01]/[Y001].

xp20:format-dateTime('2019-09-11T10:16:31.943+05:30', '[D01]/[M01]/[Y001]')

To format current date time, we can use xp20:current-dateTime() in $dateTime

xp20:format-dateTime(xp20:current-dateTime(), '[D01]/[M01]/[Y001]')

Formatting Codes: 🔗

Below are some important codes which can be helpful in generating desired format for target application.

Sample dateTime: 2019-09-03T15:16:31.943+05:30

Code	Description	Example Output
[Y001]	4 digit year	2019
[Y01]	2 digit year	19
[M01]	2 digit month	09
[D01]	2 digit date	03
[H01]	2 digit hour in 24 hour clock	15
[h01]	2 digit hour in 12 hour clock	03
[m01]	2-digit minutes	16
[s01]	2-digit seconds	31
[f001]	3-digit milliseconds	943
[Z]	Time zone offset in the form (+\|-)hhmm	+0530
[z]	Time zone offset in the form GMT(+\|-)hh:mm	GMT+05:30
[Dwo]	Word for ordinal value of day	third
[dwo]	The day of the year, represented in ordinal words	second hundred and forty-sixth
[MNn]	Capitalized month name	September
[P]	am/pm	pm
[PX]	Uppercase am/pm	PM
[FNn]	Capitalized weekday name	Tuesday
[MNn,a-b]	Capitalized month name having atleast “a” charcters and atmost “b” characters [MNn,3-3]:	Sep