Data File Sets

Oracle Health Insurance applications support file based import operations. A file based import is a two-step process:

Upload the file using the Data File Sets API.
Process the file contents by initiating the proper activity type using the Activities API^[1] or through the User Interface pages.

The document How to Migrate Data Using a Data File Set offers a detailed example of loading and processing an import file.

The datafileset API enables the user to upload data files through, either, a single request creating the data file set and loading (multiple) data files in one go, or through a multiple-request-response based conversation.

Operations

GET

/datafilesets retrieves all data file sets in the system.

POST

/datafilesets creates the data file set with data files.

This integration point validates and accepts only XML, JSON, CSV, TXT, and ZIP file formats as input.
If an invalid file is uploaded, HTTP status code 415 - Unsupported Media Type will be returned.

PUT

/datafilesets updates the data file set with data files.

POST

/datafilesets#multipart creates the data file set and uploads the zip file to it.

GET

/datafilesets/{datafilesetcode} retrieves the data file set.

POST

/datafilesets/{datafilesetcode} adds the data file to the data file set.

DELETE

/datafilesets/{datafilesetcode} deletes the data file set.

GET

/datafilesets/{datafilesetcode}/zip retrieves the zip file of the data file set.

POST

/datafilesets/{datafilesetcode}/zip adds the zip file to the data file set.

This integration point validates and accepts only the ZIP file format as input.
If an invalid file is uploaded, HTTP status code 415 - Unsupported Media Type will be returned.

PUT

/datafilesets/{datafilesetcode}/zip zips the contents of all data files in the data file set.

PUT

/datafilesets/{datafilesetcode}/unzip unzips the contents of all data files in the data file set.

PUT

/datafilesets/{datafilesetcode}/datafiles updates the data file in the data file set.

DELETE

/datafilesets/{datafilesetcode}/datafiles/{datafilecode} deletes the data file from the data file set.

GET

/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data retrieves the data file content.

POST

/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data adds the data file content.

This integration point validates and accepts only XML, JSON, CSV, and TXT file formats as input.
If an invalid file is uploaded, HTTP status code 415 - Unsupported Media Type will be returned.

The generic datafilesets API supports, in addition to the standard generic API operations, the GET and the PATCH operation on /generic/datafilesets/key/{key}. This enables retrieving and updating a datafileset based on its datafileset code.

Create a Data File Set with Data Files in a Single Request

The POST operation on /datafilesets enables the client to create a data file set with one or more data files, together with the data file contents, in one request.

Example of a Request Message to Create a Data File Set with two Data Files (click to open)

{
  "code": "myfileSet",
  "description": "This is a Data File Set example",
  "locked": false,
  "dataFiles": [
    {
      "code": "fileCode1",
      "filePath": "",
      "descr": "This is file 1"
     },
    {
      "code": "fileCode2",
      "filePath": "",
      "descr": "This is file 2",
     }
  ]
}

This request creates the data file set holding two data files. The data files do not (yet) have any content.

We recommend uploading files with sizes under 20 MB. Larger files impact the stability of the system.

The response message

Example of a Response Message for a Data File Set Creation

{
  "code": "myfileSet",
  "description": "This is a Data File Set example",
  "locked": false,
  "links": [
     {
       "href": "http://[hostName]:[portNumber]/[api-context-root]/datafilesets/myfileSet",
       "rel": "self",
       "httpMethod": "GET"
     },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/datafilesets/myfileSet",
      "rel": "datafileset",
      "httpMethod": "GET"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/datafilesets/myfileSet/zip",
      "rel": "file",
      "httpMethod": "POST"
    }
  ]
}

In case of failure the response will be as specified in the standard structure under "Indicating Failure" in Response Messages

Create a Data File Set with Data Files in Conversation Mode

In this scenario the client performs the following steps:

Create data file set, optionally with one or more files.
Add data file to the data file set, if not already created with the data file set.
Add file content.

Step 1: Create Data File Set

This request enables an external system to create a data file set.

Request Message

The create data file set request will have the following structure:

<dataFileSet code="" description=""/>

Response Message

The create data file set success response will have the following structure:

<dataFileSet code="">
  <links>
    <link rel="self" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}" httpMethod="GET"/>
    <link rel="datafileset" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}" httpMethod="GET"/>
    <link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/zip" httpMethod="POST"/>
  </links>
</dataFileSet>

The client can use the links in the response to perform further actions on the data file set.

Step 2: Create Data Files in a Data File Set

A data file can be created within a previously created data file set by posting a request to the URI received in the response of "Create Data File Set request"

uri="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}".

We recommend uploading files with sizes under 20 MB. Larger files impact the stability of the system.

Request Message

The create file within a data file set request will have the following structure:

<dataFile
  code=""
  description=""
  filePath="" -- File path can be supplied for reference purposes. The file content is uploaded through a POST operation
/>

Response Message

The create file within a data file set success response will have the following structure:

<dataFileSet code="">
  <links>
    <link rel="self" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}" httpMethod="GET"/>
    <link rel="datafileset" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}" httpMethod="GET"/>
    <link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/zip" httpMethod="POST"/>
    <link rel="zip" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/zip?deleteDataFiles=true" httpMethod="PUT"/>
  </links>
  <dataFiles>
    <dataFile code="">
      <links>
        <link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data"/>
      </links>
    </dataFile>
  </dataFiles>
</dataFileSet>

If the code for the data file set or data file is omitted a system generated number will be used instead.

Optional: Create Data File Set With a Data File

A data file set with a data file can be created directly with a single request. This will create a data file set with one data file or multiple data files.

Request Message

The create data file set with a data file request will have the following structure:

