OIC - Resolving "SOAP Header Security was not understood" invoking Web Services

Use Case:

In a utility integration scenario using MultiSpeak-compliant web services, a SOAP request fails with the error:
"CASDK-0033: Received a SOAP fault... Fault Code : soap:MustUnderstand – SOAP header Security was not understood."
This typically occurs when integrating Oracle Integration Cloud (OIC) with a third-party endpoint that requires WS-Security headers.

Root Cause:

The SOAP request included a <wsse:Security> block with mustUnderstand="1", but the target endpoint does not understand or support WS-Security headers in that format.
Alternatively, the expected security token or credentials were missing or not compliant with the service’s expected authentication scheme.

Solution Steps:

Step 1: Understand the Error Message

Error:

Fault Code : soap:MustUnderstand  
Fault String : SOAP header Security was not understood.

This indicates that the service could not process the WS-Security headers, often because it does not support them or requires a different security configuration.

Full error details:

CASDK-0033: Received a SOAP fault while invoking endpoint target: https://<host>/CC/WebAPI/MRCB.asmx.

This indicates a processing exception on the service endpoint side. Please check service side logs to further diagnose the problem

<![CDATA[

Fault Code : soap:MustUnderstand

Fault String : SOAP header Security was not understood.

]]>

Step 2: Analyze the SOAP Request

The failing payload included this header:

<wsse:Security env:mustUnderstand="1" ...>
  <wsu:Timestamp ...>
    <wsu:Created>...</wsu:Created>
    <wsu:Expires>...</wsu:Expires>
  </wsu:Timestamp>
</wsse:Security>

This was likely injected by a policy in Oracle Integration Cloud (OIC) or a SOAP client security configuration.

Step 3:  Suppress the insertion of timestamp in the request from the soap invoke connection. This will remove the Security Header from the request.

Reason: The target service does not support WS-Security, modify the request to remove the <wsse:Security> block completely.

Connection snap:

Failing payload:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

  <env:Header>

    <tns:MultiSpeakMsgHeader env:mustUnderstand="0" UserID="xxxx" Pwd="xxxx" xmlns:tns="http://www.multispeak.org/Version_5.0"/>

    <wsse:Security env:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">

      <wsu:Timestamp wsu:Id="TS-84" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

        <wsu:Created>2025-05-09T09:07:58.512Z</wsu:Created>

        <wsu:Expires>2025-05-09T10:07:58.512Z</wsu:Expires>

      </wsu:Timestamp>

    </wsse:Security>

  </env:Header>

  <env:Body>

    <tns:MeterAddNotification xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:tns="http://www.multispeak.org/Version_5.0">

      <tns:addedMeters>

        <tns:meter>

          <tns:meterNo>2345</tns:meterNo>

          <tns:utilityInfo>

            <tns:servLoc>SL#1435</tns:servLoc>

          </tns:utilityInfo>

        </tns:meter>

      </tns:addedMeters>

    </tns:MeterAddNotification>

  </env:Body>

</env:Envelope>

Updated working payload:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

  <env:Header>

    <tns:MultiSpeakMsgHeader env:mustUnderstand="0" UserID="xxxx" Pwd="xxxx" xmlns:tns="http://www.multispeak.org/Version_5.0"/>

  </env:Header>

  <env:Body>

    <tns:MeterAddNotification xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:tns="http://www.multispeak.org/Version_5.0">

      <tns:addedMeters>

        <tns:meter>

          <tns:meterNo>2345</tns:meterNo>

          <tns:utilityInfo>

            <tns:servLoc>SL#1435</tns:servLoc>

          </tns:utilityInfo>

        </tns:meter>

      </tns:addedMeters>

    </tns:MeterAddNotification>

  </env:Body>

</env:Envelope>

Step 4: Test the Integration

Resend the modified payload from OIC or any SOAP client (e.g., SOAP UI or Postman with SOAP support). The endpoint should now process the request successfully.

OIC - Combining Source File Records into a Single Line in Oracle Integration Cloud (OIC)

Working...

Issue Statement:

