Processing and Output Resources

The processing of the resources and generating output involves various JOB operations. The PUT, GET, and DELETE operations support the processing of resources. The GET and DELETE operations support output generation.

Jobs

A job resource is required to perform any operation. The POST operation creates a job resource on the Foresight REST API with a body that contains the following information necessary to define the work to be done.

  • Guideline ID

  • Data file name

  • Any special controlfiles needed

  • Any response documents desired

    The response from a job POST is the job ID assigned to the job. This Job ID helps to obtain the job’s status, along with any output files generated.

    Three operations are supported for job resources: POST, GET, and DELETE

POST

The POST operation is used to convey a message to the Foresight REST API server to initiate a job to perform some work. The body of the POST request contains the parameters of the work to be done.

  1. REST Path

    .../jobs

  2. When this parameter is included in the POST request, the results detail file (dtl) is copied to the shared file folder.

  3. Request Body: (Media Type = text/plain)

    The request body contains lines of job parameters in the format key=value. The various parameters are:

    Parameter Key

    Area

    Description

    Example

    Corresponding Java API Member

    JobID

    All

    Specify the Foresight REST API Job ID to use for the job instead of an automatic job ID. For details, see JobID.

    JobId=Test8

     

    Mode

    All

    Sets the processing mode for the job. For details, see Mode . The mode must be one of the following:

    ASYNC: Asynchronous operation (Default)

    ASYNCN: Asynchronous operation with notification on completion

    ASYNCO: Asynchronous operation with notification, including contents of Response Files and Translated Files on completion

    SYNC: Synchronous operation

    SYNCO: Synchronous operation, including Response Files and Translated Files contents on completion.

    Mode=SYNCO

     

    Ops (Required)

    All

    Main Job operations and sequence. For details, see Ops. The Ops must be one of the following:

    I = Instream

    T = Translation

    IT = Instream then Translation

    TI = Translation then Instream

    Note: When a service request is submitted to REST API to invoke Instream and Translator, and only one product is installed, REST API only runs the installed product.

    Ops=IT (for inbound operation: Validate then translate)

     

    DatafileRef

    All

    The name of the data file to use.

    Note: DataFileRef is the same as InDataFileRef from the old Translator interface.

    Example: DatafileRef=ProdMedAData.edi

    InputFile (Instream), InputFile (Translator)

    Data

    All

    Includes the data to be validated or translated as part of the Job POST body. For details, see Data.

    “Data”: “ISA*...~IEA*1*0003”

     

    CallbackTag

    All

    Sets the value for the ‘tag’ field in guideline callbacks from the Foresight Instream and the Foresight Translator engines. (See, ICallbackTag, and TCallbackTag parameters, to set each engine’s tag value individually.)

    Callback=”inbound”

     

    senderName

    All

    Specify the sender name to use in any AuditSafe messages generated by Job.

    senderName=”ABC Trucking”

     

    receiverName

    All

    Specify the receiver name to use in any AuditSafe messages generated by Job.

    receiverName=”Woody’s Warehouse”

     

    Debug

    All

    Debug indicator to add additional logging to the Job. Setting to ‘Y’ causes a list of log messages to be attached to the job. These can be accessed as part of the job status information returned from a Job ‘GET’ operation.

    Debug=Y

     

    GuidelineRef

    Instream/ Validation

    Name of the guideline file to use.

    Example: GuidelineRef=X12-5010

    guideline

    SGuidelineRef

    Translator

    Name of the guideline file to use for the source (from) data. For more details, see Guidelines.

    Example: SGuidelineRef=MYX12.std

     

    TGuidelineRef

    Translator

    Name of the guideline file to use for the target (to) data. For more details, see Guidelines.

    Example: TGuidelineRef=MYXML.xsd

     

    Profile

    Instream/ Validation

    Name of profile (apf) file to use. For details, see Controlfiles.

    Example: Profile=MedPat1.apf

    profileOptions

    ValReportFormat

    Instream/ Validation

    Type of validation report format: XML or X = XML report

    TEXT or T = Text report (default)

    Example: ValReportFormat=XML

    InStreamOutputXml Format

    OrigFileInfo

    Instream/ Validation

    Original File Information in format 'mm/dd/yy hh:mm:ss nnnn path' where ‘mm/dd/yy hh:mm:ss’ is the file creation date and time, ‘nnnn’ is the file size, and ‘path’ is the original file path.

    OrigFileInfo=02/14/19 14:55:34 2032

    C:/HVInStream/DemoData

    /TestData.txt

    origFileInfo

    Separators

    Instream/ Validation

    String representing the segment terminator, element delimiter, and composite subelement delimiter characters. Three formats are allowed:

    1. ASCII decimal values separated by commas

    2. ASCII hexadecimal values separated by commas

    3. A string of three characters

    Examples: Separators=~!” Separators=29,30,31 Separators=0x1E,

    0x1F, 0x1D

    separator, avoidENV

    EnvIC

    Instream/ Validation

    Interchange segment to use for validation. Must be used with EnvFG.

    Example: EnvIC=ISA*00*

    *00*

    *01*9012345720000

    *01*9088877320000

    *120225*0856*+*00501*0 00002491*0*T*:~

    FSDOCUMENTON

    LY, envlopISA

    EnvFG

    Instream/ Validation

    Functional Group segment to use for validation. Must be used with EnvIC.

    Example: EnvGS=GS*HS*90123457 2000*908887732000*2012

    0225*1615*2491*X*0050

    10X279A1~

    FSDOCUMENTON

    LY, envGS

    StopOnEnvErr

    Instream/ Validation

    Stops the Foresight Instream validation process if enveloping errors are encountered during validation.

     

     

    ICallbackTag

    Instream/ Validation

    Sets the value for the ‘tag’ field in guideline callbacks from the Foresight Instream engine.

    ICallback=”inbound”

     

    TCallbackTag

    Translator

    Sets the value for the ‘tag’ field in guideline callbacks from the Translator engine.

    TCallback=”outbound”

     

    TThreadLock

    Translator

    Switches the Translator processing thread locking on or off for each job.

    Possible values:

    Y, YES, or 1: Turns on thread locking

    N, NO, or 0: Turns off thread locking

    Default: NO

    TThreadLock=Y

     

    RGDocs

    Instream/ ResponseGen

    Response documents desired. One or more of the following codes separated by commas:

    997 = X12 997 response

    999 = X12 999 response

    824 = X12 824 response

    277 = X12 277 response

    TA1 = X12 TA1 response

    CONTRL = EDIFACT CONTRL response

    TEXT = Custom text response (see RGTextTemplateFileRef)

    Example: RGDocs=999,277,TA1

    RG_Rep997, RG_Rep999, RG_Rep824, RG_Rep277, RG_Contrl, RG_TA1,

    RG_repText

    RGTextTemplateFileRef

    Instream/ ResponseGen

    The name of the template file to use if TEXT Document Type is specified in RGDocs. For details, see Controlfiles.

    Example: RGTextTemplateFileRef=S ummReportTemplate.txt

    RG_Reptemp

    RGOptions

    Instream/ ResponseGen

    String of Response Generator command-line arguments to use.

    Example: RGOptions=-ge-y

    RG_Options

    RGTPAFileRef

    Instream/ ResponseGen

    The name of the trading partner automation setup (.csv) file that is used to select a Response Generator Setup file. For details, see Controlfiles.

    Foresight REST API supports envelope-based Trading Partner Automation (TPA). The appropriate guideline and configuration files are automatically selected by using the IDs in the envelopes in the X12, EDIFACT, or TRADACOMS standard.

    Example: RGTPAFileRef=SampleTPA_DS_RG.csv

    RG_TradingPartner Automation

    DSProfile

    Instream/ DocSplitting

    Name of the DocSplitter INI file to use. For details, see Controlfiles.

    Example: DSProfile=DSProfMedB.in

    DS_Profile

    DSTPAFile

    Instream/ DocSplitting

    Name of the trading partner automation setup (.csv) file that is used to select a DocSplitter INI file. For details, see Controlfiles.

    Foresight REST API supports envelope-based TPA. The appropriate guideline and configuration files are automatically selected by using the IDs in the envelopes in the X12, EDIFACT, or TRADACOMS standard.

    Example: DSTPAFile=SampleTPA_DS_RG.csv

    DS_TradingPartner Automation

    DSDebugFlag

    Instream/ DocSplitting

    Turns on debug messages in the DocSplitter report

    Y = Turn on debug messages

    N = No debug messages (default)

     

    DS_ReportDebugOpt, DS_reportdebug

    DSReportFormat

    Instream/ DocSplitting

    Type of the DocSplitter report format XML = XML report

    CSV = Text report (default)

    Example: DSReportFormat=XML

    DS_ReportFormat

    DXProfile

    Instream/ DataExchange

    Name of the Data Exchange setup file to use. For details, see Controlfiles.

    Example: DXProfile=DXProfile1.ini

    DX_Profile

    TType (Required for operation involving translation: T, IT, TI. See Ops parameter)

    Translation

    Code that indicates the type of translation to be performed. Possible codes are:

    EE - EDI to EDI EX - EDI to XML

    EF - EDI to Flat XE - XML to EDI

    XF - XML to Flat FE - Flat to EDI FX - Flat to XML FF - Flat to Flat

    TType=XE

    Argument to convert routine

    InDatafileRef

    Translation

    Name of the input (From) data file to use. For details, see Datafiles.

    Example: InDatafileRef=ProdMedAData.edi

    InputFile
    MaxErrorsCount   When the validation errors reach the number, an error message displays in the Log, but the process proceeds. When the job is completed, the POST response as well as the message includes the same number of validation errors at most. MaxErrorsCount=100  
    copyResultsfile  

    When this parameter is included in the POST request, the results detail file (dtl) is copied to the shared file folder.

    Valid values:

    Y, or YES, and N or NO

    		 copyResultsfile=Y  
    publishReport Transaction Insight

    It enables Publish Information to Insight Reporting. publishReport must be working with CallbackTag parameter.

    Valid values:

    y, or Y, and n, or N

    		 publishReport=y  
    createTrk Transaction Insight

    It creates the track file. createTrk must work with publishReport.

    Valid values:

    y, or Y, and n, or N

    		 createTrk=y  

    JobID 

    Using the JobID parameter, the caller can specify the Job number to be used for that job. If omitted, the Foresight REST API creates one as usual, based on the Job Number algorithm type specified in the Foresight REST API config parameters. Currently, there is no limit in the format of the specified JobID. If a job with the specified ID exists on the Foresight REST API system, it appends the specified ID with a period followed by a counter until it finds a JobID that does not exist.

    For example, if ‘JobId=MYJOB’ is specified and there already exists a /jobs/MYJOB resource, the REST API will try ‘MYJOB.1’, ‘MYJOB.2’, ‘MYJOB.3’, and so on.

    Mode

    The Foresight REST API normally runs in asynchronous mode. When a job request is POSTed, Foresight REST API returns the assigned job and then process the job. The calling procedure checks back periodically to see if the job is done, and when the job is done, the user downloads the output files. A few more modes are available to give the calling routine more control over this process.

    The 'Mode' parameter has the format.

    ‘Mode=n’ (Text)

    or

    '"Mode": "n"'

    where ‘n’ is one of the following:

    Mode Description
    ASYNC (Default) Results in the standard asynchronous operation. When no mode is specified, this is the default mode.
    ASYNCN

    Similar to ASYNC, except that a notification is sent to an external server’s NotifyPostAddr Callback on job completion.
    ASYNCO

    Similar to ASYNCN, except that the notification is sent to an external server’s NotifyPostAddr Callback on job completion. It also includes a validation error summary (Instream), the contents of the response documents generated (RespGen), and the resulting files from any translation operations.
    SYNC Puts Foresight REST API into synchronous mode where it does return from the initial Job POST until the job is complete. On completion, the POST response contains the job completion information.
    SYNCO Similar to SYNC mode, except that the POST response also includes the contents of the following files (if any): Response files, Translated files.

    Ops

    Usually Foresight REST API can figure out the main operations to be done based on the Job POST options specified. There may be cases, however, where this is impossible, for example passing just a DatafileRef and counting on the Callback to handle the guideline or map. When both operations are desired, the order of the two codes indicates the processing order.

    For example: IT means Instream then Translate, TI means Translate then Instream. This parameter supports four values:

    I Instream operations (Validation, Response Generation, Doc Splitting, and Data Exchange)
    T Translation operations
    IT

    Instream operations are followed by translation operations. The Foresight REST API validates the input data file, and then translates error-free transaction sets.

    When Translator is not found, the "IT" operation fails, but the "I" operation runs.

    TI

    Translation operations are followed by Instream operations. The Foresight REST API translates the input data file, and then validates the resulting file.

    When Instream is not found, the "TI" operation fails, but the "T" operation runs.

    Data

    This parameter includes the data to be validated or translated as part of the Job POST body. When using the text parameter format, the data must be the last item in the Job POST, and must start with a single line ‘Data=’. The data then starts on the next line and runs to the end of the request. When using the JSON parameter format, the data parameter can occur anywhere in the Job POST body. When using the Data parameter, the DatafileRef parameter is optional. If present, the contents of the DatafileRef parameter are used in the Validation report as the data file name. If omitted, one is created by appending ‘_Data’ to the Job ID.

    Examples:

    Text Format

    RGDocs=997,TA1 Mode=ASYNCN
