External data source

External data source mechanism is used with fields to specify that the value for a field must be fetched from an external source.

Source is described by these properties:

​	​
url	Absolute or relative URL pointing to document containing the data.
method	HTTP method used to request data. Can be “get” or “post”.
service	Service type, required if relative URL is specified. If set then data is provided by specified service. Service base URL is used to build full URL to data document.

GET

external data via GET

"source": { "url": "http://example.com/external.json", "method": "get" }

The platform sends GET request to specified URL and expects data as a response.‌

POST

external data via POST

"source": { "url": "http://example.com/prefill.json", "method": "post" }

The Interaction Cloud sends POST request to specified URL with project, event (if the field attached to event or element) and element (if the field attached to element) custom fields values.‌

Request data

{
    "project_id": "605b68ae-3efd-4edd-8139-84cbbcd20b3f",
    "project": 
    {
        "custom_fields": 
        {
            "competition_id": "1234",
            "twitter_hash_tag": "#lvis"
        }
    },
    "event_id": "851193bd-095b-478f-9b94-a8d7155f2603",
    "event": 
    {
        "custom_fields": 
        {
            "channel": "c4"
        }
    },
    "element": 
    {
        "content_type": "man_of_the_match",
        "custom_fields": 
        {
            "team_id": "234",
            "podium": [{
                "id": "p1",
                "data": "payload"
            }]
        }
    }
}

If request can not successfully return data it should return non-200 HTTP code and a body like this:‌

Error response body

{
    "missing_fields":
    {
        "project": ["competition_id"],
        "event": ["channel_id", "twitter_hash_tag"],
        "element": ["team_id"]
    },
    "error": "Unknown match id 1234"
}

Both missing_fields and error are optional.‌

POST via Service

"source": { "url": "/prefill.json", "method": "post", "service": "prefiller" }

Request URL is constructed as <service base url>/prefill.json.‌

The platform passes instance_uuid and project_uuid parameters via the query string with an instance id and project id respectively.

Is a service is used as a source, it must be specified as a required service in the app spec.