In many real-time integrations, especially in ERP or data migration scenarios, source files are received in a structured format (e.g., one header record followed by multiple detail records). However, certain downstream systems or services may require this data to be flattened into a single string line (e.g., HeaderDetailDetailDetail...) before further processing. Oracle Integration Cloud (OIC) does not offer a direct activity to do this in a single step, so a custom approach is required.

Solution Steps:

Technique 1 : for small size source file

Read the file:

Read the source file as raw line by line using a sample csv file uaing ftp adapter.

Write File using stage and translate for each line new line :

translate(ns22:FileData, "&#xA;&#xD;", "")

This XSLT function removes newline (
) and carriage return (
) characters from each line, which is essential when combining multiple lines into a single line in OIC.

Technique 2: For bigger size file - 10k ~ 30k size.

TBD

OIC - How will you handle error in OIC integration? If you are processing multiple records, how will you ensure all the records are processed even if a single record errors out?

How will you handle error in OIC integration? If you are processing multiple records, how will you ensure all the records are processed even if a single record errors out?

Answer:

In Oracle Integration Cloud (OIC), when processing multiple records (for example, a JSON array or CSV data), handling errors gracefully is crucial to prevent the entire integration from failing due to a single bad record. Here's how to ensure all records are processed even if one fails:

1. Use a For-Each Action:
   Loop through the array or list of records using the For-Each action so each record is processed individually.

2. Wrap Logic Inside a Scope:
   Place your main processing logic for each record inside a Scope activity.

3. Add Fault Handler to Scope:
   Inside the Scope, add a Fault Handler to catch any errors specific to that record and log or handle them (e.g., write to a log file, invoke an error-handling integration, or call a notification).

4. Continue on Error:
   Since the fault is handled within the loop, the integration will not fail globally and will continue to the next record in the For-Each.

5. Track Success and Failures:
   Optionally, maintain a status array or write results to a lookup, object store, or DB table indicating success or failure for each record.

This way, each record is treated independently, and errors in one record do not block the processing of others.

OIC Lookup Import Error – "The Type, Name and Description Line is Invalid" [Resolved]

Issue Case:

While trying to re-import a modified Lookup CSV file back into Oracle Integration Cloud (OIC), an error occurred:

"Failed to import lookup file ‘XYZ.csv’. The lookup is formatted incorrectly. The Type, Name and Description line is invalid."

This happened despite exporting the Lookup directly from OIC and only updating its rows.

Root Cause:
Upon opening the exported CSV file in Notepad, it was observed that the header line:

Type,Name,Description,,,,,,,

...contained extra trailing commas. These additional commas beyond the expected three fields caused the file to be rejected by OIC during import, as it violates the expected format.

Solution Steps:

1. Open the exported Lookup CSV file using Notepad or any plain text editor.
2. Locate the first line that should read:

   Type,Name,Description
   

3. Remove all extra commas after "Description" so that only three fields are defined in the header row.
4. Save the file with the same CSV format (UTF-8 or ANSI).
5. Retry the import in OIC — it should now succeed without error.

OIC - Automating File-Based Integrations in OIC: A Scheduler-to-SFTP Flow Using Object Storage and Child Integrations

Use Case

In many enterprise scenarios, large volumes of files are generated daily and need to be processed, transformed, and delivered to target systems on a schedule. This blog outlines an OIC-based solution where a scheduled integration orchestrates the entire process: from validating input parameters, listing files from Oracle Object Storage, and invoking a child integration to download, transform, and upload the files to an SFTP server.

Solution Architecture

The solution consists of three integrations:

1. Scheduler Integration – Initiated with a fileProcessingDate parameter (format: yyyyMMdd) and validates its format. This is empty by default that means current date will be used to fetch the file. but if someone wants to reprocess the file, have to put the file processing date.
2. Main Integration – Lists files from a configured Object Storage path based on prefix and and date filter in the file name and loops over each file and invokes the child integration.
3. Child Integration – Downloads each file, performs necessary transformation, and uploads it to a specified target SFTP location.

