For Orchestrated Integration Invoke Connections

The following pages describe how to configure a File Adapter invoke connection in an orchestrated integration.

Basic Information Page

Enter the basic information parameters.

Element	Description
What do you want to call your endpoint?	Provide a meaningful name so that others can understand the connection. For example, `FileReadWriteConnection`. You can include English alphabetic characters, numbers, underscores, and dashes in the name. You cannot include the following: Blank spaces (for example, `My FTP Connection`) Special characters (for example, `#;83&` or `righ(t)now4`) Multibyte characters
What does this endpoint do?	Enter an optional description of the connection’s responsibilities. For example: `This connection transfers files to a directory.`

Invoke Operations Page

Enter the File Adapter operation properties.

Choose one of the following operations to perform on files. Depending on which operation you choose, you are presented with different options and parameters that apply specifically to that operation. All operations support dynamic file name and directory through mapping.

Read File: Reads a file from the file location. This operation reads a single file. If you have not selected any schema, a file size of up to 1 GB is supported. If you have selected the schema, a file size of up to 50 MB is supported.
Write File: Writes a single file onto the target file server.
List Files: Lists the names of the files in the input directory. This operation returns the list of files without any data. It is similar to running the ls command in Linux.
Move a File: Moves a file from one location to another on the same target file server.
Delete a File: Deletes a single file on the file server.
Download File: Specifies a directory to be used for staged activity. Use this directory to stage large files for processing. This operation downloads a single file in the logical directory you specify. File size support is up to 1 GB.

Note:
If you want to read/download multiple files, use the following integration pattern.
File List File (Operation) > For Each Loop > File Read File (Operation) > End For Each Loop

The following tables describe the key information on the File Adapter invoke Operations page. Depending on which operation you choose, you are presented with different options and parameters that apply specifically to that operation. Each table corresponds to a specific operation.

Each operation can be performed against ZIP and GZIP file formats.

Read File

Note:

Elements marked with “+” can be mapped in the mapper and can be passed dynamically at runtime.

When using the connectivity agent, the Read File operation when used without a schema supports files of up to 1 GB in size. This limit is the same as the Download File operation. If you are using a schema for transformation, the file size limit is 50 MB. You can specify sample XML and JSON documents for the payload when configuring the File Adapter for read operations.

Element	Description
Input Directory	The name of the directory that contains the file to be read. For example, `/tmp/Oracle/input`.
File Name	The name of the file to be read. The name can also be provided by the mapper. File sizes of up to 50 MB are supported.

Write File

When using the connectivity agent, the Write File operation when used without a schema supports files of up to 1 GB in size. This limit is the same as the Download File operation. If you are using a schema for transformation, the file size limit is 50 MB. You can specify sample XML and JSON documents for the payload when configuring the File Adapter for write operations.

Element Description

Element	Description
Specify an Output Directory	The directory path to which to write the file. For example, `/tmp/Oracle/output`.
File Name Pattern	The pattern of file names to transfer to the output directory. Use the pattern inside `%%`. For example, `Oracle%SEQ%ICS.txt` creates files in sequence, such as `Oracle1ICS.txt`, `Oracle2ICS.txt`, and so on. For a list of supported file patterns, click the information icon. Note: Use of these patterns leads to message loss if the messages are written to the file system at the same time or files are written to a separate node. To ensure that files are not overwritten, use the mapper to assign the file names explicitly. You can use XPath functions to ensure that file names are unique.
Append to Existing File	If selected, the file content is appended to the existing file content and is not overwritten. Notes: Writing record by record using the Append to Existing File option creates too many network calls and eventually slows down the process. Instead, use a stage file action and write the records to a stage directory. Once all records are written, use the List File option in the stage file action and the File Adapter option to transfer the file to a file location. This approach reduces processing time and prevents too many calls to the file server. You may be performing successive appends by putting multiple write operations or using a write operation in a for-each loop. In this scenario, if the file server is running on multiple nodes or on a cloud service, it should synchronize the data immediately among all nodes. Otherwise, if the next request goes to a different node, there is inconsistency in the final output file. As an alternative, you can also place a wait activity before or after every append to give the data time to synchronize.

Specify an Output Directory

The directory path to which to write the file. For example, /tmp/Oracle/output.

File Name Pattern