Debug=y Data=
ISA*00*    *00*    *01*9012345720000 *01*9088877320000
*120111*1212*U*00401*000004321*0*T*:~ GS*HC*901234572000*908887732000*20120111*1615*1*X*004010X096A1~ ST*837*0001~
BHT*0019*00*3920394930203*20120111*1615*CH~
… SE*29*0001~
GE*1*1~ IEA*1*000004321~

    JSON Format

    {
“Ops”: “I”,
“Mode”: “SYNCO”,
“RGDocs”: “997,TA1”,
 
“Data”:
“ISA*00*    *00*    *01*9012345720000 *01*9088877320000
*120111*1212*U*00401*000004321*0*T*:~\nGS*HC*901234572000*908887732000*20 120111*1615*1*X*004010X096A1~\nST*837*0001~\nBHT*0019*00*3920394930203*20
120111*1615*CH~\n…\nSE*29*0001~\nGE*1*1~\nIEA*1*000004321~”
}

  1. Possible Responses

    Response Description
    200 OK

    The job is started successfully. The response body contains the following information about the job:

    • Job ID

    • Date and time started

    • Guideline Name

    • Datafile Name

    The job ID is important because it is the key to further inquiries regarding the job and to the retrieval of any output files.
    400 Bad Request Problem with request (missing control file name, and so on); see the response body for reason.
    409 Conflict The control file cannot be overwritten; see the response body for additional information.
    415 Unsupported Media Type The controlfile PUT supports only a media type of ‘application/octet-stream’ and ‘text/plain’.
    500 Internal Server Error The server had problems writing a file; see response body for reason.

  1. Examples

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

      Request Body:

      GuidelineRef=PDSA837I
