Skip to content

VCC

Configurations and tasks

Example configuration (Using the S3 adapter)

{
    "configuration_name": "welcome-video-s3-upload",
    "experience_id": "developer-conference-2022",
    "adapter_name": "s3",
    "adapter_config": {
        "auth": {
            "secret_key": "e466e906d71c49a5baba4176b0518c",
            "access_key": "22dbdfaafbfe44088c01"
        },
        "defaults": {
            "bucket_name": "abc-conference-uploads",
            "public": true,
            "force_download": false,
            "file_prefix": "xpkit/vcc/",
            "bucket_url": "https://s3.amazonaws.com"
        }
    },
    "activity_config": {
        "experience_id": "developer-conference-2022",
        "activity_type": "content-generation",
        "payload": {
            "object_id": "website"
        }
    },
    "webhook_url": "https://xpkit.abc.com/callback"
}

The contents of the activity_config field are used to create an activity once the task has finished. The activity will also contain details about the processed file. See the Activities section below for more information on that.

To determine the contents of adapter_config see here for a list of available adapters.

Example chain configuration

{
    "configuration_name": "welcome-video",
    "experience_id": "developer-conference-2022",
    "call_chain": [
        [
            "welcome-video-join",
            null
        ],
        [
            "welcome-video-add-audio",
            0
        ],
        [
            "welcome-video-s3-upload",
            1
        ]
    ],
    "webhook_url": "https://xpkit.abc.com/callback"
}

In the call_chain for each array the first element is a configuration_name and the second is the index of the configuration in the chain the input should be taken from. In the example the chain is sequential, each configuration takes the (transformed) file from the previous configuration in the chain.

Example task trigger request

curl --location --request POST 'https://vcc.emea.xpkit.net/api/task/' \
--header 'Authorization: Bearer <redacted>' \
--form 'data=@"/path/to/file/MyFile.mp4"' \
--form 'configuration_name="welcome-video"' \
--form 'extras="{\"email\": [\"sarah.jones@abc.com\"]}"'

The extras POST parameter is a JSON string. You can provide one of the following profile lookup fields (all of type array) so an activity can be created after the task has completed: email, qr_code, rfid, profile_id (profile resource UUID).

You can also override configuration options by providing them in the extras parameter. For example with a task using the YouTube adapter you may wish to personalise the video title rather than having a generic one for all the videos you upload.

Activities

If a configuration contains an activity_config field, the contents of that field will be used to create an activity for the profile fetched based on the lookups provided in the extras field when a task is triggered.

The result of the task will also be stored in this activity under a souvenir_data field. Here is an example of an activity generated from a configuration using the S3 adapter.

{
    "owner_id": "b0fc813f-c6b5-4334-97d5-153c4fe6053b",
    "experience_id": "developer-conference-2022",
    "payload": {
        "souvenir_data": {
            "adapter_response": {
                "file_key": "xpkit/vcc/1596681918.091376_MyFile.mp4",
                "url": "https://s3.amazonaws.com/abc-conference-uploads/xpkit/vcc/1596681918.091376_MyFile.mp4",
                "bucket_name": "abc-conference-uploads"
            }
        },
        "object_id": "website",
        "vcc_config_name": "welcome-video",
        "chain_id": "7cfae965-8037-47f3-a29e-3b94591c982e",
        "task_id": "9ac2c9d2-63f6-4899-8c56-51ed408b074c"
    },
    "flow_id": "67756e0e-c46e-4287-97e5-6d0951246f50",
    "activity_type": "content-generation"
}

Callbacks

Tasks created from both a single and chained configuration support callbacks. When a task has completed the result of each configuration will be posted to the provided webhook_url.

If a callback is specified on a single configuration but it is called in a chained configuration context, the webhook_url specified in the chained configuration takes precendence and all other webhook_url fields are ignored.

Any URL provided should accept POST requests over HTTPS.

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

{
    "task_id": "b8d53fc8-92bb-43f5-a05b-34eb6d4cef25",
    "configuration": "welcome-video",
    "status": "Succeeded",
    "results": [
        {
            "result": {
                "success": true
            },
            "error": false,
            "configuration": {
                "name": "welcome-video-join",
                "chain_id": "7cfae965-8037-47f3-a29e-3b94591c982e",
                "input_idx": null
            }
        },
        {
            "result": {
                "success": true
            },
            "error": false,
            "configuration": {
                "name": "welcome-video-add-audio",
                "chain_id": "7cfae965-8037-47f3-a29e-3b94591c982e",
                "input_idx": 0
            }
        },
        {
            "result": {
                "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": ["b36c9875-1480-4466-8b12-5420e3f817e3"]
            },
            "error": false,
            "configuration": {
                "name": "welcome-video-s3-upload",
                "chain_id": "7cfae965-8037-47f3-a29e-3b94591c982e",
                "input_idx": 1
            }
        }
    ]
}

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

{
    "task_id": "3f507b0d-10f0-4cf0-a6b0-0092baf9130e",
    "configuration": "welcome-video-s3-upload",
    "status": "Failed",
    "results": [
        {
            "result": "Failed to upload 1596681918.091376_MyFile.mp4 to abc-conference-uploads/xpkit/vcc/1596681918.091376_MyFile.mp4: An error occurred (SignatureDoesNotMatch) when calling the PutObject operation: The request signature we calculated does not match the signature you provided. Check your key and signing method.",
            "error": true,
            "configuration": "welcome-video-s3-upload",
                "chain_id": "f8fb7549-d2b6-4a36-9f30-051f32454616",
                "input_idx": null
            }
        }
    ]
}

Each result in the results array contains the outcome for that configuration. If there was no error the result field will be an object, otherwise it will be a string containing details about the error.