Step 3: Callout Template Request Body (JSON Format)

Request Body Page (JSON Builder)

NOTE: If the template is using the GET method, this step is skipped. GET methods don’t use bodies.

NOTE: Once you start mapping fields in the JSON Builder, you CANNOT change the Main Object and Number of records on your Callout Template. If you want to change either of these, you need to remove all mappings set in the JSON Builder. Then you have the option to update the Main Object and Number or records. This is by design as the values set in JSON are dependent on the Main Object and Number of records selected.  

 

About JSON

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is also easy for machines to parse and generate.

JSON is built on two structures:

• A collection of name/value pairs.
• An ordered list of values.

An object is an unordered set of name/value pairs. An object begins with { (left brace) and ends with } (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma). A value can be a string in double quotes, or a number, or true or false or null, or an object or an array.  Exmaple: { “name” : “Maria”, “age” : 30 }

An array is an ordered collection of values. An array begins with [ (left bracket) and ends with ] (right bracket). Values are separated by , (comma). Example: [ “orange”, “apple”, “cherry” ] These structures can be nested. Example: { “name” : { “first” : “John”, “last” : “Doe” } , “email” : “john@example.com”, “children_age” : [ 12, 8, 3 ] }

More about JSON here: https://www.w3resource.com/JSON/introduction.php  

 

JSON Builder

Let’s get started with the JSON Builder. To add nodes to the JSON body, select the ‘+’ icon as displayed below:

When adding a new node, first we need to set the Node Name, a name to define the value.

You can type in a static node name (the most commonly used option) or dynamically define a node name by clicking the edit icon on the right side of the input. The edit button opens a popup with various options for dynamic node name generation, including using a field from the main object, a formula, a custom label, a custom metadata value, or a custom setting value.

Then we need to select the type of JSON node this node will be. We have options to select either “Object”, “List of Objects”, “Single Value”, “List of Values”. If you want to build this node using Apex, choose the “Built using an Apex Class” option.

Here are a few more details to help you on your Node Type selection:

• Object: This will create an object node in JSON, containing another structure of key-value pairs. You only need to provide the name of the node. After adding the Object node, you can add additional nodes inside this object by clicking the “+” button inside the newly created node.
• List of Objects: If this is selected, it will generate a list of objects in JSON.
  • To create a JSON list with a single element, simply leave the ‘Using Related List‘ input blank. This allows you to map fields from the main record (or child record if you are already in another list) to the nodes inside the JSON list.
    
    • 
  • To create a JSON list with multiple elements based on a related list of the main object, choose the desired list in the Using Related List or Related Object input. Options include selecting a related list from the Main Object, an object related to it, or even grandchildren-related lists. Once chosen, you can map fields from the selected related list into the nodes within the JSON list.
    
    • 
  • To create a JSON list with manually defined elements, known as a parameter list, navigate to the ‘Advanced’ section within the ‘Edit Node’ popup. In the Build this JSON List input, select ‘As a Parameter list based on fields.‘ If chosen, you can manually add list elements later, specifying values for each node in each list element. Learn more about parameter lists.
    
    • 

• List of Values: If you select this option, you can send a list of values in the node. You can manually define a list of static values or you can map a field, custom label, custom metadata, custom settings, build a formula, etc. You can also build the list manually with values from different sources by selecting the Define each element in the list individually option, See Selecting a Source below for details.
• Single Value: Use this option to send single values in a node. It can be a static text, number, a field, etc mapped to the value of the node. See Selecting a Source below for details.
• Manually entered JSON: This option allows you to manually define the JSON node. You can provide the exact JSON to be sent and merge custom fields, custom label, custom metadata and custom settings in it. Learn more about manually entered JSON.
• Built using an Apex Class: This gives you the option to use an Apex class to generate this node. Learn more about using Apex to generate a node

 

Selecting a Source

If you select “List of Values” or “Single Value” in the Node Type input, you are able to select a source for the value. That can be a Static value, a Field from the current record, a Formula based on the fields of the current record, a Custom Label, a value from a Custom Metadata record, a value from a Custom Settings record, an Input Parameter or Build a JWT node. For “List of Values” option, you also have the option to “Define each element in the list individually”.

• Static Value: This is a static option for if you want to send the same value every time the callout is made. Enter the value you want it to send in the Static Value field. If you choose “Array”, enter all the values that you want to send, one per line.