DatafileRef=837I_4010_H_6claims.txt
RGDocs=997,277,824,TEXT
RGTextTemplateFileRef=RGtemplate837I_c.txt
RGOptions=-ge

      Response Body:

      Job #: J190528165545_00001
Started at 05/28/2019 16:55:45.881
GuidelineRef: PDSA837I
DataFilename: 837I_4010_H_6claims.txt

    2. For JSON

      Request Body: 

      {
"GuidelineRef": "PCBS.std",
"DatafileRef": "837I_4010_H_5provider.txt",
"Mode": "SYNCO",
"Ops": "I",
"DSReportFormat": "xml",
"DSDebugFlag": "Y",
"DSProfile": "Content_Based_Split_Auto_Setup.ini"
}

      Response Body:

      {
    "invalidTxnCount": "1",
    "outputFiles": [
        "J231218224927_00001_DSInvalid_File0002.txt",
        "J231218224927_00001_DSReport.xml",
        "J231218224927_00001_DSValid_File0001.txt",
        "J231218224927_00001_DSValid_File0002.txt",
        "J231218224927_00001_DSValid_File0003.txt",
        "J231218224927_00001_DSValid_File0004.txt",
        "J231218224927_00001_DSValid_File0005.txt",
        "J231218224927_00001_VResult.txt",
        "Summary_J231218224927_00001_VResult.txt"
    ],
    "instreamMsgsBySeverity": "0,14,0,1,0,0,0",
    "started": "2023-12-18T22:49:27.819-06:00",
    "datafileRef": "837I_4010_H_5provider.txt",
    "completed": "2023-12-18T22:49:29.601-06:00",
    "mode": "SYNCO",
    "jobId": "J231218224927_00001",
    "ops": "I",
    "validTxnCount": "0",
    "instreamMsg": "",
    "instreamMsgsByWEDIType": "14,1,0,0,0,0,0,0,0",
    "instreamRCode": 100,
    "interchanges": [
        {
            "interchangeControlNumber": "000000545",
            "interchangeVersion": "00401",
            "groups": [
                {
                    "groupStartPos": "108",
                    "svalus": [],
                    "groupVersion": "004010X096A1",
                    "groupControlNumber": "545",
                    "groupEndPos": "7114",
                    "txns": [
                        {
                            "txnStartPos": "175",
                            "txnEndPos": "7103",
                            "svalus": [],
                            "txnControlNumber": "0545",
                            "evalus": [],
                            "errors": [
                                {
                                    "severity": "3",
                                    "segment": "DTP",
                                    "errorMessage": "Invalid Date/Time '20110323-20110323': Should match pattern 'CCYYMMDD'",
                                    "segmentLocation": "101",
                                    "errorSegment": "DTP*434*D8*20110323-20110323~",
                                    "loopGroup": "2300",
                                    "errorID": "31019",
                                    "loopGroupLocation": "1",
                                    "category": "Rejecting",
                                    "elementLocation": "3",
                                    "errorData": "20110323-20110323",
                                    "element": "1251"
                                }
                            ],
                            "txnID": "837"
                        }
                    ]
                }
            ],
            "interchangeEndPos": "7133",
            "interchangeStartPos": "0",
            "txns": []
        }
    ],
    "status": "COMPLETE"
}

