Custom Field Mappings

This article covers on how one would use custom field mappings when building an external integration using the Kapost API.

A prime example of such an integration would be pulling out custom field values on a per content basis via the Kapost Content API and then ingesting them in some other tool or system. In such cases, there's a high probability that the values in Kapost will not be a 1:1 match with the values expected in the target tool. In addition, in most cases the name of the field will be different as well.

This is where, custom field mappings come into play and allow a Kapost admin to manage these mappings through the Kapost Custom Field settings, rather than having them hard-coded into the integration itself.

Why is this important? First and foremost if new values added or existing values are updated or deleted, then no code changes will be necessary when it comes to the integration itself -- it will just work.

To learn more about mapping custom fields from the Kapost admins' perspective, click here.

Without any further ado, let's dive into it.

First and foremost, we'll use the Kapost Destinations API to retrieve the generic external destination that all our custom field mappings have been associated with.

curl -u "api_token:x" -d "name=My External App" -d "platform=External" https://instance.kapost.com/api/v1/destinations

This API call will return an array with a single destination that matches the name that we just specified.

...
{
    "id": "5ea9f1943cc5260130c2304e",
    "identification": "My External App",
    "platform": "External",
    "supports_custom_field_mappings": true
}
...

Now that we have the id, we will be able to retrieve and lookup the custom field mappings by using the Kapost Custom Field API:

curl -u "api_token:x" -d "name=awesome" https://instance.kapost.com/api/v1/custom_fields_reference

This will look up the custom field that we want by its name. It is possible to lookup more than one by specifying an array of names like so:

curl -u "api_token:x" -d "name[]=awesome" -d "name[]=another" https://instance.kapost.com/api/v1/custom_fields_reference

This will return an array of fields matching specified name or names.

...
{
    "id": "5b479828bc9df500a90001fd",
    "field_type": "multiselect",
    "display_label": "Awesome",
    "name": "awesome",
    "formatted_select_values": [
        {
            "id": "5b479828bc9df500a90001fb",
            "display": "Hello",
            "value": "Hello",
            "archived": false
        },
        {
            "id": "5b479828bc9df500a90001fc",
            "display": "World",
            "value": "World",
            "archived": false
        }
    ],
    "mappings": [
        {
            "id": "5f36ed42e6ed9301394e3ac0",
            "field_name": "awesome_external",
            "external_site_id": "5ea9f1943cc5260130c2304e",
            "values": [
                {
                    "id": "5f36ed42e6ed9301394e3ac1",
                    "value_id": "5b479828bc9df500a90001fb",
                    "value": "Hello External"
                },
                {
                    "id": "5f36ed42e6ed9301394e3ac2",
                    "value_id": "5b479828bc9df500a90001fc",
                    "value": "World External"
                }
            ]
        }
    ]
}
...

In the response, there's a mappings array. In this array we have to look for for the mapping that has the external_site_id matching the id that we got back from the Kapost Destinations API. In this particular case it is 5ea9f1943cc5260130c2304e.

Our mapping will contain two pieces of information.

First, the field_name which is name of the field in the external system that we are mapping this field to, and second, an array of mapped values.

Each mapped value has a value_id and a value. It is worth nothing that only select and multi-select (dropdown) custom fields will have value mappings.

Now that we have our mappings, let's suppose that we are retrieving content via the Kapost Content API.

curl -u "api_token:x" -d "columns[]=custom_fields" https://instance.kapost.com/api/v1/content

This should return us a response that looks like this:

...
{
    "id": "5f6af6b8e7a4880130ff1281",
    "slug": "test-2948359004",
    "custom_fields": {
        "5b8ebd62cd252700a90000e8": "beautiful text value",
        "5b479828bc9df500a90001fd": [
            "5b479828bc9df500a90001fb"
        ]
    }
}
...

We can see that our custom field with the id of 5b479828bc9df500a90001fb has an array of value_ids. If this custom field was just a select not a multiselect, then the response would look like this:

...
{
    "id": "5f6af6b8e7a4880130ff1281",
    "slug": "test-2948359004",
    "custom_fields": {
        "5b8ebd62cd252700a90000e8": "beautiful text value",
        "5b479828bc9df500a90001fd": "5b479828bc9df500a90001fb"
    }
}
...

Notice how there's no array, just a single value_id.

Now that we have the value_id all we have to do is to look up the value mapping.

...
"values": [
    {
        "id": "5f36ed42e6ed9301394e3ac1",
        "value_id": "5b479828bc9df500a90001fb",
        "value": "Hello External"
    },
    {
        "id": "5f36ed42e6ed9301394e3ac2",
        "value_id": "5b479828bc9df500a90001fc",
        "value": "World External"
    }
]
...

In this particular case, our mapped value for this value_id will be Hello External.

Now that we have the mapped field name and value (or values) we can send them to our external tool or system.

{
    "awesome_external": ["Hello External"]
}

This process would then need to be repeated for all desired custom fields and values.

One question that probably comes to mind after reading all this, isn't it expensive to always retrieve the destination and the value mappings?

The answer is, not really. One wouldn't be syncing more often than every 5 minutes and in the case of large scale syncing scenarios most likely less often, like once every hour, or once every day. Therefore it makes little sense to attempt to cache or hardcode things.