Solution Steps

1. Scheduler Integration

• Trigger Type: Scheduled
• Input Parameter: fileProcessingDate (string, format: yyyyMMdd)
• Step 1: Validate fileProcessingDate using an inline expression or JavaScript function.
  • Throw a fault if the format is invalid.
• Step 2: Call the Main Integration, passing fileProcessingDate as a parameter.

2. Main Integration

• Trigger Type: App Driven (HTTP or SOAP)
• Input: fileProcessingDate
• Step 1: Use List Objects action (Object Storage adapter) to list files in the bucket/prefix corresponding to fileProcessingDate.
• Step 2: Loop over each file name from the response.
• Step 3: For each file, call the Child Integration and pass:
  • File name
  • File path (if required)
  • fileProcessingDate (if used in downstream processing)

3. Child Integration

• Trigger Type: App Driven
• Inputs:
  • File name
  • File path (optional)
• Step 1: Use Get Object action from Object Storage to download the file.
• Step 2: Apply transformation (e.g., map fields, convert formats).
• Step 3: Use FTP Adapter to upload the file to the target SFTP folder.

OIC - Understanding self::node() XSLT function in Oracle Integration cloud

In Oracle Integration Cloud (OIC) XSLT, the XPath function self::node() is used to reference the current node in a predicate or expression.

Purpose of self::node()

It ensures that the comparison or operation is being done on the current node itself, rather than its child or attribute.

Example Usage in OIC

In your expression:

fn:count(ns95:dtstart[(self::node() = $FileProcessingDate)])

Here:

• self::node() refers to the value of the current dtstart element.
• It compares that value directly to $FileProcessingDate.

Why use self::node()?

While . (dot) also refers to the current node, self::node() is more explicit and avoids ambiguity in complex expressions, especially when namespaces or deeper hierarchies are involved in OIC mappings.

Simplified Equivalent

This:

self::node() = $FileProcessingDate

Is functionally equivalent to:

. = $FileProcessingDate

But self::node() is sometimes preferred in tools like OIC for clarity or compatibility.

OIC - How to skip File Processing Excluding Hong Kong Public Holidays in Oracle Integration Cloud Using 1823 API

Use Case:

When processing data files through Oracle Integration Cloud (OIC), certain business operations must be skipped on public holidays. To automate this, we want to check whether a file's processing date falls on a Hong Kong public holiday using the 1823.gov.hk public API. If it is a holiday, the integration should stop gracefully.

API used: Https://www.1823.gov.hk/common/ical/en.json

Solution Overview:

We will implement the following in Oracle Integration Cloud (OIC):

1. Create a REST connection to consume the Hong Kong 1823 Public Holiday API.
2. Fetch and parse the public holiday list.
3. Compare the input fileProcessingDate with the holiday list.
4. If it is a holiday, stop the integration using a Switch action.

Step-by-Step Implementation:

1. Create REST Connection in OIC

• Go to Connections > Create > Choose REST Adapter.
• Set the name (e.g., HK_PublicHoliday_API).
• Set the connection URL:
  https://www.1823.gov.hk
• Security: Select “No Security Policy”.
• Test and save the connection.

2. Build the Integration

• Create a new Scheduled Integration.
• Add a Schedule Parameter: fileProcessingDate (type: date or string in yyyy-MM-dd format).
• Add an Invoke action to call the REST Connection created earlier.
  • Method: GET
  • URI: /common/ical/en.json
  • Configure the response JSON to capture the public holiday data.

3. Add a Switch Action

• Put Condition: fn:count($GetHKHolidayList/ns96:executeResponse/ns95:response-wrapper/ns95:vcalendar/ns95:vevent/ns95:dtstart[self::node()= /ns91:execute/ns88:request-wrapper/ns88:ProcessRequest/ns88:FileProcessingDate]) > 0

• If condition matches: add a stop action which will stop to proceed further.

5. Test the Integration

• Test with various fileProcessingDate values including a known public holiday (e.g., 2025-01-01) and a regular working day.
• Confirm that the integration stops only on public holidays.