GET

The GET operation is used to.

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

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

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

  • Job ID

  • Job Status: Queued, Submitted, In Progress, Completed

  • Date and time started

  • Date and time completed

  • Guideline used

  • Data file used

  • Validation return code and error message, if one

  • Count of messages by severity

  • Count of messages by type

  • List of output files

  1. REST Path

    1. For a specific job

      .../jobs/jobId

    2. For a list of all jobs

      .../jobs

  1. Optional Parameters

    archive=Y

    Used when requesting a list of all jobs to include those jobs that have completed and have been moved off the ‘Job Board’ onto disk. If requesting information on a specific job, this parameter is ignored.

  2. Request Body: (Empty)

  3. Possible Responses

    Response Description
    200 OK Job information retrieval is successful; the response body contains information.
    400 Bad Request Problem with the request (missing job ID, and so on); see the response body for reason.
    404 Not Found Specified job cannot be found on Server
    415 Unsupported Media Type Control file GET supports only media types of ‘text/plain’.
    500 Internal Server Error Server had problems reading information; see the response body for reason.

  1. Examples

    1. http://<host-name>:<port>/ForesightREST/jobs/J190528165545_00001

      Response Body:

      JobID:J190528165545_00001
Status:COMPLETE
Started:2019-05-28 16:55:45.881-0400
Completed:2019-05-28 16:56:03.269-0400 Guide:PDSA837I
Data:837I_4010_H_6claims.txt Ops:32
InstreamRCode:100 InstreamMsg:
MsgsBySeverity:0,23,0,4,0,0,0 MsgsByWEDIType:23,4,0,0,0,0,0,0,0,0
--Output Files-- J190528165545_00001_RG277.txt J190528165545_00001_RG824.txt J190528165545_00001_RG997.txt J190528165545_00001_RGText.txt
J190528165545_00001_VResult.txt Summary_J190528165545_00001_VResult.txt

    2. http://SERVX:8080/ForesightREST/jobs?archive=y

      Response Body:

      ...JOB BOARD...
