Payload Builder step

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 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 Payload Builder step

    The Payload Builder step enables action designers in Workflow Studio to create dynamic JSON or XML payloads by defining name-value pairs. These pairs can incorporate dynamic data through drag-and-drop of data pills, allowing flexible and customizable payload generation. This step is available to users with theactiondesignerrole and is useful for building structured payloads for integrations and workflows.

    Show full answer Show less

    Note that for JSON payloads, this step is deprecated and replaced by the JSON Builder step, but it remains applicable for XML or legacy JSON use cases.

    Key Features

    • Name-Value Pairs: Define keys (JSON) or elements (XML) with dynamic values using data pills, supporting flexible payload content.
    • Output Format: Choose between JSON or XML for the payload structure.
    • Namespace (XML only): Specify an XML namespace prefix applied to each element for proper XML formatting.
    • Include Outer Structure: Optionally wrap name-value pairs in a top-level container element (e.g., curly braces for JSON, or an XML element).
    • Omit if Empty: Exclude name-value pairs with empty or null values to avoid sending unnecessary data.
    • Send Empty Structure: Control whether empty payloads produce valid empty JSON ({}) or XML (<xml></xml>) structures, or no payload at all.
    • Parent Node (XML only): Customize the container element name for the XML outer structure.
    • Preview: View the generated payload to verify structure and content before execution.
    • Action Error Evaluation: Configure error handling behavior to continue or halt workflow execution if the step fails, enabling robust custom action design.

    Practical Application for ServiceNow Customers

    This step streamlines the creation of structured payloads necessary for integrating ServiceNow workflows with external systems or APIs. By using dynamic data pills, customers can tailor payload content based on runtime data, improving integration accuracy and flexibility. The ability to choose output format and control empty payload behavior helps ensure that payloads meet the requirements of target systems.

    Customers should be aware that for JSON payloads, transitioning to the newer JSON Builder step is recommended. However, the Payload Builder step remains valuable for XML payloads or when maintaining legacy action steps.

    By leveraging the error evaluation options, customers can design more resilient workflows that appropriately handle failures during payload construction.

    Enable action designers to easily create name-value pairs in JSON and XML payloads using dynamic data.

    Roles and availability

    Available as an Workflow Studio action step. Users with the action_designer role can create a custom action with one or more action steps.
    Note:
    For JSON, this step is deprecated and replaced by the JSON Builder step.

    Fields

    Fields Description
    Name Value Pairs

    The name-value pairs to include in the payload. Click the plus icon to add name-value pairs. Drag data pills into either field to produce dynamic payloads.

    The Name becomes a key in JSON and an element in XML. For example, suppose you create this name-value pair.
    • Name: short_description
    • Value: [action]->[short_description]
    When the system formats the name-value pair as JSON:
    "short_description": "[action]->[short_description]"

    When the system formats the name-value pair as XML:

    <short_description>[action]->[short_description]</short_description>
    Omit if empty The option to exclude a name-value pair if the value is empty or null.
    Note:
    This field is only visible after clicking the down arrow to display advanced options.
    Output Format The payload file format.
    • JSON: Select to format the payload as a JSON document.
    • XML: Select to format the payload as an XML document.
    Namespace The XML namespace to apply to each element. For example, when the namespace is set to incident:
    <incident:short_description>[action]->[short_description]</incident:short_description>
    Note:
    This field is only visible when the Output Format is set to XML.
    Include Outer Structure

    The option to include or exclude a top level container appropriate to the output format. When the Output Format is JSON, curly braces contain the name-value pairs. When the Output Format is XML, a specified XML element contains the name-value pairs.

    For example, when the system formats the name-value pair as JSON:

    {
  "short_description": "[action]->[short_description]"
}

    When the system formats the name-value pair as XML:

    <xml>
  <short_description>[action]->[short_description]</short_description>
</xml>
    Send Empty Structure

    The option to send valid JSON or XML structures when the payload is empty. Enable this option to include JSON or XML structural text in the payload.

    For example, when the system formats an empty structure as JSON:
    {}

    When the system formats an empty structure as XML:

    <xml></xml>

    Disable this option to produce an empty payload.

    Empty payloads can occur when you select the Omit if empty option for every name-value pair, and all name-value pairs in the payload produce empty values.
    Parent Node The name of the XML element that contains the name-value pairs. The default parent node element is xml.
    Note:
    This field is only visible when the Output Format is set to XML and the option to Include Outer Structure is enabled.
    Preview The read-only payload the step produces.

    Action error evaluation

    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.