The pattern of file names to transfer to the output directory. Use the pattern inside %%. For example, Oracle%SEQ%ICS.txt creates files in sequence, such as Oracle1ICS.txt, Oracle2ICS.txt, and so on. For a list of supported file patterns, click the information icon.

Note: Use of these patterns leads to message loss if the messages are written to the file system at the same time or files are written to a separate node. To ensure that files are not overwritten, use the mapper to assign the file names explicitly. You can use XPath functions to ensure that file names are unique.

Append to Existing File

If selected, the file content is appended to the existing file content and is not overwritten.

Notes:

Writing record by record using the Append to Existing File option creates too many network calls and eventually slows down the process. Instead, use a stage file action and write the records to a stage directory. Once all records are written, use the List File option in the stage file action and the File Adapter option to transfer the file to a file location. This approach reduces processing time and prevents too many calls to the file server.
You may be performing successive appends by putting multiple write operations or using a write operation in a for-each loop. In this scenario, if the file server is running on multiple nodes or on a cloud service, it should synchronize the data immediately among all nodes. Otherwise, if the next request goes to a different node, there is inconsistency in the final output file. As an alternative, you can also place a wait activity before or after every append to give the data time to synchronize.

List Files

Element	Description
Input Directory	The name of the directory that contains the file to be read. For example, `/tmp/Oracle/input`.
File Name Pattern	Specify a wildcard pattern to be used for listing files from the input directory. For example, `order*.csv`.
Max Files	The maximum number of file names that should be listed. The maximum value is 1000. Note: The List File operation returns the file list in a sorted order according to the last modified time. If you selected 10 as the maximum number of files and the last modified time of the eleventh file is the same as the tenth file, then the eleventh file is also added. This continues until you get a file with a different timestamp. For example, assume the directory has 15 files and you select 10 as the maximum number of files. If the tenth, eleventh, twelfth, and thirteenth files have the same time stamp, then the list file returns thirteen files.
Minimum Age	The minimum age in seconds for files to be displayed. For example, if the last time a file was modified is 02:28:45 AM and the minimum age is defined as 80 seconds, the file will not be listed at 02:29:00 AM and 02:30:00 AM. It will be listed after 02:30:05.
Process Files Recursively	List files within directories recursively beneath the input directory.

Move a File

Element	Description
Directory Path	The name of the directory that contains the file to be moved. For example, `/tmp/Oracle/input`.
File Name	The name of the file to be moved. There is no limit to the size of the file to move.
Target Directory Path	The name of the directory to which the file will be moved.
Target File Name	The name of the file as it will be written in the target directory.
Overwrite File	Select to overwrite the file in the target directory.

Delete a File

Element	Description
Directory Path	The directory path to the file you wish to delete.
File Name	The name of the file to delete.

Download File

The Download File operation enables you to map the download directory dynamically. This works fine for new integrations. You can also edit an existing Download File operation in the Adapter Endpoint Configuration Wizard to add more file download operations, then click Done to regenerate the adapter artifacts. You can download file sizes of up to 1 GB.

Using the Download File operation with the connectivity agent enables you to upload the file from the connectivity agent server to Oracle Integration. This operation enables you to download and upload files of up to 1 GB in size. This operation may take more time depending on the network conditions between the file server and the connectivity agent and the connectivity agent and Oracle Integration.

Element Description

Element	Description
Input Directory	Specify the name of the directory that contains the file to be read. For example, `/tmp/Oracle/input`.
File Name	The name of the file to download. This can be overridden using the mapper.
Download Directory	The name of the directory to be used for stage file action. See Processing Files in Scheduled Integrations with a Stage File Action. Do not enter the directory path in double quotes. The quotes are mistakenly included as part of the directory name.

Input Directory

Specify the name of the directory that contains the file to be read. For example, /tmp/Oracle/input.

File Name

The name of the file to download. This can be overridden using the mapper.

Download Directory

The name of the directory to be used for stage file action. See Processing Files in Scheduled Integrations with a Stage File Action.

Do not enter the directory path in double quotes. The quotes are mistakenly included as part of the directory name.

Invoke Schema Page

Enter the schema properties.

