Input Resources

Input Resources use the PUT, GET, and DELETE operations. The validation and the translation processes function in different manners.

In the validation process, the input includes an EDI datafile and a guideline. It requires several other optional files.

In the translation process, the input includes an EDI or XML datafile and a map file. In addition, it must have a source and target schema or guidelines.

The Foresight REST API server requires the following Input Resources:

Guidelines

A guideline resource is either represented as a SEF (.sef or .std extension) or an XML schema (.xsd extension). If an extension is not specified in the Foresight REST API command, the system first looks for a file with a .std extension. If not found, it searches for a file with a .sef extension.

Three Foresight REST API operations are supported for guideline resources: PUT, GET, and DELETE.

Using the PUT operation

The user can utilize the PUT operation to upload guidelines to the Foresight REST API server for use in a subsequent job operation. All guidelines uploaded through the PUT operation go into the Database folder under the Foresight REST API server’s guidelines directory.

  1. REST Path

    .../guidelines/guidelineFileName

    .../guidelines/zip/zipFileName

  2. Optional Parameters

    overwrite=Y

    If a guidelineFileName exists on the server, the server rejects the request unless this optional parameter is specified.

  3. Request Body: guideline file (Media Type=application/octet-stream)

    Note: To upload multiple guidelines, provide a zip file as an input.

  4. Possible Responses

    Response Description
    200 OK The guideline upload is successful.
    400 Bad Request

    Problem with the request (missing guideline ID) or with the guideline that is sent (does not appear to be a .sef file); see the response body for the reason.
    409 Conflict The guideline cannot be overwritten; see the response body for additional information.
    415 Unsupported Media Type The guideline PUT supports a media type of ‘application/octet-stream’ only.
    500 Internal Server Error The server had problems writing files; see the response body for the reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/guidelines/TEST835.std

    2. http://SERVX:8080/ForesightREST/guidelines/TEST835.std?overwrite=Y

Using the GET operation

The GET operation is used to

  • Get the information about a specific guideline file on the Foresight REST API server, or

  • Get a list of all the guidelines on the Foresight REST API server.

For specific guideline GETs, the following information is returned in the response body:

{
    "stdFileInfo": "20220228 072106.000+0530/139350",
    "internalId": "834AA120",
    "stdDate": "07/27/110:15:56:54",
    "size": "139350",
    "guidelinePath": "\\usr\\local\\tomcat\\TibcoFSRest\\guidelines\\Database\\834AA120.std",
    "id": "834AA120",
    "type": "X12",
    "desc": "Types 1-2,  Addenda October, 2002 Included;  Benefit Enrollment and Maintenance (834-A1)",
    "fileMod": "20220228 072106.000+0530"
}

  1. REST Path

    1. For a specific guideline

      .../guidelines/guidelineFileName

    2. For a list of all the guidelines

      .../guidelines

    3. For bytecode of zip file of all the guidelines

      ../guidelines?multiple=Y

  1. Optional Parameters

    1. full=Y

      For a specific guideline, where the guideline body is desired and installation permits it, this option causes the server to return the .std/.sef file contents in the response body (media type=Application/Octet-Stream). If requesting a list of all the guidelines, this parameter is ignored.

    2. multiple=Y

      To get the bytecode of the zip file of all the guidelines.

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The guideline information retrieval (or full guideline retrieval) is successful; response body contains the information. For full retrieval, the body contains the contents of the guideline requested from the server. For a normal GET, the body contains the information about the guideline file on the server.
    400 Bad Request Problem with the request (such as missing guideline id); see the response body for reason.
    403 Forbidden The specified guideline is a ‘Factory’ guideline and cannot be downloaded.
    404 Not Found The specified guidelines cannot be found on the server.
    415 Unsupported Media Type The guideline GET supports media types of ‘application/octet-stream’ and ‘text/plain’.
    500 Internal Server Error The server had problems reading the file; see the response body for reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/guidelines/PDSA837I

      Response Body:

      {
    "stdFileInfo": "20201022 081648.000-0500/755533",
    "internalId": "5010-837I_TRANS",
    "stdDate": "08/26/109:15:34:38",
    "size": "755533",
    "guidelinePath": "c:\\FSREST\\guidelines\\Database\\5010-837I_TRANS.std",
    "id": "5010-837I_TRANS",
    "type": "X12",
    "desc": "Types 1-2, Health Care Claim: Institutional (837I), Version 5, Release 1, Errata (OCT 2007)",
    "fileMod": "20201022 081648.000-0500"
}

    2. http://SERVX:8080/ForesightREST/guidelines

      Response Body: 

      PDSA837I.std 210-X12-4030