• Field from Main Record: Here you can select any field from the Main Object or related objects you selected in the Callout Template. If you select a related list of objects and Node Type is Array, it will create a list with values from each related record.
  •  
  • The Field Selector allows you to select fields from the Main Object, any related object and any related list, as well as values from more complex relationships. For example, if the Main Object is Account, the selection below allows you to select the Username of the Owner of the account.
  • 
  • For List of Values type of nodes, when you select a field, you can specify a character to split the mapped field, to generate a list of values. For example, if you want to map a multi-select picklist field, specify the “;” character in the Split Field Value by input. If the field has one value per line, specify “\n” in the Split Field Value by input.
  • If the selected field is a Blob field (for example Attachment -> Body or ContentVersion -> VersionData), then you will also be asked to provide the encoding to be used: Base64, Hex or Raw (which only works for UTF-8 content)

• Formula: This allows you to build a formula using the current object’s fields that will be used to generate the node. 
  • 
  • Clicking the Edit icon will open the Formula editor. See more details in the “Using Formulas” section of this user guide.
  • 
• Custom Label: This option allows you to provide a custom label name to be mapped in that node.
• Custom Metadata: This allows you to map a field from a Custom Metadata Type record.
  • 
  • Clicking the Edit icon will open the Custom Metadata selector.
  • 
• Custom Setting: This allows you to map a field from a Hierarchy or List Custom Setting record.
  • 
  • Clicking the Edit icon will open the Custom Setting selector.
  • 
• Input parameter: This allows you to use an input parameter when the call is made from a flow. Learn more about input parameters.
• Build a JWT: This allows you to build a JWT token to be sent to the external system. Learn more about JWT nodes.
• Define each element in the list individually: This allows you to select a source for each value added to the list. This helps you build more complex lists that are defined based on criteria.
  • 

 

Node Data Type

This lets you choose the data type of the JSON node value. It can be Text, Number or a True/False value. Text values include out of the box fields like First Name, Last Name, Description and so on. Any field in Salesforce that is a data type of the following will need to be Text:

• Auto-Number
• Email
• Phone
• Text
• Text Area
• Text Area (Long)
• Text Area (Rich)
• Text Area (Encrypted)
• URL

When you are mapping Date or DateTime fields, you need to use Text as well. Unless formatted using a formula, the Date fields are sent in the standard yyyy-MM-dd format and the DateTime fields are set in the standard yyyy-MM-ddTHH:mm:ss.sssZ format.

When Text is selected, you have the option to send empty strings when a value is null. If that option is selected, if the mapped value is null, then an empty string is sent instead. You can find that option in the “Advanced” section of the “Edit Node” popup.

 

Dynamically generating nodes (node criteria)

“In the Advanced section of the Edit Node popup, you can determine whether a node is generated during runtime by utilizing a formula. Locate the This node is generated (criteria) field. By default, it is set to Always, but you have the option to edit it and incorporate a formula. This allows you to dynamically decide if the node should be generated based on criteria from the main object.

 

Create from sample JSON request

If you have a JSON Sample from the API documentation from the app or platform being implemented, you can create your Request Body quickly by utilizing the ‘Generate from sample JSON’ button. This enables you to quickly map your Main Object to your external system bypassing creating Node Names with stand-in values.

One example may be Quickbooks. Let’s say you are looking at the Account Request Body details on the API documentation of QuickBooks. You can find a Request Body sample to copy and pull into the Declarative Webhooks app:

 

After you copy the Request Body, select the ‘Generate from sample JSON’ button and paste your example.

Click “Generate and replace exiting body” and you will see this has been added into the Request Body of your Callout Template. From here, you can begin mapping Salesforce fields from your Main Object by selecting the edit icon next to the row and replacing the static values from the sample body. This helps you to quickly map without having to manually create each Node Name with a provided guide from your external system API documentation.

NOTE: If you have started mapping in the JSON Builder and you opt to utilize the ‘Generate from sample JSON’ button, your previous mapping will be overwritten. It is advised you begin with your sample JSON first before mapping additional Nodes.  

 

Generate based on fields from Main Object

If you want to generate the JSON body based on fields from the main object, click the “Generate from Main Object fields” button.

It will open a popup that will allow you to select the fields used to generate the body.

Once you select all the fields, click “Generate and replace existing body” and see the JSON body being generated for you.

NOTE: If you have started mapping in the JSON Builder and you opt to utilize the ‘Generate from Main Object fields’ button, your previous request body will be overwritten.