Element	Description
Do you want to specify the structure for the contents of the file?	Yes: Select to define a schema format to use for the file to transfer. This option enables you to read and write files up to 50 MB in size. No: Select if a schema is not required and you want to send the file as an attachment. You typically select No if you want to stream large files to or from the servers. This option enables you to read and write files up to 1 GB in size.
Which one of the following choices would be used to describe the structure of the file contents?	Select an option: Sample delimited document (e.g. CSV): Select to create a new schema file from a comma-separated value (CSV) file. On a subsequent page of this wizard, you are prompted to select the CSV file from which to create the schema. XML schema (XSD) document: Select an existing schema file. On a subsequent page of this wizard, you are prompted to select the existing schema (XSD) file from the file system. You can also upload non-native schemas that are created outside of Oracle Integration. See XSD File Capabilities. Sample XML document (Single or No Namespace): Select to provide sample XML content for the payload. Sample JSON document: Select to provide sample JSON content for the payload.

Element

Description

Do you want to specify the structure for the contents of the file?

Yes: Select to define a schema format to use for the file to transfer. This option enables you to read and write files up to 50 MB in size.
No: Select if a schema is not required and you want to send the file as an attachment. You typically select No if you want to stream large files to or from the servers. This option enables you to read and write files up to 1 GB in size.

Which one of the following choices would be used to describe the structure of the file contents?

Select an option:

Sample delimited document (e.g. CSV): Select to create a new schema file from a comma-separated value (CSV) file. On a subsequent page of this wizard, you are prompted to select the CSV file from which to create the schema.
XML schema (XSD) document: Select an existing schema file. On a subsequent page of this wizard, you are prompted to select the existing schema (XSD) file from the file system. You can also upload non-native schemas that are created outside of Oracle Integration.

See XSD File Capabilities.
Sample XML document (Single or No Namespace): Select to provide sample XML content for the payload.
Sample JSON document: Select to provide sample JSON content for the payload.

XSD File Capabilities

The adapter supports the upload of an XSD file without a target namespace. In these cases, a surrogate namespace is added to the XSD file that all messages then use:
```
http://xmlns.oracle.com/cloud/adapter/nxsd/surrogate
```

The adapter supports complex XSDs that can import and include other XSDs. The included XSDs in the ZIP file can import the XSD from an HTTP location. All XSD files must be added to a ZIP file and uploaded when configuring the adapter for read and write operations in the Adapter Endpoint Configuration Wizard.

In the following example, the hierarchy of the ZIP file to upload is as follows:

zipxsd.zip
  first.xsd
  second (folder)
    second.xsd

first.xsd imports second.xsd.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:tns="http://xmlns.oracle.com/first" 
targetNamespace="http://xmlns.oracle.com/first" 
      xmlns:tns1="http://xmlns.oracle.com/second"> 
<xs:import schemaLocation="./second/second.xsd" 
targetNamespace="http://xmlns.oracle.com/second"/>
<xs:import schemaLocation="https://example.com/fscmService/ItemServiceV2?
XSD=/xml/datagraph.xsd" targetNamespace="commonj.sdo"/>
<xs:element name="book"> 
  <xs:complexType> 
    <xs:sequence> 
      <xs:element name="isbn" type="xs:string"/>
      <xs:element name="title" type="xs:string"/> 
      <xs:element name="author" type="tns1:author"/> 
    </xs:sequence> 
  </xs:complexType>  
</xs:element> 
</xs:schema>

The contents of second.xsd are as follows.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:tns="http://xmlns.oracle.com/second" 
targetNamespace="http://xmlns.oracle.com/second"> 
<xs:import schemaLocation="https://example.com/fscmService/ItemServiceV2?
XSD=/mycompany/apps/scm/productModel/items/itemServiceV2/ItemAttachment.xsd" 
targetNamespace="http://xmlns.oracle.com/apps/scm/productModel/items/itemServiceV2/"/>
<xs:complexType name="author">
    <xs:sequence> 
       <xs:element name="name" type="xs:string"/>  
       <xs:element name="address" type="xs:string"/> 
    </xs:sequence> 
</xs:complexType> 
<xs:element name="Admin">
    <xs:complexType>
          <xs:sequence>
             <xs:element name="AdminName" type="xs:string"/>
             <xs:element name="AdminAdd" type="xs:string"/>
          </xs:sequence>
    </xs:complexType>
</xs:element>
</xs:schema>

Note:

If you are importing from HTTPS locations, ensure that you import the SSL certificates into Oracle Integration.

File Contents - Definition Page

Enter the format definition parameters.

The fields that display on the Format Contents - Definition page are determined by your selection on the Schema page:

Note:

