Data File Set Integration Point

OHI applications support file based import operations. Uploading the files and processing the file contents is a two step process:

Load the files using the Data File Set Integration Point.
Process the file contents by initiating the proper activity type using the Activity Integration Point or through the UI.

The data file set integration point allows uploading of the files in the following ways:

Through multiple request-response based conversation mode.
Through a single request by creating the data file set and loading multiple data files.

Creating a data file set with one or more files in conversation mode

(multiple requests).

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://host:port/api/datafilesets/{datafilesetcode}' httpMethod='GET'/>
    <link rel='datafileset' href='http://host:port/api/datafilesets/{datafilesetcode}' httpMethod='GET'/>
    <link rel='file' href='http://host:port/api/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://host:port/api/datafilesets/{datafilesetcode}".

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://host:port/api/datafilesets/{datafilesetcode}' httpMethod='GET'/>
    <link rel='datafileset' href='http://host:port/api/datafilesets/{datafilesetcode}' httpMethod='GET'/>
    <link rel='file' href='http://host:port/api/datafilesets/{datafilesetcode}/zip' httpMethod='POST'/>
    <link rel='zip' href='http://host:port/api/datafilesets/{datafilesetcode}/zip?deleteDataFiles=true' httpMethod='PUT'/>
  </links>
  <dataFiles>
    <dataFile code=''>
      <links>
        <link rel='file' href='http://host:port/api/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://host:port/api/datafilesets/{datafilesetcode}'/>
    <link rel='datafileset' href='http://host:port/api/datafilesets/{datafilesetcode}'/>
  </links>
  <dataFiles>
    <dataFile code=''>
      <links>
        <link rel='file' href='http://host:port/api/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. i.e

 'http://host:port/api/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’s success response will have appropriate HTTP status code in the header and the following structure:

<dataFileSet code=''>
  <links>
    <link rel='self' href='http://host:port/api/datafilesets/{datafilesetcode}' httpMethod='GET'/>
    <link rel='datafileset' href='http://host:port/api/datafilesets/{datafilesetcode}' httpMethod='GET'/>
    <link rel='file' href='http://host:port/api/datafilesets/{datafilesetcode}/zip' httpMethod='POST'/>
    <link rel='zip' href='http://host:port/api/datafilesets/{datafilesetcode}/zip?deleteDataFiles=true' httpMethod='PUT'/>
  </links>
  <dataFiles>
    <dataFile code=''>
      <links>
        <link rel='file' href='http://host:port/api/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>

Creating a data file set with multiple files in a single request

As an alternative to creating the data file set in the 'conversational' mode, the data file sets endpoint offers the client the ability to create a data file set with one or more data files, together with the file contents, in one request.

This feature requires the client to POST a so called multipart request message that contains the following parameters:

The "dataFileSetCode" that contains the unique code for the data file set that will be created.
One or more "file" parameters that contain the file contents along with file metadata.

Multipart requests can be constructed with various technologies. The following is an example in HTML:

In an HTML based UI the following sample form could be used to create a data file set with code as "myfileSet" and upload two files with code "fileCode1" and "fileCode2" in one request:

<html>
  <form name="formtest" action="/filesets/multipart" method="POST" enctype="multipart/form-data">
    <input type="text" name="dataFileSetCode" value="myfileSet" />
    <input type="file" name="fileCode1" value="" />
    <input type="file" name="fileCode2" value="" />
    <input type="submit" value="Submit" />
  </form>
</html>

The system’s response to this request will have the following structure:

<dataFileSet code='myfileSet'>
  <links>
    <link rel='self' href='http://host:port/api/datafilesets/myfileSet' httpMethod='GET'/>
    <link rel='datafileset' href='http://host:port/api/datafilesets/myfileSet' httpMethod='GET'/>
    <link rel='file' href='http://host:port/api/datafilesets/myfileSet/zip' httpMethod='POST'/>
    <link rel='zip' href='http://host:port/api/datafilesets/myfileSet/zip?deleteDataFiles=true' httpMethod='PUT'/>
  </links>
  <dataFiles>
    <datafile code='fileCode1'>
      <links>
        <link rel='file' href='http://host:port/api/datafilesets/myfileSet/datafiles/fileCode1/data'/>
      </links>
    </datafile>
    <datafile code='fileCode2'>
      <links>
        <link rel='file' href='http://host:port/api/datafilesets/myfileSet/datafiles/fileCode2/data'/>
      </links>
    </datafile>
  </dataFiles>
</dataFileSet>

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

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).

Warning: 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

See the "/datafilesets/metadata" for additional operations for this IP.

Error Messages

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

Scenario	Message code	Message	Severity
Create a data file set	DAT-IP-DAFI-001	Data file set code {0} already exists	Fatal
Create data file within a data file set.	DAT-IP-DAFI-002	Data file code {0} already exist within the data file set	Fatal
Update/Delete/Get a data file set or Update/Delete/Get file within a data file set.	DAT-IP-DAFI-003	Data file set code {0} is unknown	Fatal
Update/Delete a data file set or Update/Delete file within a data file set.	DAT-IP-DAFI-004	Data file set code {0} is locked for modification	Fatal
Update/Delete/Get data file within a data file set.	DAT-IP-DAFI-005	Data file code {0} is unknown to data file set {1}	Fatal

Scenario

Message code

Message

Severity

Create a data file set

DAT-IP-DAFI-001

Data file set code {0} already exists

Fatal

Create data file within a data file set.

DAT-IP-DAFI-002

Data file code {0} already exist within the data file set

Fatal

Update/Delete/Get a data file set or Update/Delete/Get file within a data file set.

DAT-IP-DAFI-003

Data file set code {0} is unknown

Fatal

Update/Delete a data file set or Update/Delete file within a data file set.

DAT-IP-DAFI-004

Data file set code {0} is locked for modification

Fatal

Update/Delete/Get data file within a data file set.

DAT-IP-DAFI-005

Data file code {0} is unknown to data file set {1}

Fatal