J190528165545_00003    COMPLETE    started:190528165545 completed:190528165545 J190528165345_00002    PROCESSING started:190528165545
J190528165225_00001    COMPLETE    started:190528165545  completed:190528165545
...ARCHIVE... J190507164911_00011 J190522162506_00001 J190522165258_00002 J190522170723_00003

DELETE

The DELETE operation is used to remove a job resource from the REST server, along with all of its Output files.

  1. REST Path: .../jobs/jobId

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK The specified job is deleted successfully.
    400 Bad Request

    Problem with request (missing job ID, and so on); see response body for reason.
    409 Conflict The specified job resource cannot be deleted; see the response body for additional information.
    500 Internal Server Error The server had problems deleting the job; see response body for reason.

Job Output Files

The purpose of a job is to produce output files. Job Output File resources are created during job processing initiated through a POST process.

Two REST API operations are supported for Job Output File resources: GET and DELETE

GET

The GET operation is used to:

  • Get a specific output file from a particular job on the REST API server

  • Get a list of all the output files generated by a particular job on the server

For specific Output File GETs, the contents of the requested file will be returned in the response body (media type=Application/Octet-Stream).

When a list of all output files is requested, the following information is provided for each output file found for the specified job:

  • File name

  • File Size

  • File Creation Date and Time

  • File Last Modification Date and Time

