Skip to main content

convertField

A Workflow Engine function that converts a field value using mappings from the Conversion Maps integration.

The action looks up the value of the field in the conversion map. You can write the results of the lookup to a separate field with the optional target argument. If you don't specify a target, the function updates the source field in-line. Both the field and target arguments accept workflow context and payload keys. Specify the appropriate prefix, either workflowContext or payload.

The optional reversed argument defaults to “false”. If true, the lookup is performed in reverse. The Workflow Engine checks for the value against the conversion map alias to return the name.

The keys and values in the conversion maps are stored as strings. The optional type argument you to explicitly cast to one of the following primitive types: number, string, or boolean. For core target fields, there is implicit casting.

The return behavior of the action is controlled by the “no match” behavior settings in the conversion maps. See the examples below for details.

This function is available as a feature of the Add-ons v2.1 download and later. See Install Moogsoft Add-ons for information on how to upgrade.

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

Back to Workflow Engine Functions Reference.

Arguments

Workflow Engine function convertField takes the following arguments:

Name

Required

Type

Description

mapName

yes

string

Name of mapping.

field

yes

string

Name of field to convert.

target

no

string

Optional target field. If omitted, the supplied field will be updated.

type

no

string

Optional primitive return type: 'string', 'number', 'boolean'. Defaults to 'string'.

reversed

no

string

Apply mapping in reverse: 'true' or 'false'.

Example

Basic conversions

A conversion map “User” has been created with the following values:

  • case sensitive : false

  • no match behavior : "default"

  • default value : "unknown_user"

name

alias

user1

new_user1

user2

new_user2

An event workflow is defined containing the convertField action with the following arguments:

Argument Name

Argument Value

mapName

User

field

custom_info.user

target

custom_info.updatedUser

type

string

reversed

false

Which the UI translates to:

{"mapName":"User","field":"custom_info.user", "target": "custom_info.updatedUser", "type": "string", "reversed": "false"}

An event enters the workflow with the following custom_info:

{
  "user": "user1"
}

The action returns true and updates the event to have the custom_info:

{
  "user": "user1",
  "updatedUser": "new_user1"
}

If a new event is received with the custom_info:

{
  "user": "user3"
}

The action again returns true but updates the event using the conversion map default value:

{
  "user": "user1",
  "updatedUser": "unknown_user"
}

If the “User” conversion map had used the “exclude” no match behavior instead, the action would have returned false and the event would have remained unchanged.

If the “User” conversion map had used the “retain” no match behavior, the action would have returned true and the original value would have been copied into the ‘target’:

{
  "user": "user1",
  "updatedUser": "user1"
}

List conversions

If a field holds a list of primitive values, the conversion is applied to each element of the list.

Using the conversion map and workflow above, add an event with the following custom_info:

{
  "user": [ "user1", "user2", "user3" ]
}

Would result in the following results depending on the “no match” behavior:

retain

Returns true and updates custom_info to:

{
  "user": [ "user1", "user2", "user3" ],
  "updatedUser": [ "new_user1", "new_user2", "user3" ]
}
default

Returns true and updates custom_info to:

{
  "user": [ "user1", "user2", "user3" ],
  "updatedUser": [ "new_user1", "new_user2", "unknown_user" ]
}
exclude

Returns true and updates custom_info to:

{
  "user": [ "user1", "user2", "user3" ],
  "updatedUser": [ "new_user1", "new_user2" ]
}

In this last example, the returned list excludes the unconvertible value.

A special case for list conversion is when the field holds is a CSV list. The list is split into elements, which are converted and joined to produce a new CSV list, which may have fewer elements.

Casting target type

The conversion process treats all values as strings and produces string results. The "type" argument allows the results to be explicitly casted to either numbers or booleans. For core target fields, there is implicit casting.

For example, a conversion map “Severity” has been created with the following values:

  • case sensitive : false

  • no match behavior : "default"

  • default value : "1"

name

alias

Critical

5

Major

4

Minor

3

Warning

2

Intermediate

1

Clear

0

An event workflow is defined containing the convertField action with the following arguments:

Argument Name

Argument Value

mapName

Severity

field

custom_info.severity

target

severity

type

reversed

Which the UI translates to:

{"mapName":"Severity","field":"custom_info.severity", "target": "severity"}

An event enters the workflow with the following custom_info:

{
  "severity": "warning"
}

The convertField action finds the string value “2” in the Severity conversion map. The target is “severity”, which is a core field that expects an integer value, so it is implicitly casted to a number and used to set the event severity.

The following core fields are implicitly casted:

Field

Event Types

Field Type

signature

event, alert, alertUpdate, alertClose

string

source_id

event, alert, alertUpdate, alertClose

string

external_id

event, alert, alertUpdate, alertClose

string

manager

event, alert, alertUpdate, alertClose

string

source

event, alert, alertUpdate, alertClose

string

class

event, alert, alertUpdate, alertClose

string

agent

event, alert, alertUpdate, alertClose

string

agent_location

event, alert, alertUpdate, alertClose

string

type

event, alert, alertUpdate, alertClose

string

description

event ,alert, alertUpdate, alertClose, sig, sigUpdate, sigClose

string

severity

event, alert, alertUpdate, alertClose

number

internal_priority

sig, sigUpdate, sigClose

number

Updating other core fields with the convertField action will fail.

For the custom_info, workFlowContext and payload fields, the type can be explicitly casted as required.

Casting to the number type

Fields containing single values will either result in a valid number equivalent to the string or the action will fail:

  • “1” becomes 1 and the action returns true.

  • “one” is just a string, won’t conversion and the action returns false.

For fields containing an array of values, any convertible strings become 0:

  • [“1', “one” ] becomes [1, 0] and the action will return true.

Casting to the boolean type

An empty string with any of the following becomes false: “false”, “0”, “-0”, “null”, “NaN”, “undefined”.

Any other non-empty string becomes true.

Casting CSV lists

For fields containing CSV lists, casting is applied after converting and joining to the new CSV string as a whole.

In this section: