Network Functions

Functions relating to networking (host names, IP addresses, etc.) or making remote calls.

`cidr-to-numeric-ip-range`

cidr-to-numeric-ip-range(cidr)➡Sequence

Converts a CIDR IP address range to an array of numeric IP addresses representing the start and end (broadcast) of the range.

When storing the result in a variable, ensure you indicate the type as a string array (xs:string*).

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`cidr`	String		-	-		-	The CIDR range to convert, for example `192.168.1.0/24`.

Return Value:

Type	Description
Sequence	An array containing the start and end addresses as numeric strings.

Example

XSLT:

<xsl:variable name="range" select="stroom:cidr-to-numeric-ip-range('192.168.1.0/24')" as="xs:string*" />
<Range>
  <Start><xsl:value-of select="$range[1]" /></Start>
  <End><xsl:value-of select="$range[2]" /></End>
</Range>

XML:

<Range>
  <Start>3232235776</Start>
  <End>3232236031</End>
</Range>

`fetch-json`

fetch-json(url, [clientConfig])➡Sequence

Sends an HTTP GET request and converts a JSON response body to XML using json-to-xml(). A 404 response produces an empty sequence.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`url`	String		-	-		-	The URL to fetch.
`clientConfig`	String		-	-		-	Optional JSON HTTP client configuration, including SSL settings.

Return Value:

Type	Description
Sequence	The XML representation of the JSON response, or an empty sequence when no usable response is returned.

`host-address`

host-address(hostname, [ignoreWarnings])➡String

Resolves a host name to an IP address.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`hostname`	String		-	-		-	The host name to resolve.
`ignoreWarnings`	Boolean		-	-		-	Suppress resolution warnings when `true`.

Return Value:

Type	Description
String	The resolved IP address, or an empty sequence if resolution fails.

`host-name`

host-name(ipAddress, [ignoreWarnings])➡String

Resolves an IP address to a host name.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`ipAddress`	String		-	-		-	The IP address to resolve.
`ignoreWarnings`	Boolean		-	-		-	Suppress resolution warnings when `true`.

Return Value:

Type	Description
String	The resolved host name, or an empty sequence if resolution fails.

`http-call`

http-call(url, [headers], [mediaType], [data], [clientConfig])➡Sequence

Sends an HTTP POST request and returns a stroom-http XML response containing the status, headers and body. The request body is optional.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`url`	String	-	-	-	The URL to request.
`headers`	String	-	-	-	Optional newline-separated HTTP headers in `name:value` form.
`mediaType`	String	`application/json; charset=utf-8`	-	-	The request media type; defaults to `application/json; charset=utf-8`.
`data`	String	-	-	-	Optional request body.
`clientConfig`	String	-	-	-	Optional JSON HTTP client configuration, including SSL settings.

Return Value:

Type	Description
Sequence	An XML response document containing the response or an error.

`clientConfig`

The HTTP client can be configured using the clienConfig argument. This is a JSON object containing various optional configuration items. The following is an example of the client configuration object with all keys populated.

{
  "callTimeout": "PT30S",
  "connectionTimeout": "PT30S",
  "followRedirects": false,
  "followSslRedirects": false,
  "httpProtocols": [
    "http/2",
    "http/1.1"
  ],
  "readTimeout": "PT30S",
  "retryOnConnectionFailure": true,
  "sslConfig": {
    "keyStorePassword": "password",
    "keyStorePath": "/some/path/client.jks",
    "keyStoreType": "JKS",
    "trustStorePassword": "password",
    "trustStorePath": "/some/path/ca.jks",
    "trustStoreType": "JKS",
    "sslProtocol": "TLSv1.2",
    "hostnameVerificationEnabled": false
  },
  "writeTimeout": "PT30S"
}

If you are using two-way SSL then you may need to set the protocol to HTTP/1.1.

  "httpProtocols": [
    "http/1.1"
  ],

Example Output

The following is an example of the XML returned from the http-call function:

<response xmlns="stroom-http">
  <successful>true</successful>
  <code>200</code>
  <message>OK</message>
  <headers>
    <header>
      <key>cache-control</key>
      <value>public, max-age=600</value>
    </header>
    <header>
      <key>connection</key>
      <value>keep-alive</value>
    </header>
    <header>
      <key>content-length</key>
      <value>108</value>
    </header>
    <header>
      <key>content-type</key>
      <value>application/json;charset=iso-8859-1</value>
    </header>
    <header>
      <key>date</key>
      <value>Wed, 29 Jun 2022 13:03:38 GMT</value>
    </header>
    <header>
      <key>expires</key>
      <value>Wed, 29 Jun 2022 13:13:38 GMT</value>
    </header>
    <header>
      <key>server</key>
      <value>nginx/1.21.6</value>
    </header>
    <header>
      <key>vary</key>
      <value>Accept-Encoding</value>
    </header>
    <header>
      <key>x-content-type-options</key>
      <value>nosniff</value>
    </header>
    <header>
      <key>x-frame-options</key>
      <value>sameorigin</value>
    </header>
    <header>
      <key>x-xss-protection</key>
      <value>1; mode=block</value>
    </header>
  </headers>
  <body>{"buildDate":"2022-06-29T09:22:41.541886118Z","buildVersion":"SNAPSHOT","upDate":"2022-06-29T11:06:26.869Z"}</body>
</response>

Example Usage

This is an example of how to use the function call in your XSLT. It is recommended to place the clientConfig JSON in a Dictionary to make it easier to edit and to avoid having to escape all the quotes.

  ...
  <xsl:template match="record">
    ...
    <!-- Read the client config from a Dictionary into a variable -->
    <xsl:variable name="clientConfig" select="stroom:dictionary('HTTP Client Config')" />
    <!-- Make the HTTP call and store the response in a variable -->
    <xsl:variable name="response" select="stroom:http-call('https://reqbin.com/echo', null, null, null, $clientConfig)" />
    <!-- Apply 'response' templates to the response -->
    <xsl:apply-templates mode="response" select="$response" />
    ...
  </xsl:template>
  
  <xsl:template mode="response" match="http:response">
    <!-- Extract just the body of the response -->
    <val><xsl:value-of select="./http:body/text()" /></val>
  </xsl:template>
  ...

`ip-in-cidr`

ip-in-cidr(ipAddress, cidr)➡Boolean

Checks whether an IPv4 address lies within a CIDR range.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`ipAddress`	String		-	-		-	The IPv4 address to check.
`cidr`	String		-	-		-	The CIDR range, for example `192.168.1.0/24`.

Return Value:

Type	Description
Boolean	`true` if the address is in the range; otherwise `false`.

`numeric-ip`

numeric-ip(ipAddress)➡String

Converts an IP address to a numeric string suitable for range comparisons and reference data lookups.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`ipAddress`	String		-	-		-	The IP address to convert.

Return Value:

Type	Description
String	The numeric IP address, or an empty sequence if conversion fails.

Last modified October 20, 2026: Merge pull request #144 from gchq/add-7.14-rel-notes (2c6fb22)