Mapping Values to a Custom Json Outbound Integration

When mapping values and fields in a custom Json outbound integration, use “dot notation” to define where each value being mapped should be placed in the request body.

(This article assumes that you understand the basics of how Json documents are structured. There are numerous resources and tutorials online that cover the basics of Json data structures.)

Json documents consist of hierarchically organized collection of Json objects, properties and arrays. Use dot notation to map the structural path to each value you need to send to the recipient of your LeadConduit flow’s Custom Json outbound step.

It’s probably easiest to see how dot notation works by looking at an example. Here’s a typical json request body:

{
    "lead" : {
        "Acode" : "D80731",
        "FirstName" : "Chester",
        "LastName" : "Tester",
        "HSGraduationYear" :  "1996",
    },
    "phones" : [{
            "PhoneNumber" : "212-555-1212",
            "PhoneType" : "3"
        }, {
            "PhoneNumber" : "916-555-1212",
            "PhoneType" : "1"
        }
    ],
    "leadEmail" : "chester@tester.com",
    "address" :{
        "Line1" : "405 Broadway",
        "City" : "New York",
        "State" : "NY",
        "Country" : "US",
        "Zip" : "10010"
    },
    "passcode" : "cjdujwofpf",
    "programTypeCode" : "12345",    "program_of_interest": "MA in Mathematics"
}

Note that it consists of a json object that consists of several root-level json properties (Named “lead”, “phones”, “leadEmail”, “address”, “passcode”, and “programTypeCode”) each of which may have as their values either a simple value (as do “leadEmail”, “passcode”, “programTypeCode”), or a collection of child properties (as do “lead” and “address”) or an array of child objects (as does “phones”).

To map a value to a root-level property like “leadEmail”, the path in this case would simply be the property name leadEmail

To map a value to a child property, like “FirstName” which is a child of the root-level property “lead”, the path would be lead.FirstName

When a property has as its value an array of one or more child objects, such as “phones” which has as its value an array of one or more json objects each of which has two properties (“PhoneNumber” and “PhoneType”), each element of the array is represented as a numeric subscript that relates the components. For instance, to map phone_1, the path for that element’s PhoneNumber would be phones.0.PhoneNumber and the path for that element’s phoneType would be phones.0.PhoneType. Similarly, for phone_2 the paths would be phones.1.PhoneNumber and phones.1.PhoneType. Subscripts must be assigned sequentially beginning with zero.

Here is an example of what the mappings for the above Json request body would look like in LeadConduit:

Sending Numbers and Booleans with #number and #boolean

Unlike XML, Json distinguishes between a string, a number, and a boolean. By default, a value you map into a Custom Json outbound step is sent as a Json string — it arrives at the recipient wrapped in quotes. Most recipients accept that, but some require true Json types, such as an unquoted number for an age or a real true instead of the word "true".

To control the type, add a type suffix to the end of the mapping’s Json path. This works the same way #text and #cdata do in the Custom XML outbound integration.

Without those suffixes, the same two mappings would send {"age": "42"} and {"consent": "true"}.

The suffix always goes at the very end of the path, so it can be used at any depth, including on array elements:

What Gets Converted

#number ignores any character that isn’t a digit, a minus sign, or a decimal point before converting, so currency and thousands separators are handled for you:

• 42 → 42
• -3.5 → -3.5
• $100,000.00 → 100000

#boolean ignores case, spaces, and punctuation, then accepts any of these:

• true, t, yes, y, 1 → true
• false, f, no, n, 0 → false

Things to Know

• A value that can’t be converted is sent unchanged, as a string. If a field mapped to age#number contains unknown, the request body contains {"age": "unknown"} rather than failing. The lead is never rejected because of a type suffix, so check the outbound request body in the lead’s event detail if a recipient reports a type error.
• Blank and missing values are left alone. An unpopulated mapping stays empty or null; it does not become 0 or false.
• Only these two suffixes are recognized. The suffix is not case-sensitive, so #Number and #NUMBER both work, but anything else — #string, #json, #integer — is treated as part of the property name and sent literally. A mapping to price#usd produces {"price#usd": "42"}, so double-check your spelling if a recipient reports an unexpected property name.
• Type suffixes apply only to Json paths in Custom Json (and Json) outbound steps. They have no effect on form, query string, XML, or SOAP steps.

• mapping_values_to_a_custom_json_outbound_01.png200 KB