Skip to main content

searchAndReplaceOrdered

A Workflow Engine function that matches a regular expression to an object field and updates the values for fields in the object based upon a map. You can map the contents of subgroups to other fields. For example, extract the 'source' value inside a description and map it to the source field. You can also map fields to a constant value.

searchAndReplaceOrdered requires you to, with the exception of the $extract.n pattern, delimit field replacements with "$[<field>]". For example, $[description]. Otherwise, this function treats the replacement as a literal string.

This function differs from searchAndReplace in that you can provide the map as an array to preserve the mapping order. For efficiency reasons, only use this function instead if you require this functionality, or intend to supply the map as a set of key:value pairs.

For example, the ordered map:

[ 
    {"source": "${source]-1"}, 
    {"description": "$[description] $[source]"}
]

differs from the unordered map:

{ 
    "source": "${source]-1", 
    "description": "$[description] $[source]" 
}

This is because, given an event with source set to "host" and description set to "Failure for", the ordered map results in an updated event with source: "host-1" and description: "Failure for host-1". The unordered version has the same source, but the description is only "Failure for host", as it doesn't have access to the updated source value from the first operation.

This function is available for event, alert, and Situation workflows.

The workflow sweep up filter applies to this function.

Back to Workflow Engine Functions Reference.

Arguments

Workflow Engine function searchAndReplaceOrdered takes the following arguments:

Name

Required

Type

Description

field

Yes

String

Field to search.

expression

Yes

String

Regular expression pattern test against the field.

map

Yes

Object

Map to apply the extracted values to as a key : value pairing using $extract.n, where n = the subgroup identified.

For example [ { "custom_info.newValue" : "$extract.1" }, { "source" : "$extract.2" }, {"description" : "$[description] $extract.3" }].

Note

The code display for the Workflow Engine double-escapes characters. You do not need to double-escape in the data entry field. For example the IP address: "((?:\d+\.){3}\d+)".

When you have nested subgroups, as in the example with the IP address, they do not affect the extract numbering.

Example 1

The following example demonstrates typical use of Workflow Engine function searchAndReplaceOrdered.

Set the following:

  • field: description

  • expression: Event for (host\d+)

  • map: [{"custom_info.eventDetails.manager":"$[source]"},{"source":"$extract.1"},{"description":"$[class] $[type] event: destination $[source] unreachable"}]

    This defines the following mapping:

    • Save the original value of source as the value of manager.

    • Replace the original value of source with an extract from description.

    • Update the description with a statement which references the values of class, type, and the updated source field.

The UI translates your settings to the following JSON:

{
  "field": "description",
  "expression": "Event for (host\d+)",
  "map": [
    {
      "manager": "$[manager]::$[source]"
    },
    {
      "source": "$extract.1"
    },
    {
      "description": "$[class] $[type] event: destination $[source] unreachable"
    }
  ]
}

With this mapping, given the following event:

{
  "signature": "network::availability::host10",
  "source_id": "192.168.1.1",
  "manager": "Pinger",
  "source": "ping-host1",
  "class": "network",
  "agent": "RESTLam",
  "type": "availability",
  "severity": 5,
  "description": "Event for host10",
  "agent_time": 1581951814000,
  "custom_info": = {}
}

The function transforms the event payload to:

{
  "signature": "network::availability::host10",
  "source_id": "192.168.1.1",
  "manager": "Pinger::ping-host-1",
  "source": "host10",
  "class": "network",
  "agent": "RESTLam",
  "type": "availability",
  "severity": 5,
  "description": "network availability event: destination host10 unreachable",
  "agent_time": 1581951814000,
  "custom_info": = {}
}

Example 2

This example makes use of the mapping order to update the description using a source value that a previous mapping assigned.

You can provide the map as an array to preserve the mapping order. For efficiency reasons, only use this functionality if you require it. Otherwise, supply the map as a set of key:value pairs. For example:

map: {"custom_info.eventDetails.manager":"$[source]" , "source":"$extract.1", "description":"$[class] $[type] event: destination $[source] unreachable"}

This defines the following mapping:

  • map: {"custom_info.eventDetails.manager":"$[source]" , "source":"$extract.1", "description":"$[class] $[type] event: destination $[source] unreachable"}

    This defines the following mapping:

    • Save the original value of source as the value of manager.

    • Replace the original value of source with an extract from description.

    • Update the description with a statement which references the values of class, type, and the original source field.

With the same field and expression arguments as Example 1, the UI translates your settings to the following JSON:

{
  "field": "description",
  "expression": "Event for (host\d+)",
  "map": {
      "manager": "$[manager]::$[source]",
      "source": "$extract.1",
      "description": "$[class] $[type] event: desination $[source] unreachable"
  }
}

With this mapping, given the same event as before:

{
  "signature": "network::availability::host10",
  "source_id": "192.168.1.1",
  "manager": "Pinger",
  "source": "ping-host1",
  "class": "network",
  "agent": "RESTLam",
  "type": "availability",
  "severity": 5,
  "description": "Event for host10",
  "agent_time": 1581951814000,
  "custom_info": = {}
}

The event payload is now:

{
  "signature": "network::availability::host10",
  "source_id": "192.168.1.1",
  "manager": "Pinger::ping-host-1",
  "source": "host10",
  "class": "network",
  "agent": "RESTLam",
  "type": "availability",
  "severity": 5,
  "description": "network availability event: destination ping-host-1 unreachable",
  "agent_time": 1581951814000,
  "custom_info": = {}
}

description now contains the original value of source as this time you have defined map as key:value pairs rather than an array.

In this section: