getObjectValuesFromList

A Workflow Engine function that allows keys to be extracted from a list of anonymous objects based on a “trigger” key and value. An anonymous list is an array containing a list of objects.

[
   { ... },
   { ... },
   ...
   { ... }
]

For example:

"serviceData" : [
    {       
        "name": "NotifyUser",
        "value": "true",    
        "user" : "fred@bigco.com"
    },
    {
        "name": "ServiceName",
        "value": "Service1",
        "location" : "London"
    },
    {
        "name": "ServiceName",
        "value": "Service2",
        "location" : "Paris"
    }
]

serviceData is an array (list) containing 3 anonymous objects, with each object containing key: value pairs.

This function allows you to extract one or more keys from the objects in the list, based on the value of a key and value within the object. For example, you can extract the “location” value from objects where the “name” has a value of “ServiceName”.

This function will extract the specified keys and create a new object in either the source CEvent (event, alert or Situation) or the workflowContext.

This function is available as a feature of the Add-ons v2.4 download and later.

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

Back to Workflow Engine Functions Reference.

Arguments

Workflow Engine function getObjectValuesFromList takes the following arguments:

Name	Required	Type	Description
`source`	yes	string	The source field. Must be an array of objects.
`keyName`	yes	string	The name of the “trigger” key. Extraction will only be performed on an object that has this key populated with the `keyValue` value.
`keyValue`	yes	string	The value of `keyName` to “filter” on. This can either be an equality check (case and whitespace sensitive) or a positive or negative regular expression.
`values`	yes	object	A list of keys to extract from target objects.
`destination`	yes	string	Either the CEvent field, or the `workflowContext` field to write the results to.
`extractAll`	no	string (true\|false)	Either "true" or "false". Determines whether values should be consolidated if more than one anonymous object has the trigger condition.

Examples

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

Given this list of anonymous objects within custom_info.serviceData:

"custom_info" : {
  serviceData" : [
    {       
        "name": "NotifyUser",
        "value": "true",    
        "user" : "fred@bigco.com",
        "userRole" : "operator"
    },
    {
        "name": "ServiceName",
        "value": "Service1",
        "location" : "London"
    },
    {
        "name": "ServiceName",
        "value": "Service2",
        "location" : "Paris"
    }
  ]
}

It is not possible to use other WorkflowEngine functions to get the value for the user. This is because the object position within the list cannot be guaranteed. As such, trying to extract using a copyToContext action with a JSON path of

custom_info.serviceData[0].user

may work for some events, but not others.

To extract the user value consistently, we can use the getObjectValuesFromList action. We will specify the keyName and keyValue we are looking for, along with a list of the attributes (keys) that we want to extract. The extracted value(s) can then be written to a known consistent location within custom_info or the workflowContext.

For this example, we can use the following action parameters:

source : custom_info.serviceData
keyName : name
keyValue : NotifyUser
values : [ “user” ]
destination : workflowContext.userDetails
extractAll : false

In the UI this is displayed as:

{"source":"custom_info.serviceData","keyName":"name","keyValue":"NotifyUser","values":["user"],"destination":"custom_info.test"}

And produces a result in the workflowContext of:

{
    "userDetails": {
        "name": "NotifyUser",
        "user": "fred@bigco.com"
    }
}

This can then be accurately referenced by other actions using a consistent JSON path.

If multiple keys need to be extracted, we can add these to the values list:

For example, to extract both user and userRole, we would use the following:

{"source":"custom_info.serviceData","keyName":"name","keyValue":"NotifyUser","values":["user", "userRole"],"destination":"custom_info.test"}

This produces an extracted object:

{
    "userDetails": {
        "name": "NotifyUser",
        "user": "fred@bigco.com",
        "userRole": "operator"
    }
}

If the list contains multiple matching triggers, then setting the extractAll parameter changes the behavior.

By default, if the list contains multiple matching objects, then the last object’s values are extracted.
If extractAll is set to true, then the results will contain a list of values for the extracted keys.

For example, if the serviceData above had two entries for NotifyUser:

"custom_info" : {
  serviceData" : [
    {       
        "name": "NotifyUser",
        "value": "true",    
        "user" : "fred@bigco.com",
        "userRole" : "operator"
    },
    {       
        "name": "NotifyUser",
        "value": "true",    
        "user" : "barney@bigco.com",
        "userRole" : "administrator"
    }
  ]
}

With extractAll set to false (default), the resulting object would contain just a single value:

{
    "userDetails": {
        "name": "NotifyUser",
        "user": "barney@bigco.com",
        "userRole": "administrator"
    }
}

With extractAll set to true, the resulting object would contain a list of values. Each list will be in order (i.e. position 0 in user corresponds to position 0 in userRole).

{
    "userDetails": {
        "name": "NotifyUser",
        "user": [
            "fred@bigco.com",
            "barney@bigco.com"
        ],
        "userRole": [
            "operator",
            "administrator"
        ]
    }
}

If objects do not contain the same payload, for example if userRole was missing, then this ordering is lost. If a key cannot be found in an object, no value will be inserted into the list.

Using Regular Expressions For keyValue

The keyValue parameter can be expressed in three ways:

An equality check - case and whitespace sensitive.
A positive regular expression
A negative regular expression

Given the following list of objects:

"custom_info" : {
  serviceData" : [
    {       
        "name": "NotifyUser",
        "value": "true",    
        "user" : "fred@bigco.com",
        "userRole" : "operator"
    },
    {       
        "name": "ServiceName",
        "value": "Service1",   
        "location": "London"
    }
  ]
}

The following equality check in the keyValue:

{ ... ,"keyName":"name","keyValue":"NotifyUser", ...}

would identify:

    {       
        "name": "NotifyUser",
        "value": "true",    
        "user" : "fred@bigco.com",
        "userRole" : "operator"
    },

as a match (i.e. “name === NotifyUser” ).

A positive regular expression (select all objects where the regular expression matches the. “/…./” syntax):

{ ... ,"keyName":"name","keyValue":"/^notify/", ...}

would identify

    {       
        "name": "NotifyUser",
        "value": "true",    
        "user" : "fred@bigco.com",
        "userRole" : "operator"
    },

as a match (i.e. name matches "/^notify/" - a case insensitive regular expression).

A negative regular expression (select all objects where the regular expression does not match using the “!/…./” syntax - note the "!" at the beginning of the string):

{ ... ,"keyName":"name","keyValue":"!/^notify/", ...}

would identify

    {       
        "name": "ServiceName",
        "value": "Service1",   
        "location": "London"
    }

as a match (i.e. name does not match "/^notify/").

In this section:

getObjectValuesFromList

Arguments

Examples

Using Regular Expressions For keyValue

Search results