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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
{
"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:
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} |