269X187Q
269X187R
270-A120
270-X279
270AA120
271-A120
271-X279
271AA120
275-X151
275-X210
275-X314
…
X12-6030 (Factory) X12-6031 (Factory) X12-6032 (Factory) X12-6040 (Factory) X12-6041 (Factory) X12-6042 (Factory) X12ICS (Factory) XHL7
XML_PO_F
Note: While retrieving files having '?' in the name, the '?' must be replaced by '%3F'.

Using the DELETE operation

The DELETE operation is used to remove a guideline resource from the Foresight REST API server, if permitted by the installation.

  1. REST Path: .../guidelines/guidelineFileName

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The guideline is deleted successfully.
    400 Bad Request Problem with request (missing guideline id, and so on.); see the response body for reason.
    409 Conflict The specified guideline resources cannot be deleted; see the response body for additional information.
    500 Internal Server Error The server had problems writing the files; see the response body for the reason.

Datafiles

A datafile resource is a data file to be validated. Three Foresight REST API operations are supported for datafile resources: PUT, GET, and DELETE

Using the PUT operation

The PUT operation is used to upload a data file to the Foresight REST API server for use in a subsequent job operation. All data files uploaded through this PUT operation go into the Foresight REST API server’s datafile directory.

  1. REST Path

    .../datafiles/dataFileName

    .../datafiles/zip/zipFileName

  1. Optional Parameters

    1. overwrite=Y

      If a data file being datafilename exists on the server, the server rejects the request unless this optional parameter is specified.

  1. Request Body: data file (Media Type=application/octet-stream)

  2. Possible Responses

    Response Description
    200 OK The data file upload is successful.
    400 Bad Request Problem with the request (missing data file name, and so on.); see the response body for the reason.
    409 Conflict The data files cannot be overwritten; see the response body for additional information.
    415 Unsupported Media Type The data file PUT supports a media type of ‘application/octet-stream’ only.
    500 Internal Server Error The server had problems writing files; see the response body for the reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/datafiles/TESTData.txt

    2. http://SERVX:8080/ForesightREST/datafiles/FlatFile.dat?overwrite=Y

Using the GET operation

You can use the GET operation to:

  • Get the information about (or the contents of) a specific data file on the Foresight REST API server, or

  • Get a list of all the datafiles on the Foresight REST API server.

For specific data file GET, the following information is returned in the response body:

  • File name

  • File size

  • File creation date and time

  • File last modification date and time

Note: The information is in a single line and the fields are tab delimited. When a list of all the control files is requested, multiple lines of the same information are returned, one line per file.

  1. REST Path

    1. For a specific data file

      .../datafiles/dataFileName

    2. For a list of all the datafiles

      .../datafiles

    3. For bytecode of zip file of all the datafiles

      ../datafiles?multiple=Y

  1. Optional Parameters

    1. full=Y

      If requesting a specific data file, and the actual contents of the data file is desired, and the installation permits it, then specifying this option causes the server to return the contents of the specified data file in the response body (media type=Application/Octet-Stream). If requesting a list of all the datafiles, this parameter is ignored.

    2. multiple=Y

      To get the bytecode of the zip file of all the datafiles.

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The data file information retrieval (or full data file retrieval) is successful; response body contains the information. For full retrieval, the body contains the contents of the datafile requested from the server. For a normal GET, the body contains the information about the data file on the server.
    400 Bad Request Problem with the request (missing data file name, and so on); see the response body for the reason.
    404 Not Found The specified data files cannot be found on the server.
    415 Unsupported Media Type The data file GET supports media types of ‘application/octet-stream’ and ‘text/plain’.
    500 Internal Server Error The server had problems reading the file; see the response body for the reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/datafiles/837I_4010_H_6claims.txt

      Response Body:

      837I_4010_H_6claims.txt    7179 2019-05-22T21:13:30.214054Z 2017-07-25T23:42:52Z

    2. http://SERVX:8080/ForesightREST/datafiles

      Response Body:

      [
    {
        "fileName": "1_D3_CONTRL.dat",
        "size": "0",
        "created": "2023-10-18T18:17:26.8185517Z",
        "modified": "2021-10-06T21:48:49.3641381Z"
    },
    {
        "fileName": "1_D3_CONTRL_updated.dat",
        "size": "386",
        "created": "2023-10-18T18:17:26.8315535Z",
        "modified": "2021-03-01T17:51:48.3834129Z"
    },
    {
        "fileName": "270_4010_H_3InfoSrc_Clean.txt",
        "size": "3007",
        "created": "2023-10-18T18:17:26.8585517Z",
        "modified": "2023-12-14T22:29:18.1016401Z"
    },
    {
        "fileName": "270_5010_H_BadReceiverID.txt",
        "size": "611",
        "created": "2023-10-18T18:17:26.8705518Z",
        "modified": "2023-12-14T22:29:18.1106405Z"
    },
    {
        "fileName": "271_4010_H_2InfoSrc_Clean.txt",
        "size": "2060",
        "created": "2023-10-18T18:17:26.8835588Z",
        "modified": "2023-12-14T22:29:18.1156392Z"
    },
    {
        "fileName": "2Interchanges837i.txt",
        "size": "4042",
        "created": "2023-10-18T18:17:26.8455512Z",
        "modified": "2023-09-13T22:38:40.8527996Z"
    },
    {
        "fileName": "bkup",
        "size": "24576",
        "created": "2023-12-18T03:06:42.1330487Z",
        "modified": "2023-12-18T03:06:46.0144448Z"
    }
]
Note: While retrieving files having '?' in the name, the '?' must be replaced by '%3F'.