If configuring the adapter in the trigger (inbound) direction, schema selection is not supported. If you select Yes to define a schema for the endpoint on the Basic Info page, nothing prevents you from uploading a schema on the Format Contents - Definition page. However, this schema is not used. You must select No on the Basic Info page to transfer files as an attachment.
The adapter can only be configured as an invoke connection in an orchestrated integration.

Creating a New Schema from a CSV File

Element	Description
Select the Delimited Data File	Select the delimited comma-separated value (CSV) file from which to create the schema file. The content of the file is then displayed at the bottom of the page.
Enter the Record Name	Enter the record name. This becomes the parent element in the created schema file for the record names selected as column headers from the CSV file.
Enter the Recordset Name	Enter the recordset name. This becomes the root element of the created schema file.
Select the Field Delimiter	Select one of the following supported file delimiter options: Single space Comma Semicolon Tab Pipe (for example, Name\|City\|Country)
Character Set	Select a character set. The selected value will be used as the encoding format while reading the sample data file. This field is used for character encoding during file transfer. If data sent to the adapter is in a specific encoding format, then select that same encoding format in the adapter. Otherwise, there may be some character loss in the final written file. This also corrupts the file. For example, if a REST Adapter is using UTF-8 encoding and the adapter is configured with the ASCII character set, this may corrupt the file. If you select the same UTF-8 encoding in the adapter, the problem is resolved.
Optionally Enclosed By	This value causes occurrences of the selected delimiter to be ignored during processing. For example, when processing the following record: `Fred,"2 Old Street, Old Town,Manchester",20-08-1954,0161-499-1718` If the selected Field Delimiter is “,” and the Optionally Enclosed By value is `quot;` (`“`), then the value `2 Old Street, Old Town,Manchester` is treated as a single record column. If Optionally Enclosed By is used, the character must not be part of any field. Therefore, the following is invalid: `a,b",c` (In this scenario, `"` is part of the second field) `a,"b,c",d` (In this scenario, the second field is created using Optionally Enclosed By (`'"'`). However, it has `','` as content for the second field value.)
Terminated By	Displays by default the first row of the selected CSV file as the column headers. Select the option to terminate the end of a line. ${eol} \n \r\n \r
Detach	Select to edit the CSV file in a separate window.
Use First Row as Column Headers	Select to use the first row as the column headers.
Mark All As Optional	Select to mark elements as optional in the schema file. By default, all elements are mandatory. You can also select the data type (for example, string, byte, integer, and so on) to use for each column in the table and mark specific elements as optional. While this option enables you to select all elements as optional, you must have at least one mandatory element to validate this page. This checkbox provides a convenient method to select the majority of elements as optional.

Select an existing XML schema or schema archive from the file system

The schema archive can have a single top level schema with nested input and include elements containing absolute or relative paths.

Element	Description
Select File	Select the existing schema file to use.
Selected File Name	Displays the selected schema file name.
Select the Schema Element	Select the schema element. This field is displayed after the schema file is selected. The element name is treated as the root element in the uploaded schema file.

Provide a sample XML document from the file system

The XML document should contain no namespaces or only a single namespace.

Element	Description
Select File	Select the existing XML document to use.
Selected File Name	Displays the selected schema file name.
Select the Schema Element	Select the schema element. This field is displayed after the schema file is selected. The element name is treated as the root element in the uploaded schema file.

Provide a sample JSON document from the file system

Element	Description
Select File	Select the existing JSON file to use.
Selected File Name	Displays the selected file name.
Select the Schema Element	Select the schema element. This field is displayed after the schema file is selected. The element name is treated as the root element in the uploaded schema file.

Summary Page

You can review the specified adapter configuration values on the Summary page.

Element	Description
Summary	Displays a summary of the configuration values you defined on previous pages of the wizard. The information that is displayed can vary by adapter. For some adapters, the selected business objects and operation name are displayed. For adapters for which a generated XSD file is provided, click the XSD link to view a read-only version of the file. To return to a previous page to update any values, click the appropriate tab in the left panel or click Back. To cancel your configuration details, click Cancel.

Element

Description

Summary

Displays a summary of the configuration values you defined on previous pages of the wizard.

The information that is displayed can vary by adapter. For some adapters, the selected business objects and operation name are displayed. For adapters for which a generated XSD file is provided, click the XSD link to view a read-only version of the file.

To return to a previous page to update any values, click the appropriate tab in the left panel or click Back.

To cancel your configuration details, click Cancel.