Retrieve Workflow Details

The first method (retrieve workflow details) is defined as:

Where {workflow_id} corresponds to the Identifier associated with the workflow previously uploaded.

Recall from the previous section that this identifier is accessible from the Workflow Details section of the Telestream Cloud UI:

Using this ID, the following GET query is performed:

https://api.cloud.telestream.net/vantage-cloud-port/v2.0/workflows/912d15b040e2d3f784e9ea89d5b2bee2

📘

Authorization Header

The same authorization header which was detailed in the previous section about Stores is specified as well.

A successful response shall return a JSON data blob that represents the details of this workflow. This JSON data shall provide a complete representation of what Inputs are expected and what Variables are expected.

The response to the specific query above is:

{
    "id": "912d15b040e2d3f784e9ea89d5b2bee2",
    "name": "API Example",
    "vantage_workflow_name": "Simple_Cloud_Workflow",
    "identifier": "fa72f190-1efc-4ac8-b762-afc308d65fee",
    "workflow_hash": "CmzSNrKUe7+b3eC9J1tehvjaaBY=",
    "timestamp": "2020-04-09T13:10:37Z",
    "input": {
        "variables": {
            "Video Height": {
                "identifier": "409cf8c1-b4f9-41cb-b075-4bb028257d57",
                "name": "Video Height",
                "typecode": "Int32",
                "default": "480",
                "value": "480"
            },
            "Video Width": {
                "identifier": "6ccc4b35-9abf-421d-9f3d-d92b48cfc8e8",
                "name": "Video Width",
                "typecode": "Int32",
                "default": "720",
                "value": "720"
            }
        },

        "sources": {
            "Original": {
                "name": "Original",
                "description": "The original version of content encountered or created by Vantage.",
                "identifier": "abb3f7e5-8d7e-49ba-84c5-674a55edb700"
            }
        },

        "storage_references": {
            "9dff864e-045c-4b58-8cb1-12221bd89c6b": {
                "action_identifier": "9dff864e-045c-4b58-8cb1-12221bd89c6b",
                "name": "IPTV Flip",
                "description": "IPTV with variables",
                "lifecycle": "Permanent"
            }
        }
    },

    "store_id": "240f042bfc4bee58a965c7d79e17c45c",
    "created_at": "2020-04-09T13:11:25.370778Z",
    "updated_at": "2020-04-09T13:11:25.991997Z",
    "status": "Active"
}

The ‘input’ section of the JSON blob above define the specific parametric components that can be modified at submission time via the API.

In particular, the ‘variables’ section correspond to exactly the list of EXPECTED variables that was defined as part of the original Vantage workflow, i.e.:

The ‘typecode’ value is a hint so that the API User knows how to interpret the contents of the ‘value’ and ‘default’ fields.

The following values will be present for a ‘typecode’:

Again, the intent of the typecode value is to provide a qualifier so that the client can properly interpret how to manipulate the specific variable entry (i.e.: a variable which has an advertised typecode of ‘Byte’ should NOT be given a value of 4096 as an example. This will produce unexpected results and/or failures in the receiving workflow.

The ‘source’ section corresponds to the different input Nicknames expected by this workflow. This shall correspond exactly to the requirements defined for the Receive action which acts as the origin for this workflow.

The contents of the ‘source’ section correspond to the fact that the workflow being manipulated was designed with a single Input nickname (‘Original’):

The ‘storage_reference’ section is a mechanism which provides control over where the OUTPUT of a specific action should be placed. This is utilized in conjunction with the Lifespan concept (which details how long a given OUTPUT should persist) to define the desired rules regarding the storage and persistence of output material.

The ‘store_id’ field MUST correspond to the storage ID of a valid Telestream Cloud store (defined in the current user’s account).

The ‘folder_offset’ field allows specification of an offset path (relative to the base location defined in the storage for which the ‘storage_id’ corresponds.

📘

Immutable Values

Certain values which are provided in the ‘storagereference’ generated by the GET query above may NOT be changed. _In particular, the action_id field is not something a user can alter; that data MUST be left unchanged. This specifically defines that particular action that the workflow creator explicitly associated the storage with. This value MAY NOT be altered.

What can be altered on a job by job basis is WHICH store and any desired path offset.

As an example of how the ‘store_id’ and ‘folder_offset’ would be used. Consider the following Storage definition (which has previously been created in Telestream Cloud

❗️

Valid Store

A storage MUST have been created and have VALID credentials/access provided within Telestream Cloud in order to be utilized within the Vantage Cloud V2 API.

The Vantage Cloud V2 API would allow a user to query the available Storages for an account. The result of this query would provide a name and ID.

For example, the result of the query to list the available stores would return information similar to:

Name: Telestream S3

StoreId: 1234

Using this information, the StoreID in particular, the API user/client can indicate that the output of a particular action should utilize a particular store.

Further, via specifying a path offset in the ‘folder_offset’ field; a specific subfolder may be specified on a per-job basis.

For example, consider that the ‘Telestream S3’ store above points to a base location of a bucket named: johnktest1 in a specific AWS S3 account.

If an API user wishes to indicate that the output of a given action in the current workflow should be placed into a specific subfolder, relative to the base location specified by this storage entry (bucket: johnktest1); the ‘folder_offset’ would be populated with this value.

For example, specifying “folder_offset’:”/folder1/project1” would imply a desired bucket/folder structure of: johnktest1/folder1/project1/

Any media files created by the action associated with this storage reference would be placed in this location.