Using the DELETE operation

The DELETE operation is used to remove a data file resource from the Foresight REST API server, if permitted by the installation.

  1. REST Path: .../datafiles/dataFileName

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The specified data file is deleted successfully.
    400 Bad Request Problem with request (missing data file name, and so on); see the response body for the reason.
    409 Conflict The specified data file resources cannot be deleted; see the response body for additional information.
    500 Internal Server Error The server had problems deleting the file; see the response body for the reason.

Controlfiles

A controlfile resource is a supporting file used by the Foresight Instream processes. Some examples include custom .apf files, Response Generator, custom report template files, and so on.

Three Foresight REST API operations are supported for controlfiles resources: PUT, GET, and DELETE.

Using the PUT operation

The PUT operation is used to upload a control file to the Foresight REST API server for use in a subsequent Job operation. All control files uploaded through this PUT operation go into the Foresight REST API server’s controlfile directory.

  1. REST Path

    .../controlfiles/controlFileName

    .../controlfiles/zip/zipFileName

  1. Optional Parameters

    overwrite=Y

    If a control file being ‘PUT’ exists on the server, the server rejects the request unless this optional parameter is specified.

  2. Request Body: controlfile (Media Type=application/octet-stream)

    Note: To upload multiple guidelines, provide a zip file as an input.

  3. Possible Responses

    Response Description
    200 OK The control file upload is successful.
    400 Bad Request Problem with request (missing control file name, and so on); see the response body for the reason.
    409 Conflict The control file cannot be overwritten; see the response body for additional information.
    415 Unsupported Media Type The control file PUT supports a media type of ‘application/octet-stream’ and ‘text/plain’.
    500 Internal Server Error The server had problems writing a file; see the response body for the reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/controlfiles/TESTErrs.apf

    2. http://SERVX:8080/ForesightREST/controlfiles/MyCustRespTemplate.txt? overwrite=Y

Using the GET operation

You can use GET operation to:

  • Get the information about a specific control file on the Foresight REST API server,

  • Get a list of all the control files on the Foresight REST API server.

For specific data file GETs, the following information is returned in the response body:

  • File name

  • File size

  • File creation date and time

  • File last modification date and time

Note: The information is in a single line and the fields are tab delimited. When a list of all the control files is requested, multiple lines of the same information are returned, one line per file.

  1. REST Path

    1. For a specific control file

      .../controlfiles/controlFileName

    2. For a list of all control files

      .../controlfiles

    3. For bytecode of zip file of all the controlfiles

      ../controlfiles?multiple=Y

  1. Optional Parameters

    1. full=Y

      If requesting a specific control file, and the actual contents of the control file is desired, and the installation permits it, then specifying this option causes the server to return the contents of the specified control file in the response body (media type=Application/Octet-Stream). If requesting a list of all the control files, this parameter is ignored.

    2. multiple=Y

      To get the bytecode of the zip file of all the controlfiles.

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The control file information retrieval is successful; the response body contains the information. For full retrieval, the body contains the contents of controlfile requested from the server. For a normal GET, the body contains the information about the control file on the server.
    400 Bad Request Problem with request (missing control file name, and so on); see the response body for the reason.
    404 Not Found The specified control files cannot be found on the server
    415 Unsupported Media Type The control file GET supports media types of ‘application/octet-stream’ and ‘text/plain’.
    500 Internal Server Error The server had problems reading the file; see the response body for the reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/controlfiles/Phase2.apf

      Response Body:

      Phase2.apf    6779 2019-05-10T23:41:03.629214Z 2019-05-11T03:09:22Z

    2. http://SERVX:8080/ForesightREST/controlfiles

      Response Body:

      RGtemplate837I_c.txt 337  2019-05-22T21:13:30.192058Z 2017-07-25T23:42:52Z
      test.apf   8416 2019-05-08T19:30:56.601053Z 2019-05-08T19:36:06.433946Z
      test2.apf     9416 2019-05-08T19:33:48.212871Z 2019-05-08T19:36:06.433946Z