Note: Fields are tab delimited.

  1. REST Path

    1. For a specific output file for job ‘jobId’

      .../jobs/jobId/output/outputFileName

    2. For a list of all output files for a specified job ‘jobId’

      .../jobs/jobId/output

  1. Optional Parameters

    1. (None)

  1. Request Body: (Empty)

  2. Possible Responses

    Response Description
    200 OK Output file information retrieval is successful; the response body contains information.
    400 Bad Request Problem with request (missing job ID, output file name, and so on); see the response body for reason.
    404 Not Found The specified job/output file cannot be found on the server.
    415 Unsupported Media Type Output file GET supports only media types of ‘Application/Octet-Stream’.
    500 Internal Server Error The server had problems reading information; see response body for reason.

  1. Examples

  1. http://<host-name>:</ForesightREST/jobs/J190528165545_00001/output

    Response Body:

    J190528165545_00001_RG277.txt 889 2019-05-28T20:56:03.164831Z 2019-05-28T20:56:03.304824Z J190528165545_00001_RG824.txt 0 2019-05-28T20:56:03.165871Z 2019-05-28T20:56:03.165871Z J190528165545_00001_RG997.txt 681 2019-05-28T20:56:03.161896Z 2019-05-28T20:56:03.229838Z J190528165545_00001_RGText.txt 1365 2019-05-28T20:56:03.167827Z 2019-05-28T20:56:03.305916Z J190528165545_00001_VResult.txt 16015 2019-05-28T20:56:02.603854Z 2019-05-28T20:56:02.893816Z Summary_J190528165545_00001_VResult.txt 466 2019-05-28T20:56:02.605864Z 2019-05-28T20:56:02.895826Z

  1. http://SERVX:8080/ForesightREST/jobs/J190528165545_00001/output/ J190528165545_00001_RG997.txt

    Response Body:

    ISA*00* *00* *01*HORIZONE *01*HILLSDALEHOSP
*190528*1656*U*00401*000000001*0*P*:~ GS*FA*HORIZONE*HILLSDALEHOSP*20190528*165603*1*X*004010~ ST*997*0001~
AK1*HC*1~ AK2*837*0001~ AK3*DTP*58*2300*8~ AK4*3*1251*8*20120212~ AK3*DTP*77*2300*8~
AK4*3*1251*6~ AK4*3*1251*8*12~ AK3*DTP*98*2300*8~ AK4*3*1251*8*20120212~
AK5*R*5~ AK9*R*1*1*0~ SE*13*0001~
GE*1*1~ IEA*1*000000001~
ISA*00* *00* *01*9088877320000 *01*9012345720000
*190528*1656*U*00401*000000002*0*P*:~ GS*FA*908887732000*901234572000*20190528*165603*2*X*004010~ ST*997*0002~
AK1*HC*2~ AK2*837*0002~
AK5*A~ AK9*A*1*1*1~ SE*6*0002~ GE*1*2~ IEA*1*000000002~

DELETE

The DELETE operation is used to remove a job Output File resource from the Foresight REST API server.

  1. REST Path: .../jobs/jobId/output/outputFilename

  1. Request Body: (Empty)

  2. Possible Responses

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