Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

JSON and XML functors

Use functors to select info from JSON/XML sources.

This topic describes how to use JSON and XML functors to select contents from JSON and XML sources.

These functors reduce the amount of shell scripting needed to pull JSON and XML information into your Harness Pipeline steps.

JSON Functor

The JSON functor uses the JSON library JsonPath. The JSON functor methods are described below.

select()

  • Syntax: select(string, string)

  • Description: Select attribute values using a path.

  • Parameters: literal string, string (typically, the second string is httpResponseBody). This is a path to identify the desired JSON attribute value from a JSON response.

Example:

Here is the JSON array that we want to select a value from:

{  
  "data": {  
    "attributes": {  
      "name": "new-construction-api",  
      "version_pins": {  
        "mvn-service://new-construction-api": "0.0.253-feature_NC-6595.8d268cd~nc1.6312a66"  
      }  
    }  
  }  
}

You can find this example at https://raw.githubusercontent.com/wings-software/harness-docs/main/functors/select.json.

To select the value 0.0.253-feature_NC-6595.8d268cd~nc1.6312a66, you would use select() to specify the path to the value, like this:

The httpResponseBody argument is used to indicate that we want to select the path within the HTTP response body. httpResponseBody is propagated from the HTTP request.

A common use of select() is in an HTTP step.

For example, the following HTTP step uses a variable named book and the select() method in Value to obtain the value 0.0.253-feature_NC-6595.8d268cd~nc1.6312a66 from the HTTP response payload at the URL specified in URL.

When this HTTP step is executed, in its Output tab, you can see the HTTP response in HTTP Response Body and the selection in the Output Variables:

You can also use a Shell Script step to echo the book output like this:

When the Pipeline is executed, the value of book is output:

object()

  • Syntax: object(string)

  • Description: Selects objects from a JSON collection.

  • Parameters: string. This is a JSON key used to identify the desired JSON attribute value from a JSON response. Typically, httpResponseBody.

Example:

Here is the JSON we will query:

You can find this example at https://raw.githubusercontent.com/wings-software/harness-docs/main/functors/object.json.

Here is the query using the object() method to select value1:

We can add the object() method to an HTTP step and output it:

When this HTTP step is executed, in its Output tab, you can see the HTTP response in HTTP Response Body and the object in the Output Variables:

list()

  • Syntax: list(string, string)

  • Description: Returns list object.

  • Parameters: literal string, string (typically, httpResponseBody). Using the list().get() method returns items from the list.

Example:

Here is the JSON we will query:

You can find this example at https://raw.githubusercontent.com/wings-software/harness-docs/main/functors/books.json.

Here is the query using the list() method to select pages from the 3rd book:

Since the JSON array starts at 0, get(2) returns pages from the third list item ("pages": "460").

We can add the list() method to an HTTP step and output it using the variable list:

When this HTTP step is executed, in its Output tab, you can see the HTTP response in HTTP Response Body and the list item in the Output Variables:

format()

  • Syntax: format(object)

  • Description: Format the array passed as the string value in JSON format.

  • Parameters: object. Typically, this is the response from the HTTP response body (httpResponseBody). The httpResponseBody argument is used to indicate that we want to select the path within the HTTP response body. httpResponseBody is propagated from the HTTP request.

Example:

We add an HTTP step to obtain the httpResponseBody and then reference that in a subsequent Shell Script step.

We are using the example at https://raw.githubusercontent.com/wings-software/harness-docs/main/functors/select.json.

If we simply rendered the httpResponseBody, we would get:

If we render it using <+json.format(<+pipeline.stages.Functors.spec.execution.steps.jsonformat1.output.httpResponseBody>)> we get a JSON formatted string:

IMPORTANT

  1. JSON accepts the control sequence \n as strings. To format JSON, use jq to prettify the JSON.

  2. Conditional expressions within double quotes are considered strings.

    So, "<+json.select("fields.status.name", httpResponseBody)>"=="In Progress" is treated as string comparison and will not work.

    Use <+json.select("fields.status.name", httpResponseBody)>=="In Progress" instead.

    The keyword null, too, shouldn't be enclosed in quotes during comparison.

    Here's an example of a null comparison: <+json.object(httpResponseBody).fields.parent>!=null

Fetching and Masking Attributes from JSON Secrets

Users can now fetch attributes from JSON files marked as secrets and have them masked in the pipeline execution page outputs and execution logs by setting the output variable type to secret. This feature leverages a new functor called secretJson, along with support for the following functors: select(), list(), and object().

XML Functor

The XPath functor has one method: xml.select().

select()

  • Syntax: xml.select(string, string)

  • Description: Returns XML file.

  • Parameters: String using an XPath expression and XML file, and a string for httpResponseBody.

Example:

Here is the contents of the XML file we will query:

We are using the example at https://raw.githubusercontent.com/wings-software/harness-docs/main/functors/books.xml.

Here is the query using the xml.select() method to select the title from the first book:

We can add the xml.select() method to an HTTP step and output it using Response Mapping:

Next, we reference the output variable select in a Shell Script step:

When the Workflow is deployed, the result is:

You can also see the entire XML file in the deployment Details section:

YAML Pipeline Example

Here's the YAML for a Pipeline that demonstrates all of the functors.

Functors Pipeline YAML:

PreviousHTTP step
NextCommand step

Last updated

Was this helpful?