Retrieve Workflow Details

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

830830

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:

410410

Using this ID, the following GET query is performed:

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

761761

📘

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_CloudPort_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.:

596596

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’:

Typecode value (in JSON)

Variable Type

Definition

Boolean

Boolean

True/False

Byte

Byte

8 bit unsigned value (0x0 ... 0x255)

Int16

Signed Short

16 bit signed integer value

Int32

Signed Integer

32 bit signed integer value

UInt32

Unsigned Integer

32 bit unsigned integer value

String

String

A string value

Uri

Uri

A path to a file (specified as a fully qualified Signed HTTP URL

TimeCode

Vantage Timecode

A timecode value in the form: HH:MM:SS:[email protected], where framerate can be: 23.976, 24, 25, 29.97, 30, 50, 60

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’):

238238

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 ‘storage_reference’ 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 Cloud Port V2 API.

14551455

The Cloud Port 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.


Did this page help you?