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

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

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

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.

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}

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