<dataFileSet code="" description="">
  <dataFiles>
    <dataFile code="" description="" filePath=""/>
    ...
  </dataFiles>
</dataFileSet>

Response Message

The create data file set with file success response will have the following structure:

<dataFileSet code="">
  <links>
    <link rel="self" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}"/>
    <link rel="datafileset" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}"/>
  </links>
  <dataFiles>
    <dataFile code="">
      <links>
        <link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data"/>
      </links>
    </dataFile>
    ...
  </dataFiles>
</dataFileSet>

Step 3: Add Data to Data File

Data file contents can be submitted to the URI which was received as the response of Step 2, that is,

http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data.

The file structure as expected by various activities is documented in the specifications of file import based integration points.

Response Message

The add content to data file request' success response will have appropriate HTTP status code in the header and the following structure:

<dataFileSet code="">
  <links>
    <link rel="self" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}" httpMethod="GET"/>
    <link rel="datafileset" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}" httpMethod="GET"/>
    <link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/zip" httpMethod="POST"/>
    <link rel="zip" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/zip?deleteDataFiles=true" httpMethod="PUT"/>
  </links>
  <dataFiles>
    <dataFile code="">
      <links>
        <link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data"/>
     </links>
    </dataFile>
  </dataFiles>
</dataFileSet>

For all of the above-mentioned steps, in case of failure the response will be as specified in the standard structure under "Indicating Failure" in Response Messages.

Example: a result message for file content that could not be added as the data file code was unknown will have the following structure.

<resultMessages result="F">
    <resultMessage code="DAT-IP-DAFI-005">
     DAT-IP-DAFI-005:Data file code abc is unknown to data file set pqr.
    </resultMessage>
</resultMessages>

Zip and Unzip

The contents of all data files in a data file set can be zipped by having the client invoke the "zip" link. For creating a zip file the following options can be specified as query parameter with the request:

deleteDataFiles: when set to true (the default) the data files in the data file set will be deleted after the zip file is created.

For data file sets with zip files response messages contain a link for downloading the zip file.

A zip file can be uploaded with the request for creating a data file set. Alternatively, a zip file can be added to the data file set at a later stage by posting the contents to the "datafilesets/{datafilesetcode}/zip/" resource (very similar to posting data file contents).

An uploaded zip file can only contain text files, it should not contain binary files.

A zip file for a data file set can be unzipped by having the client invoke the "unzip" link (that is available in a response when a zip file exists for a data file set). The unzip operation creates a data file for each file in the zip file. For unzipping the following options can be specified as query parameter with the request:

deleteExistingDataFiles: when true any existing data files in the data file set are removed before unzipping.
deleteZipFile: when true the zip file is removed after unzipping.

Antivirus Scanning

Antivirus scanning is essential to prevent malicious files from being uploaded and potentially executing malware on other users' machines. The OHI Cloud Service uses Internet Content Adaptation Protocol (ICAP) servers to scan files for viruses.

How it Works

When files are uploaded using the Data File Set IP, antivirus scanning is automatically initiated in the background if the ohi.antivirus.scan.enabled property is set to true.
All data files will undergo malware scanning. Files deemed clean will be marked as Ready and can be downloaded or processed. If malware is detected, files will be marked as Quarantined and unavailable for download or processing. In cases where scanning is skipped due to technical issues or ICAP service unavailability, files will be marked as Skipped. Although these files have not been scanned, they can still be downloaded and processed.
You can monitor the scan status using the Data Files and Data File Sets generic API, which returns the status and extraInfo in the response body.

The scan status can have the following values:

Initial (IN): The data file has been created but has not yet been uploaded.
Uploaded (UP): The file has been successfully uploaded.
Scanning (SC): The antivirus scan is in progress.
Ready (RD): The antivirus scan was successful.
Quarantined (QT): The antivirus scan failed.
Skipped (SK): The antivirus scan failed due to a technical exception or ICAP server downtime.

Response field extraInfo

If the antivirus scan fails, the reason provided by ICAP will be stored in the extraInfo field.

The ohi.antivirus.scan.enabled property must be set in the properties file, not using the Properties API.
On-premises customers should set this property to false in the properties file.
The status and extraInfo response fields will not be populated for on-premises customers.

Other Available Operations

Send a GET request to /datafilesets/metadata for additional operations for this API.

Error Messages

The following error messages, that are specific to the data file set integration point may be returned in the response messages:

Table 1. Error Messages
Message Code	Severity	Message
DAT-IP-DAFI-001	Fatal	Data file set code {0} already exists
DAT-IP-DAFI-002	Fatal	Data file code {0} already exist within the data file set
DAT-IP-DAFI-003	Fatal	Data file set code {0} is unknown
DAT-IP-DAFI-004	Fatal	Data file set code {0} is locked for modification
DAT-IP-DAFI-005	Fatal	Data file code {0} is unknown to data file set {1}
DAT-IP-DAFI-011	Fatal	Content of data file {0} is invalid. For further information check extraInfo on the data file
DAT-IP-DAFI-012	Informative	Data file {0} is not ready to download. Please wait until the file is scanned for viruses
DAT-IP-DAFI-013	Fatal	Zip file of data file set {0} is invalid. For further information check extraInfo on the data file
DAT-IP-DAFI-014	Informative	Data file set {0} is not ready to download. Please wait until the file is scanned for viruses
DAT-IP-DAFI-015	Informative	Data file set {0} is not ready to unzip. Please wait until the file is scanned for viruses
DAT-IP-DAFI-016	Informative	Data file {0} is not ready to be zipped. Please wait until the file is scanned for viruses

1. For example, use the Relation Import activity type to process the file based request for relation integration point