VCC

Task Groups

Overview

Sometimes you may need to call multiple tasks in your application and waiting to receive all the callback requests is not practical. In this situation you can use a taskgroup.

A taskgroup trigger request is similar to a standard task trigger request but it accepts a list of tasks. The taskgroup runs each of these tasks in order and once complete returns all the results to a provided webhook_url.

Example taskgroup trigger request

curl --location --request POST 'https://vcc.emea.xpkit.net/api/taskgroup/' \
--header 'Authorization: Bearer <redacted>' \
--form 'configuration_names="[\"tg-image-compositor\", \"tg-overlay\", \"tg-s3-upload\"]"' \
--form 'tg-image-compositor_data=@"/path/to/file/MyFile.png"' \
--form 'tg-image-compositor_extras="{\"additional_context\":  {\"voucher_code\": \"AAA-BBB-CCC\"}}"' \
--form 'tg-overlay_data=@"/path/to/file/MyFile.mp4"' \
--form 'tg-s3-upload_input="tg-overlay"' \
--form 'webhook_url="https://abc.com/callback"'

Similar to a task request you should provide a file (data) and optional extras per configuration. These params should be prefixed with the configuration name, example: tg-image-compositor_data and tg-image-compositor_extras.

You can also use the output from a previous configuration in the group as the input into another. To do this rather than providing a param called {configuration_name}_data use {configuration_name}_input and set the value to the name of the configuration you wish to use. Example param name: tg-s3-upload_input.

Setting auxillary files

Some configurations require a static asset to function. In the above example the "tg-overlay" configuration uses the Video Add Overlay adapter. This adapter takes the provided file and overlays an image asset. This asset is usually provided using the asset endpoints.

This can be overriden in a taskgroup by taking the asset's param name, in this case overlay_file_name and suffixing it with "_override". The value should be set as a configuration name of a previous configuration in the group. The output of this would then be used. Example:

--form 'tg-overlay_extras="{\"overlay_file_name_override\": \"tg-image-compositor\"}"'

Callbacks

Any URL provided should accept POST requests over HTTPS.

Example payload sent to a webhook URL (successful taskgroup):

{
    "status": "Succeeded",
    "task_id": "621fb380-6adc-4d9e-86bf-806203bb9942",
    "results": [
        {
            "error": false,
            "result": [
                {"success": true},
                {"success": true},
                {
                    "bucket_name": "abc-conference-uploads",
                    "file_key": "xpkit/vcc/1596681918.091376_MyFile.mp4",
                    "url": "https://s3.amazonaws.com/abc-conference-uploads/xpkit/vcc/1596681918.091376_MyFile.mp4",
                    "activity": ["975567d9-cc78-4fb9-b073-6d608ad5cfb4"]
                }
            ],
            "configuration": "chain-video-join"
        },
        {
            "error": false,
            "result": [
                {
                    "bucket_name": "abc-conference-uploads",
                    "file_key": "xpkit/vcc/1596681918.091376_MyFile.png",
                    "url": "https://s3.amazonaws.com/abc-conference-uploads/xpkit/vcc/1596681918.091376_MyFile.png",
                    "activity": ["41d6a224-c87b-4301-8ede-e09ad1f6fae1"]
                }
            ],
            "configuration": "s3-image-upload"
        }
    ]
}

In this example the first task is using a chained configuration and the three results are provided in order. The second task is a single configuration and therefore only one result is provided.

Example payload sent to a webhook URL (failed taskgroup):

{
    "status": "Failed",
    "task_id": "e637c9ad-1074-4ef2-bb72-16ac5739fc5f",
    "results": [
        {
            "error": false,
            "result": [{"success": true}],
            "configuration": "tg-image-compositor"
        },
        {
            "error": false,
            "result": [{"success": true}],
            "configuration": "tg-overlay"
        },
        {
            "error": true,
            "result": "Failed to upload 1660699678_1660699666_media-overlay.mp4 to abc-conference-uploads/1660699678_1660699666_media-overlay.mp4: An error occurred (InvalidAccessKeyId) when calling the PutObject operation: The AWS Access Key Id you provided does not exist in our records.",
            "configuration": "tg-s3-upload"
        }
    ]
}