JSON Builder step

  • Release version: Zurich
  • Updated July 31, 2025
  • 3 minutes to read
    • Summarize
    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 Workflow Studio allows you to create JSON payloads for use in subsequent steps of an action. It supports dynamic input through values or data pills and can handle various data types, including nested objects and arrays. This step requires an Integration Hub subscription and is accessible to users with theactiondesignerrole once the necessary plugin is activated.

    Show full answer Show less

    Inputs and Configuration

    • Name and Value: Define each name-value pair with static values or dynamic data pills to build the JSON payload.
    • Type: Specify the data type of each name-value pair (String, Object, Number, Boolean, Array) to ensure data consistency.
    • Handling Empty Values: Choose how to handle empty or null values with options to leave as is, omit the property, set as null, or throw an error.
    • Structural Options: Include options to add outer curly braces for the top-level JSON container and to omit empty payloads when all values are empty or omitted.
    • Error Handling: Configure behavior if the step fails, either continuing to the next step or triggering error evaluation.

    Outputs

    • Output: Produces the JSON payload as a string, which can be parsed into an object in later steps if needed.
    • Step Status: Provides runtime details including an integer code (0 for success, 1 for error) and an error message if applicable.

    JSON Payload Generator

    The step includes an Add JSON for Payload feature that allows automatic generation of the JSON structure from a JSON script. Key considerations when using this feature:

    • Empty keys are accepted, but duplicate keys will have the last occurrence override earlier ones.
    • Root arrays are wrapped into objects, and keys from multiple objects in arrays are merged.
    • Limitations include no support for empty payloads, non-complex object types, invalid JSON, empty root objects, or payloads larger than 65,000 bytes.
    • Using the generator will overwrite any existing JSON structure in the step.

    Practical Use for ServiceNow Customers

    This step is essential for integrating and orchestrating workflows that require structured JSON data. It provides flexibility to create dynamic payloads tailored to your integration needs. Understanding input types and empty value handling ensures your payload accurately reflects the desired data state, improving data integrity and reducing errors during API calls or downstream processing.

    By leveraging the automatic JSON payload generator, you can quickly build complex JSON structures from existing JSON scripts, streamlining action development. The detailed step status outputs help in troubleshooting and handling errors effectively within your custom actions.

    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

    This step requires an Integration Hub subscription. For more information, see Legal schedules - Integration Hub overview. 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

    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.

    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

    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.
    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.

    Outputs

    These outputs appear in the Data panel. You can use them as inputs elsewhere in your action.

    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 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

    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.
    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
    Note:
    Generating a JSON payload overrides any existing structures in the JSON Builder step.