This help file gets you started with more advanced setups for the data mapping. The whole article is made for all versions of WP Webhooks Pro 3.0.6 and higher.
We will start this manual with a full explanation of a complex mapping setup, so please take your time reading through each step. At the end of the manual, we also provide you the Export data of the data mapping so that you can simply import it on your very own system.
The example
Let’s assume we have the following, outgoing data that we want to send over to an external service:
{
"user_email": "[email protected]",
"first_name": "Jon",
"last_name": "Doe",
"roles": [
{
"name": "Admin",
"slug": "admin"
}
],
"meta_data": "{\"meta_key_1\": \"Some meta data\"}"
}
The server, that receives the request, requires the following notation:
{
"email": "[email protected]",
"user_first_name": "Jon",
"user_last_name": "Doe",
"user_role": "admin:Admin",
"user_meta": "meta_key_1,Some meta data"
}
To map it correctly, we will set up a data mapping template in the default way as described in this article.
Let’s begin with the email, first_name and last_name argument:
This one is simple. On the left side, we define the new argument name of the payload that the receiving endpoint requires, which in this case is email for the user_email. On the right, we define a new mapping key with the value user_email. There is no further configuration needed for this specific argument.
The user_first_name and user_last_name have the same treatment.
The next argument we need to map is the roles argument:
Sine this argument is more complex, we will break it down per line down below. What’s important to understand is why we actually use three different mapping elements to map the data accordingly.
The explanation is fairly simple: We separate each value to one main argument key and put the puzzle pieces together using dynamic tag mapping.
The first two arguments (user_role_name and user_role_slug) are using the same structure. Both are temporary arguments that we create to separate the data from the complex array string of the payload. We first iterate into the roles element (which is configured only as a mapping key and nothing else), then into the first element of the array (each dynamic element starts with 0, then 1,2,3,4,…).
The 0 you can see is set as well as a mapping key with the addition that we chose the Data Type setting to make an integer out of it (Convert Data To -> Integer).
The name and slug catch the actual value from the last entry of the sub-data, which then will be assigned to each the user_role_name and the user_role_slug.
We know this is a lot of information. If it was hard to understand, we recommend taking a look at the above JSON example.
In the final user_role argument, we used the Value Type setting with the Data Value selection. This tells the specific key to use it as a value instead of a mapping key. The value we used looks as followed:
{:user_role_slug:},{:user_role_name:}
This value uses our advanced argument mapping, which allows you to access the data of a given argument within a new or existing value. The notation for it is simple: The tag starts with {: followed by the argument name and ending with :}.
You can use also multiple argument tags within the same value as seen above.
Since the notation of the receiving endpoint requires the data separated by a comma, we added a comma in between.
The last example focuses on the user_meta maping.
This data mapping requires two custom entries. It is more complex since the initial string, which is given from the JSON that is sent over, contains a JSON escaped string. Due to that, you would usually only be able to map the JSON string as a whole string to a new value.
Thanks to our new data mapping setup, you can now also make this data accessible by encoding it with our key settings.
As seen in the example above, we are first going to extract the actual value from the string. This is done by first accessing the JSON encoded meta data string using the meta_data key for mapping, including the Decode JSON value setting active for encoding the JSON escaped string.
After that’s done, we can simply access the JSON data within the next keys. In this example, which is also seen in the screenshot above, is meta_key_1 since it contains the actual value.
After we extracted the data, it is a simple mapping again to the real argument value as seen in the screenshot or JSON. As a key, we use the following value in combination with the Value Type setting set to Data Value.
meta_key_1,{:meta_value:}
That’s it for the mapping.
If you test the results with the Data Mapping Preview, you will see the following result:
Pro tip: Since in our example we mapped all existing and required arguments, we can simply turn on the argument whitelist within the Global Template Settings (Via the button right next to the Save Template button)
This will remove all arguments that haven’t been actively defined within the data mapping template. This way you can minimize the payload size of your templates.
The data mapping export
This data mapping template is available as an importable example. Simply copy it and import it within one of your data mapping templates.
{"template_settings":{"wpwhpro_data_mapping_whitelist_payload":"whitelist"},"template_data":[{"new_key":"email","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"user_email\"}"]},{"new_key":"user_first_name","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"first_name\"}"]},{"new_key":"user_last_name","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"last_name\"}"]},{"new_key":"user_role_name","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"roles\"}","{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"integer\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"0\"}","{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"name\"}"]},{"new_key":"user_role_slug","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"roles\"}","{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"integer\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"0\"}","{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"slug\"}"]},{"new_key":"user_role","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"data_value\",\"wpwhpro_data_mapping_convert_data\":\"string\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"{:user_role_slug:},{:user_role_name:}\"}"]},{"new_key":"meta_value","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_decode_json\":\"1\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"meta_data\"}","{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"key_mapping\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"meta_key_1\"}"]},{"new_key":"user_meta","singles":["{\"settings\":{\"wpwhpro_data_mapping_value_type\":\"data_value\",\"wpwhpro_data_mapping_convert_data\":\"none\",\"wpwhpro_data_mapping_fallback_value\":\"\"},\"value\":\"meta_key_1,{:meta_value:}\"}"]}]}