Helpful Tip

This page contains information regarding the differences between the Job State and the Job Detailed Error message.

Vantage Cloud/Hosted Workflows maintains a distinction between the detailed error message description and the job state. This is being called out to help clarify the difference between what is displayed in the Vantage Cloud User interface and what is returned when a Job State query is made (specifically when a Job has FAILED and a diagnosis is being made).

The Job State/Progress query, an example of which is:

https://api.cloud.telestream.net/vantage-cloud-port/v2.0/workflows/\<WorkflowID>/workflow-jobs/<JobID>/progress

For a job which has failed, this query will return a JSON structure similar to:

{

    "status": "completed",

    "state": "failed"

}

NOTE: The final ‘status’ of the job is ‘Completed’. This indicates that the Job in question has completed. The ‘state’ designation indicates that the completed state was a failure.

What is not present in this API query is the low level error description of what failed within this job. All that is returned is the final job state (Failed).

The Job associated with the query/result above; would display a failed state in the Telestream Cloud web user interface as well. However, in addition, the error details would be displayed. This may appear as (in the UI):

If this level of information is desired via the API, then a separate query exists which will return the full set of details about the specific job. The information displayed above would be present in the results of that query.

The API query to return the full job details (including the error message details) is:

 https://api.cloud.telestream.net/vantage-cloud-port/v2.0/workflows/workflow_id/workflow-jobs/workflow_job_id

eg:
https://api.cloud.telestream.net/vantage-cloud-port/v2.0/workflows/406a4e29de2076307e38f52d99ba515c/workflow-jobs/a9d29e1081847726fd4af5da35cf5d4e

This will return a JSON structure similar to:

{

    "id": "a9d29e1081847726fd4af5da35cf5d4e",

    "name": "Flip64_Overlay API submit - path normal",

    "inputs": {

        "sources": {

            "Original": "https://johncloud.s3-us-east-2.amazonaws.com/Source/demo1.mpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=
XXXXXXXXXXXXXXXXXXX/20210528/us-east-2/s3/aws4_request&X-Amz-Date=20210528T133646Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2dec797a3045e86f033883334fbedc8a70dc6a019e457e4329f2c799e5074340"

        },

        "variables": {

            "OverlayUrl": "https://johnkoctopus.s3-us-west-1.amazonaws.com/MyOverlayFile.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=
XXXXXXXXXXXXXXXXXXX/20200602/us-west-1/s3/aws4_request&X-Amz-Date=20200602T165424Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=d863e748b08638983b4b39a1cb70268ad89c2156cc634e899b4ba90bd3d78025"

        }

    },

    "storage_references": {

        "d114b493-e433-4dd1-81fd-c3c89297dd8d": {

            "name": "Flip64",

            "store_id": "240f042bfc4bee58a965c7d79e17c45c",

            "folder_offset": "SDK1"

        }

    },

    "state": "failed",

    "status": "completed",

    "error_class": "ProcessingError",

    "error_message": "action 'd114b493-e433-4dd1-81fd-c3c89297dd8d' (Flip64): 'failed: A failure occurred at Telestream Cloud during the processing phase, error: Unable to download the media. Forbidden'",

    "action_jobs": [

        {

            "id": "0a9e8db85e2ecf9d424f776d420b37f5",

            "action_name": "Flip64",

            "state": "failed",

            "status": "completed",

            "inputs": [

                {

                    "id": "98b2b02def765fd35b3a9828d8faf7e3",

                    "name": "Original",

                    "url": "https://johncloudport.s3-us-east-2.amazonaws.com/Source/demo1.mpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=XXXXXXXXXXXXXXXXXXX/20210528/us-east-2/s3/aws4_request&X-Amz-Date=20210528T133646Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2dec797a3045e86f033883334fbedc8a70dc6a019e457e4329f2c799e5074340",

                    "duration": 30101,

                    "file_size": 30158984

                },

                {

                    "id": "1a7a797785d7c31209c3994442bd32e1",

                    "url": "https://johnkoctopus.s3-us-west-1.amazonaws.com/MyOverlayFile.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=
XXXXXXXXXXXXXXXXXXX
/20200602/us-west-1/s3/aws4_request&X-Amz-Date=20200602T165424Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=d863e748b08638983b4b39a1cb70268ad89c2156cc634e899b4ba90bd3d78025"

                }

            ],

            "outputs": [

                {

                    "id": "2926c08e8e31d13eec8c133492de097a",

                    "name": "_out",

                    "remote_path": "SDK1"

                }

            ],

            "store_id": "240f042bfc4bee58a965c7d79e17c45c",

            "created_at": "2021-05-28T13:38:31.057631Z",

            "updated_at": "2021-05-28T13:42:12.846287Z",

            "error_class": "",

            "error_message": "Unable to download the media. Forbidden"

        }

    ],

    "workflow_revision": 1,

    "created_at": "2021-05-28T13:38:18.191412Z",

    "updated_at": "2021-05-28T13:42:14.917767Z"

}

NOTE: The JSON above includes a field named: "error message" which contains a value that corresponds to the information displayed in the Telestream Cloud User Interface. This also represents the details of why this particular job failed.