Skip to content

URL Callback

Introduction

The seal-dpf-urlcallback service provides the option of an active answer back to the assigning party of a job. It will perform a PUT request of the URL given containing the tracker url of the job, if the job parameter DpfControlCallbackUrl is set. The response is triggered by these job states:

  • job_sending: entering working unit sendback, i. e. waiting for the client to fetch the result file(s)

  • job_finished: DPF job reached end, either normally or abnormally/erroneously.

Usage

Using DPF Batch Client you can supply a callback URL for your DPF job and thus trigger a callback request.

Example

dpfclient -wf example -protocol http -host localhost:4303 -s DpfControlCallbackUrl=http://callbackhost:8080/ourjobmanager/ourjobno/12345

Data Delivery

The seal-dpf-urlcallback service performs a PUT request containing a JSON data structure.

It contains these elements:

  • jobId: DPF job ID
  • jobIdFs: DPF job ID, same value as jobId
  • jobState: current state of the job, for example SENDING, FINISHED, or ERROR
  • exitStatus: final status of the job, only if the job is finished, either normally or with an error
  • errorReason: error reason, only if the job ends with an error and the job parameter ErrReason is set
  • dpfTrackerUrl: link to the job in DPF Tracker. In on-premise installations, set TRACKER_URL to get a working link.

Elements without a value are missing in the JSON data structure.

Example - JSON data for job state SENDING

{
    "jobId": "202610191243440151",
    "jobIdFs": "202610191243440151",
    "jobState": "SENDING",
    "dpfTrackerUrl": "https://dpfsrv03:9126/cgi-bin/dpftracker?job=202610191243440151"
}

If the job ended successfully, jobState is FINISHED and exitStatus has the value OK.

Example - JSON data for a successful job

{
    "jobId": "202610191213550149",
    "jobIdFs": "202610191213550149",
    "jobState": "FINISHED",
    "dpfTrackerUrl": "https://dpfsrv03:9126/cgi-bin/dpftracker?job=202610191213550149",
    "exitStatus": "OK"
}

If the job ended with an error, jobState is ERROR and exitStatus contains the error status.

Example - JSON data for an erroneous job

{
    "jobId": "202610191221400150",
    "jobIdFs": "202610191221400150",
    "jobState": "ERROR",
    "dpfTrackerUrl": "https://dpfsrv03:9126/cgi-bin/dpftracker?job=202610191221400150",
    "exitStatus": "ERR_EXTERN_PROG_CALL"
}

Differences to DPF 3.x

The JSON data structure differs from DPF 3.x:

Element DPF 3.x DPF 4.x
jobId Internal job number as number, for example 47. Job ID as string, same value as jobIdFs.
Elements without a value All six elements are always sent.
Elements without a value are null.		 Elements without a value are omitted.
errorReason Sent if a working unit fails, for example Error calling external program. Sent only if the job parameter ErrReason is set.

Error Analysis

If the callback does not seem to work as expected, i. e. callback URL not requested, do any of the following:

  • In a PowerShell or Command Line (not DPF environment), check the status of seal-dpf-urlcallback service.

    dpf service status seal-dpf-urlcallback

  • Check in the log file whether the callback request was successful.

    • Windows: C:\ProgramData\SEAL Systems\log\seal-dpf-urlcallback.log
    • Linux: /var/log/seal/seal-dpf-urlcallback.log

    Hint - use Elastic Stack

    The log file contains machine-readable entries in JSON format. Use Elastic Stack for a human-readable view. For how to install and configure Elastic Stack, refer to SEAL Elastic Stack documentation.

    If the log file provides too few information, you can raise the LOG_LEVEL.

Back to top