Note: While retrieving files having '?' in the name, the '?' must be replaced by '%3F'.

Using the DELETE operation

The DELETE operation is used to remove a controlfile resource from the Foresight REST API server, if permitted by the installation.

  1. REST Path: .../controlfiles/controlFileName

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The specified control file is deleted successfully.
    400 Bad Request Problem with the request (missing control file name, and so on); see the response body for the reason.
    409 Conflict The specified control file resources cannot be deleted; see the response body for additional information.
    500 Internal Server Error The server had problems deleting the file; see the response body for the reason.

Maps

A map resource is a translation map file used by the Foresight Translator processes. A map resource connects the fields between different formats.

Three Foresight REST API operations are supported for mapping resources: PUT, GET, and DELETE

Using the PUT operation

The PUT operation is used to upload a map file to the Foresight REST API server for use in a subsequent job translation operation. All map files uploaded through this PUT operation go into the Foresight REST API server’s maps directory.

  1. REST Path

    .../maps/mapFileName

    .../maps/zip/zipFileName

  1. Optional Parameters

    overwrite=Y

    If a map file being ‘PUT’ exists on the server, the server rejects the request unless this optional parameter is specified.

  2. Request Body: map file (Media Type=application/octet-stream)

    Note: To upload multiple guidelines, provide a zip file as an input.

  3. Possible Responses

    Response Description
    200 OK The map file upload is successful.
    400 Bad Request Problem with request (missing map file name, and so on); see the response body for the reason.
    409 Conflict The map file cannot be overwritten; see the response body for additional information.
    415 Unsupported Media Type Maps PUT supports a media type of ‘application/octet-stream’ and ‘text/plain’.
    500 Internal Server Error The server had problems writing files; see the response body for the reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/maps/837EtoX.map

    2. http://SERVX:8080/ForesightREST/maps/810XMLtoEDI.map? overwrite=Y

Using the GET operation

You can use GET operation to:

  • Get the information about a specific map file on the Foresight REST API server, or

  • Get a list of all the map files on the Foresight REST API server.

For specific data file GETs, the following information is returned in the response body:

  • ID = File name

  • mapPath = Full path to map file

  • fileInfo = File Last Modification Date and Time/Size

When a list of all the map files is requested, map file names are returned one line per file.

  1. REST Path

    1. For a specific map file

      .../maps/mapFileName

    2. For a list of all the map files

      .../maps

    3. For bytecode of zip file of all the maps

      ../maps?multiple=Y

  1. Optional Parameters

    1. full=Y

      If requesting a specific map file, and the actual contents of the map file is desired, and the installation permits it, then specifying this option causes the server to return the contents of the specified map file in the response body (media type=Application/Octet-Stream). If requesting a list of all the map files, this parameter is ignored.

    2. multiple=Y

      To get the bytecode of the zip file of all the maps.

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK

    The map file information retrieval (or full map file retrieval) is successful; response body contains the information. For full retrieval, the body contains the contents of the map file requested from the server. For a normal GET, the body contains the information about the map file on the server.
    400 Bad Request Problem with request (missing map file name, and so on); see response body for the reason.
    404 Not Found The specified map files cannot be found on Server.
    415 Unsupported Media Type The map file GET supports media types of ‘application/octet-stream’ and ‘text/plain’.
    500 Internal Server Error The server had problems reading the file; see the response body for the reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/maps/Phase2.apf (application/json)

      Response Body:

      {
"fileInfo": "20230403 090358.658-0400/244966",
"id": "origMapFile",
"mapPath": "C:\\FSRest\\maps\\origMapFile.map"
}

    2. http://SERVX:8080/ForesightREST/maps (text/plain)

      Response Body:

      837-X222_837_EX.map
837-X223_EX.map
837-X223_XE.map
850_4010_02_GG_DEMO_850_EX.map origMapFile.map
Note: While retrieving files having '?' in the name, the '?' must be replaced by '%3F'.

Using the DELETE operation

The DELETE operation is used to remove a map file resource from the Foresight REST API server, if permitted by the installation.

  1. REST Path: .../maps/mapFileName

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The specified map file is deleted successfully.
    400 Bad Request Problem with request (missing map file name, and so on); see response body for the reason.
    409 Conflict The specified map file resources cannot be deleted; see the response body for additional information.
    500 Internal Server Error The server had problems deleting the file; see the response body for the reason.