---
sourceDocument: Australia Build workflows
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/build-workflows

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia Build workflows

ft:clusterId :

    - crworkflow

bundleId :

    - crworkflow

workflow :

    - Creator


---

# JSON Builder step

# JSON Builder step {#ariaid-title1}

* Release version: Australia
* 
* Updated March 12, 2026
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read

Summarize  
![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI  
This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.  

## Summary of JSON Builder step

The JSON Builder step in ServiceNow's Integration Hub allows you to create JSON payloads dynamically for use in subsequent workflow steps.
It supports multiple data types including strings, numbers, booleans, arrays, and objects, which enables building complex nested JSON structures.
This step is available as a Workflow Studio action step and requires the Integration Hub subscription and appropriate plugin activation.
Show full answer Show less  

## Inputs and Configuration

* **Name:** Specify the key name of each name-value pair, either as a static string or via dynamic data pills.
* **Value:** Define the value for each key, supporting static strings or dynamic pills. Complex object pills can be used but will overwrite existing children.
* **Type:** Choose the data type of the name-value pair (String, Object, Number, Boolean, Array). For objects and arrays, you can add nested pairs dynamically.
* **In case of empty value:** Configure handling of empty or null values with options to leave as empty string, omit the property, set as null, or throw an error.
* **Include Outer Structure:** Option to include curly braces around the top-level JSON container.
* **Omit Empty Structure:** Option to omit the entire payload if it results empty due to omitted properties.
* **If this step fails:** Choose whether the workflow continues or evaluates error handling.

## Outputs

* **Output:** Provides the generated JSON payload as a string for use in later steps. Use the JSON parser step to convert this string into an object if needed.
* **Step Status:** Returns runtime details including an integer code (0 for success, 1 for error) and an error message if applicable.

## Generating JSON Payload Automatically

The JSON Builder includes a feature to auto-generate payloads using the "Add JSON for Payload" button, which opens a script editor. Here you can input raw JSON that will be deserialized into the builder's structured inputs. Important considerations when using this generator include:

* Empty keys are accepted, but duplicate keys are overridden by the last occurrence.
* If the root JSON is an array, it will be wrapped into a root object.
* Multiple objects inside arrays have their keys merged into a parent object.
* The generator does not support empty payloads, non-complex object types, invalid JSON, empty root objects (like empty arrays), or payloads larger than 65,000 bytes.
* Using this feature overwrites any existing JSON structure configured in the step.

## Practical Benefits for ServiceNow Customers

This step empowers you to create flexible, dynamic JSON payloads tailored to your integrations and workflows without manual JSON string construction. It ensures data integrity through type enforcement and provides options to handle empty values and errors gracefully. The automatic JSON generator accelerates payload creation from sample JSON, streamlining integration development.  
Create a JSON payload to use in another step. Enter values or use data pills to produce a dynamic payload. This step supports several data types, including objects and arrays for nested structures.

## Roles and availability {#json-build-step-action-designer__section_g22_gnn_gxb}

This step requires an Integration Hub subscription. For more information, see [Legal schedules - Integration Hub overview](https://www.servicenow.com/content/dam/servicenow-assets/public/en-us/doc-type/legal/snc-addendum-integrationhub.pdf).
After the required plugin is activated, the step is visible under Integrations.

Available as an Workflow Studio action step. Users with the action_designer role can create a custom action with one or more action steps.

## Inputs {#json-build-step-action-designer__section_fgp_z4n_gxb}

Provide a value for each input that your action needs. To add dynamic values, you can also drag and drop pills from the Data panel or select them from the pill picker.{#json-build-step-action-designer__inputs-description}

Name
:   Data type: String

    Name part of a name-value pair. Enter a value or use a data pill to produce a dynamic payload.

Value
:   Data type: String

    Value part of a name-value pair. Enter a value or use a data pill to produce a dynamic payload. You can use a complex object pill to populate a row with an object data type, but doing
    so deletes any children the complex object pill already has.

Type
:   Data type: Choice  
    Data type for the name-value pair. If you're using a data pill for the name or value, make sure the data type for the pill matches the data type selected here. The options are:

    * String
    * Object
    * Number
    * Boolean
    * Array
    {#json-build-step-action-designer__ul_kqt_v4p_xbc}

    For arrays and objects, use the plus icon (![plus icon]()) to add name-value pairs to the array or object.

In case of empty value
:   Data type: Choice  
    Option to specify what to do if a name-value pair has an empty or null value.

    * Leave as is: Keeps the empty or null value as an empty string.
    * Omit property: Excludes a name-value pair if the value is empty or null.
    * Set as null: Returns an empty or null value as a null data type.
    * Throw error: Returns an error if a name-value pair has an empty or null value.
    {#json-build-step-action-designer__ul_wtl_1pp_xbc}

Include Outer Structure
:   Data type: True/False

    Option to include the curly braces for a top-level JSON container.

Omit Empty Structure
:   Data type: True/False

    Option to omit an empty payload. Empty payloads can occur when you select Omit property for the In case of empty value input for every
    name-value pair and all name-value pairs in the payload produce empty values.

Structure
:   Data type: Structure

    Read-only payload the step produces.

If this step fails
:   Data type: Choice

    Option to continue running the next step or go to error evaluation. To use the step status code or message for a custom action error condition, see [Action error evaluation](https://servicenow-prod.fluidtopics.net/TJkLnvv_cE34AFa4p0LuVQ "Enable actions to catch step failures and continue running. Identify when specific error conditions occur and return your own action status code, status message, and error state.").

## Outputs {#json-build-step-action-designer__section_zch_jln_lyb}

These outputs appear in the Data panel. You can use them as inputs elsewhere in your action.{#json-build-step-action-designer__outputs-description}

Output
:   Data type: String

    JSON payload as a string. If you want to use the payload as an object, you can use the [JSON parser step](https://www.servicenow.com/docs/access?context=json-parser-step-action-designer&version=australia&pubname=australia-integrate-applications&ft:locale=en-US) to parse the string.

Step Status
:   Data type: Object

    Object data pill containing runtime details about the step. Each step in an action returns a Step Status.

Step Status \> Code
:   Data type: Integer

    Integer data pill indicating whether the step produced an error. By default, a value of 1 indicates that the step produced an error. A value of 0 indicates that the step ran
    successfully. You can't customize these codes.

Step Status \> Message
:   Data type: String

    String data pill containing the error message produced by the step or system operation. You can't customize this message.

## Generate a JSON Payload {#json-build-step-action-designer__section_okh_v3w_sbc}

Automatically generate a JSON payload with the Add JSON for Payload button. This button opens the Add Payload script editor where you can enter a JSON payload to be automatically de-serialized into structured
input.  
There are a few details to be aware of when using the JSON payload generator.

* If the JSON has empty keys, the payload is still generated.
* If there are duplicate keys in the script editor, the last key entry in the object overrides the value of any previous keys with the same name.
* If the root object is an array, the root array is wrapped into a root object.
* If an array contains multiple objects, all the keys in the objects are coalesced into one parent object.
{#json-build-step-action-designer__ul_t4t_dlw_sbc}  
The JSON payload generator doesn't support the following.

* empty payloads
* non-complex object types
* invalid JSON
* empty root objects, such as an empty array
* payloads larger than 65,000 bytes
{#json-build-step-action-designer__ul_igz_jkw_sbc}  
Note:  
Generating a JSON payload overrides any existing structures in the JSON Builder step.