FCOM Processor

The FCOM Processor microservice takes collected fault data from an input topic, runs it through fault common object models (FCOM) to normalize into an event structure, and sends the output to an output topic. The Event Sink microservice subscribes to the default output topic, but you can configure any topic for additional enrichment or suppression.

This microservice is part of the Event microservice pipeline. See Understanding the Event Pipeline in Unified Assurance Concepts for conceptual information.

Autoscaling is enabled by default for this microservice. You can optionally disable autoscaling when you deploy the microservice. See Configuring Autoscaling.

This microservice provides additional Prometheus monitoring metrics. See FCOM Processor Self-Monitoring Metrics.

FCOM Processor Prerequisites

Before deploying the microservice, confirm that the following prerequisites are met:

1. A microservice cluster is set up. See Microservice Cluster Setup.

2. The Apache Pulsar microservice is deployed. See Pulsar.

3. The Coherence microservices are deployed. See:

   • Coherence Operator

   • Coherence

Deploying FCOM Processor

To deploy the microservice, run the following commands:

su - assure1
export NAMESPACE=<namespace>
export WEBFQDN=<WebFQDN>
a1helm install <microservice-release-name> assure1/fcom-processor -n $NAMESPACE --set global.imageRegistry=$WEBFQDN

In the commands:

• <namespace> is the namespace where you are deploying the microservice. The default namespace is a1-zone1-pri, but you can change the zone number and, when deploying to a redundant cluster, change pri to sec.

• <WebFQDN> is the fully-qualified domain name of the primary presentation server for the cluster.

• <microservice-release-name> is the name to use for the microservice instance. Oracle recommends using the microservice name (fcom-processor) unless you are deploying multiple instances of the microservice to the same cluster.

You can also use the Unified Assurance UI to deploy microservices. See Deploying a Microservice by Using the UI for more information.

Changing FCOM Processor Configuration Parameters

When running the install command, you can optionally change default configuration parameter values by including them in the command with additional --set arguments. You can add as many additional --set arguments as you need.

For example:

• Set a parameter described in Default FCOM Processor Configuration by adding --set configData.<parameter_name>=<parameter_value>. For example, --set configData.LOG_LEVEL=DEBUG.

• Disable autoscaling for the microservice by adding --set autoscaling.enabled=false.

• Set an autoscaling parameter described in FCOM Processor Autoscaling Configuration by adding --set autoscaling.<parameter_name>=<parameter_value>. For example, --set autoscaling.thresholds.backlogSize=2000.

Default FCOM Processor Configuration

The following table describes the default configuration parameters found in the Helm chart under configData for the microservice.

FCOM Processor Autoscaling Configuration

Autoscaling is supported for the FCOM Processor microservice. See Configuring Autoscaling for general information and details about the standard autoscaling configurations.

The FCOM Processor microservice also supports the additional configurations described in the following table.

FCOM Processor Self-Monitoring Metrics

The FCOM Processor microservice exposes the self-monitoring metrics described in the following table to Prometheus.

FCOM Overrides

An FCOM override is a JSON file in an authoritative, language-neutral format that lets you override or build on FCOM Processors the basic processing steps.

After you create and upload an FCOM override to the directory set in the FCOM_FILES_LOCATION configuration parameter, you must restart the FCOM Processor microservice to load the new rules. When messages come in, the defined overrides run if the messages match the scope or objectName defined in any override.

Overrides can apply before or after messages are converted to events, and they can apply globally to all messages of a specific type (such as CORBA or Syslog) or only messages that match the objectName defined in the override (object-specific).

Overrides are applied in the following order:

1. Pre-conversion:

   1. Global

   2. Object-specific

2. Post-conversion:

   1. Object-specific

   2. Global

JSON Paths for Overrides

You can use the following JSON paths to access locations beyond the current message:

• $.lookups: References a lookup file value. The full path format is $.lookups.{lookupfile name}.{key}.

• $.foreach: Stores key-value pairs during the lifecycle of an iteration when using a foreach processor. The full path formats are:

  • For the key: $.foreach.{keyVal}

  • For the value: $.foreach.{valField}

  See foreach for more information.

• $.localmem: A local memory location. The value is cleared for each event. For example, you can set $.localmem.test in a pre-processor and then reference it in a post-processor.

• $.globalmem: A global memory location, accessible from all pods within a deployment. For example, $.globalmem.test. It requires Coherence to be running in the cluster. The values are only cleared when the Coherence microservice is restarted, or another processor removes it.

• $.error: Holds an error message based on the current state. For example, to set a field or print an error, you can reference an error thrown by a processor during runtime by using $.error.message in a processor.

FCOM Override Format

The following table describes the expected override properties.

For example, the following example override applies to all trap messages after they have been converted to events. It has two set processors to update the event summary and event type fields.

{
    "name": "Override Example",
    "description": "This is an example of a global FCOM override",
    "domain": "fault",
    "method": "trap",
    "scope": "post",
    "@objectName": "GLOBAL",
    "_type": "override",
    "processors": [
        {
            "set": {
                "source": "Hello, this is an example of overriding the event Summary field",
                "targetField": "$.event.Details"
            }
        },
        {
            "set": {
                "source": "Switch is down with value: %s",
                "args": [ "$.event.Details.trap.variables[0]" ],
                "targetField": "$.event.EventType"
            }
        }
    ]
}

When creating overrides, note the following:

• Fields and values prefixed with .event are only applicable when the scope is set to post. These fields do not exist until the message has been processed.

• While creating eval statements in trap rules, use ECMASCRIPT6 (ES6) syntax.

• The override processors support Java JSONPath syntax. For example, in a post processor, to refer to the following array in the event object:

  "variables" : [3,6,10,20,11]

  You would use the following syntax:

  $.event.variables[1]

  The descriptions of the processors below contain more examples.

FCOM Override Processors

You can use the processors described below in FCOM overrides.

append

This processor appends the value of source to the specified array and stores it in the specified target field. It uses the properties described in the following table.

The following example stores the text Example Value in the event.NewArray array. The resulting value of event.NewArray is [ "Example Value" ].

{
    "append": {
        "source": "Example Value",
        "array": [],
        "targetField": "$.event.NewArray"
    }
}

appendToOutputStream

This processor sends the value of source to the specified output, which is a Pulsar topic within the cluster. It uses the properties described in the following table.

The following example sends the value of the trap field to the assure1/event/sink topic:

{
    "appendToOutputStream": {
        "source": "$.trap",
        "output": "pulsar+ssl:///assure1/event/sink"
    }
}

break

This processor immediately breaks from an enclosing foreach loop.

Example format:

{
    "break": {
    }
}

See foreach for an example of this processor used with the foreach processor.

convert

This processor performs the conversion specified in type on the value of source and sets the value in the specified target field. It uses the properties described in the following table.

The following example converts the value of the event.Count field from an integer to a string and stores it in the event.CountString field. If an error occurs during the conversion, it continues to the next processor in the override.

{
    "convert": {
        "source": "$.event.Count",
        "type": "inttostring",
        "targetField": "$.event.CountString",
        "ignoreFailure": true
    }
}

copy

This processor copies the value of source to the specified target field. It uses the properties described in the following table.

The following example copies the value of the event.Count field to the event.CopiedCount field.

{
    "copy": {
        "source": "$.event.Count",
        "targetField": "$.event.CopiedCount"
    }
}

date

This processor converts the date in source to the specified timezone and stores it in the specified target field. It uses the properties described in the following table.

The following example converts the current UTC time, minus 2 hours and 45 minutes, to Eastern Standard Time, and stores it in the event.CurrentTimeInEST field.

{
    "date": {
        "source": "",
        "offset": "-2h45m",
        "timezone": "America/New_York",
        "targetField": "$.event.CurrentTimeInEST"
    }
}

discard

This processor immediately discards a message. When a message is discarded, no successive overrides are run on it, and it is not sent to the output topic. The FCOM Processor continues to the next message.

Example format:

{
    "discard": {
    }
}

foreach

This processor loops over an array or an object containing a key-value map. It uses the properties described in the following table.

The following example loops over the event.Details.trap.variables array, logging The index is <index> and the value is <value> for each item in the object, where <index> is the index number and <value> is the value. It breaks out of the loop when it reaches the fourth item in array.

{
    "foreach": {
        "source": "$.event.Details.trap.variables",
        "keyField": "i",
        "valField": "c",
        "then": [
            {
                "log": {
                    "source": "The index is %s and the value is %s",
                    "args": [
                        "$.foreach.i",
                        "$.foreach.c"
                    ],
                    "type": "info"
                }
            },
            {
                "if": {
                    "conditions": {
                        "and": [
                            {
                                "property": "$.foreach.i",
                                "operator": ">",
                                "value": 3
                            }
                        ]
                    },
                    "then": [
                        {
                            "break": {}
                        }
                    ],
                    "else": []
                }
            }
        ]
    }
}

grok

This processor runs a grok pattern on the source value and stores the result in the specified target. It uses the properties described in the following table.

The following example runs a grok pattern on the syslog.datagram field and stores the results in the syslog.variables field.

{
    "grok": {
        "source": "$.syslog.datagram",
        "pattern": "%LINK-5-CHANGED: Interface %{VALUE:interface}, changed state to %{VALUE:status}",
        "targetField": "$.syslog.variables"
    }
}

The following example shows a possible resulting value for syslog.variables:

"variables": {
    "interface": "Interface123",
    "status": "Available"
}

if

This processor evaluates a list of specified conditions and runs a specified array of processors if the conditions are true, or a different array of processors if they are false. It uses the properties described in the following table.

Conditions Properties

The conditions object of the if processor lets you specify the conditions to evaluate. It can contain an and or an or object at the top level, along with nested and and or objects. These objects contain the values to compare and the operator to use.

The and and or objects use the properties described in the following table. The examples after the table illustrate how to use the objects separately and nested together.

Basic Example

The following example shows how to use a single condition and run additional processors in the then, else, and onFailure properties. The processor:

• Checks if the event category is equal to 3.

• If the condition is true, it runs the log processor in the then block to log a message.

• If the condition is false, it runs log processor in the else block to log a different message.

• If an error occurs, it uses the log processor to log an error message, then continues processing.

{
    "if": {
        "conditions": {
            "and": [
                {
                    "property": "$.event.EventCategory",
                    "operator": "==",
                    "value": 3
                }
            ]
        },
        "then": [
            {
                "log": {
                    "source": "The event category is 3."
                }
            }
        ],
        "else": [
            {
                "log": {
                    "source": "The event category is not 3."
                }
            }
        ],
        "ignoreFailure": true,
        "onFailure": [
          {
             "log": {
                "source": "An error occurred in the if processor."
             }
          }
    }
    }

Conjunction Example: "or"

The following example shows how to use the or conjunction. The processor:

• Checks if the event category is equal to 2 or if the event severity is equal to 1.

• If either condition or both conditions are true, it runs the log processor in the then block to log a message.

• If neither condition is true, it checks the else block for processors and because there are none, continues processing.

{
    "if": {
       "conditions": {
          "or": [
             {
                "property": "$.event.EventCategory",
                "operator": "==",
                "value": 2
             },
             {
                "property": "$.event.Severity",
                "operator": "==",
                "value": 1
             }

          ]
       },
       "then": [
          {
             "log": {
                "source": "The event category is 2 or the severity is 1."
             }
          }
       ],
       "else": [
       ]
    }
}

Conjunction Example: "and"

The following example shows how to use the and conjunction. The processor:

• Checks if the event category is equal to 3 and if the event severity is equal to 1.

• If both conditions are true, it runs the log processor in the then block to log a message.

• If either condition is false, it checks the else block for processors and because there are none, continues processing.

{
    "if": {
       "conditions": {
          "and": [
             {
                "property": "$.event.EventCategory",
                "operator": "==",
                "value": 3
             },
             {
                "property": "$.event.Severity",
                "operator": "==",
                "value": 1
             }
          ]
       },
       "then": [
          {
             "log": {
                "source": "The event category is 3 and the event severity is 1."
             }
          }
       ],
       "else": [
       ]
    }
}

Conjunction Examples: "and" plus "or"

The following examples show how to use the and and or conjunctions together.

This example processor:

• Checks if the event category is 3 and the event count is 3. Because there is only one item in the or array, it must evaluate to true for an overall result of true.

• If both conditions are true, it runs the log processor in the then block to log a message.

• If either condition is false, it checks the else block for processors and because there are none, continues processing.

{
    "if": {
       "conditions": {
          "and": [
             {
                "property": "$.event.EventCategory",
                "operator": "==",
                "value": 3
             },
             {
                "or": [
                   {
                      "property": "$.event.Count",
                      "operator": "==",
                      "value": 3
                   }
                ]
             }

          ]
       },
       "then": [
          {
             "log": {
                "source": "The category 3 event occurred 3 times."
             }
          }
       ],
       "else": [
       ]
    }
}

This example processor:

• Checks if the event category is 3 and either the event count is 3 or the event severity is 3.

• If the and condition is true and one or both of the nested or conditions are true, it runs the log processor in the then block to log a message.

• If the and condition is true and both of the nested or conditions are false, it checks the else block for processors and, because there are none, continues processing.

• If the first condition is false, regardless of the results for the nested or conditions, it checks the else block for processors and, because there are none, continues processing.

{    
    "if": {
       "conditions": {
          "and": [
             {
                "property": "$.event.EventCategory",
                "operator": "==",
                "value": 3
             },
             {
                "or": [
                   {
                      "property": "$.event.Count",
                      "operator": "==",
                      "value": 3
                   }, 
                   {
                      "property": "$.event.Severity",
                      "operator": "==",
                      "value": 3
                   }
                ]
             }

          ]
       },
       "then": [
          {
             "log": {
                "source": "The category 3 event is either of severity 3 or occurred 3 times."
             }
          }
       ],
       "else": [
       ]
    }
}

This example processor:

• Checks if the event category is 5 or if there are more than 7 severity events with severity 1.

• If the or condition is true, regardless of the results for the nested and conditions, it runs the processors in the then block:

  • The first log processor logs a message.

  • The set processor sets a value in local memory.

  • The second log processor logs a message containing the value from local memory.

• If the or condition is false and both of the nested and conditions are true, it runs the processors in the then block.

• If the or condition is false and either of the nested and conditions is false, it checks the else block for processors and, because there are none, continues processing.

{
    "if": {
       "conditions": {
          "or": [
             {
                "property": "$.event.EventCategory",
                "operator": "==",
                "value": 5
             },
             {
                "and": [
                   {
                      "property": "$.event.Count",
                      "operator": ">",
                      "value": 7
                   },
                   {
                      "property": "$.event.Severity",
                      "operator": "==",
                      "value": 1
                   }
                ]
             }
          ]
       },
       "then": [
          {
             "log": {
                "source": "Either a severity 1 event occurred more than seven times, or it is a category 5 event."
             },
             "set": {
                "source": "$.event.Count"
                "targetField": "$.localmem.eventCount"
             },
             "log": {
                "source": "The event occurred %s times.",
                "args": [ "$.localmem.eventCount" ]
          }
       ],
       "else": [
       ]
    }
}

interpolate

This processor interpolates the text and variables contained in source with the values which exist in the message currently being processed. It uses the properties described in the following table.

The following example is used within a post processor. It interpolates the values of event.EventType and event.ExpireTime from the current message into the source string, then stores the string in the event.Summary field.

{
    "interpolate": {
        "source": "The $.event.EventType event expires in $.event.ExpireTime seconds",
        "targetField": "$.event.Summary"
    }
}

If the value of EventType is Unknown and the value of ExpireTime is 3600 in the current message, then the processor sets the Summary field to The Unknown event expires in 3600 seconds.

kv

This processor extracts data from event fields or messages and formats it as key-value pairs. Use key-value pairs to organize and group related information based on keys and their corresponding values.

The processor uses the properties described in the following table.

The processor works as follows:

1. Splits key-value pairs from each other according to the delimiter set in the fieldSplit property.

2. Splits keys from values according to the delimiter set in the valueSplit property and splits them.

3. Saves the resulting array in the field specified in targetField.

The following example splits key-value pairs delimited by the space character, and splits keys from values delimited by ::. It stores the separated fields in an array in the event.Summary field.

{
    {
    "kv" : {
       "source" : "ALARM_UC01::Communication-Fail ALARM_UC02::System-Fail",
       "fieldSplit": " ",
       "valueSplit": "::",
       "targetField" : "$.event.Summary"
       }
    }
}

The resulting value in the event.Summary field is:

{
    "Summary": {
        "ALARM_UC01": "Communication-Fail",
        "ALARM_UC02": "System-Fail"
    }
}

length

This processor calculates the length of the string contained in or referenced by source and stores it in the target field. It uses the properties described in the following table.

The following example calculates the length of the value of the trap.oid field and stores it in the localmem.oidlength field for use later in the override.

{
    "length": {
        "source": "$.trap.oid",
        "targetField": "$.localmem.oidlength"
    }
}

log

This processor outputs a log message to stdout. It uses the properties described in the following table.

The following example outputs an info-level log message of There are 100 devices in the device catalog.

{
    "log": {
        "source": "There are %d devices in the device catalog",
        "args": [ 100 ],
        "type": "info"
    }
}

lookup

This processor enables external querying against the Unified Assurance databases and API and, when the Coherence microservice is deployed, caching results in the Coherence cache. It uses the properties described in the following table.

Cache Properties

The cache object of the lookup processor lets you add a cache entry for the lookup's results. The entry is stored as a key-value pair in the format [<key>,<value>], where:

• <key> is constructed from the values of the object and keys properties.

  Only the object property is required. If you do not provide a value for keys, then <key> is set to the value of the object property. If you provide values for both, <key> is set by concatenating the keys array items, adding them to the object string, and separating them by a colon (:).

• <value> is constructed from the results of the lookup query.

The cache object uses the properties described in the following table.

Cache Entry Key Examples

For example, start with the following lookup processor. It creates the zoneValue variable with a value of 1 to use later in the lookup. Then it searches the Graph database for vertices where the zone ID is greater than the zoneValue variable, and stores the results in local memory in the localmem.gdbresults field.

{
    "lookup": {
       "source": "gdb",
       "properties": {
          "database": "graph",
          "variables": {
             "zoneValue": 1
          },
          "query": "MATCH(v) WHERE v.ZoneID > $zoneValue RETURN v;"
       }
       "targetField": "$.localmem.gdbresults"
    }
}

You can add the cache property to cache the results, including any of the following in the keys property:

• An empty array. For example:

   "cache": {
            "enabled": true,
            "object": "Vertex",
            "keys": []
         }
  

  The cache entry key is simply the value of the object property: Vertex. The result would be the same if you omitted the keys property entirely.

• A variable defined in the lookup. For example:

   "cache": {
            "enabled": true,
            "object": "Vertex",
            "keys": ["$zoneValue"]
         }
  

  The lookup builds the cache entry key by replacing the variable with its actual value and adding it to the value of the object property: Vertex:1

• A JSON path. For example:

   "cache": {
            "enabled": true,
            "object": "Vertex",
            "keys": [ "$.event.Node"]
         }
  

  If a value exists at the JSON path, the lookup builds the cache entry key by replacing the path with its actual value and adding it to the value of the object property. For example, if the value of event.Node is 1234, the cache entry key would be Vertex:1234.

  If no value exists, the lookup just uses the object name as the key: Vertex. If the JSON path is invalid, the FCOM processor stops processing the current event and moves on to the next one.

• A string. For example:

   "cache": {
            "enabled": true,
            "object": "Vertex",
            "keys": ["Device"]
         }
  

  The lookup builds the cache entry key by adding the string to the value of the object property: Vertex:Device.

  This is a simple example, but you can include other strings, such as a query used in a cache lookup, to make it easier to understand and find the lookup from the cache entry.

• A combination of key types. For example:

   "cache": {
            "enabled": true,
            "object": "Vertex",
            "keys": ["Device", "$zoneValue", "$.event.Node"]
         }
  

  The lookup builds the cache entry key by concatenating the string, the variable's actual value, and the value from the JSON path, then adding the result to the value of the object property: Vertex:Device:1:1234

Fallback Properties

You can use the fallback object in a lookup when source is set to cache. If the cache lookup cannot find any data, the fallback performs an alternative lookup in the Graph database, a MySQL database, or the Unified Assurance API and optionally caches the results.

The fallback property of the lookup processor uses the properties described in the following table.

The following example shows a fallback object that gets all fields for the first 10 events from the Event database:

"fallback": {
  "source": "db",
  "properties": {
    "database": "Event",
    "query": "SELECT * From Events LIMIT 10;"},
  "cache": {
    "enabled": "true",
    "object": "Event",
    "keys": [ "$.event.Node" ],
    "ttl": 1000
    }
  }

The lookup builds the cache entry key adding the value of event.Node to the value of the object property. For example, Event:1234.

Database Lookup Properties

When the source of the lookup processor is set to db, the properties object uses the properties described in the following table.

The following example returns 10 events from the Event database and stores them in local memory in the localmem.dbresults field. It also caches the results in a single entry, with a key in the format Event:<EventNode>, where <EventNode> is the value of the event.Node field. The ttl field specifies that the cache entry expires after 1000 milliseconds, overriding the default value set for the FCOM processor.

{
  "lookup": {
    "source": "db",
    "properties": {
      "database": "Event",
      "variables": {
        "v1": 10
      },
      "query": "SELECT * From Events LIMIT :v1;"
    },
    "cache": {
      "enabled": true,
      "object": "Event",
      "keys": [ "$.event.Node" ],
      "ttl": 1000
    },
    "targetField": "$.localmem.dbresults"
  }
}

Graph Database Lookup Properties

When the source of the lookup processor is set to gdb, the properties object uses the properties described in the following table.

The following example creates the zoneValue variable with a value of 1 to use later in the lookup. Then it searches the Graph database for vertices where the zone ID is greater than zoneValue, and stores the results in local memory in the localmem.gdbresults field. It also caches the results in a single entry, with a key in the format Vertex:<id>, where <id> is value of the event.Node field.

{
    "lookup": {
        "source": "gdb",
        "properties": {
            "database": "graph",
            "variables": {
                "zoneValue": 1
            },
            "query": "MATCH(v) WHERE v.ZoneID > $zoneValue RETURN v;"
        },
        "cache": {
            "enabled": true,
            "object": "Vertex",
            "keys": [ "$.event.Node" ]
        },
        "targetField": "$.localmem.gdbresults"
    }
}

API Lookup Properties

When the source of the lookup processor is set to api, the properties object uses the properties described in the following table.

The following example returns all devices in the first page of the device catalog and stores them in local memory in the localmem.apiresults field. It also caches the results in a single entry with a key in the format Device:1.

{
    "lookup": {
        "source": "api",
        "properties": {
            "variables": {
                "deviceID" : 1
            },
            "endpoint": "/api/device/devices?page=1&start=0"
        },
        "cache": {
            "enabled": true,
            "object": "Device",
            "keys": [ "$deviceID" ]
        },
        "targetField": "$.localmem.apiresults"
    }
}

Cache Lookup Properties

When the source of the lookup processor is set to cache, the properties object uses the properties described in the following table.

See Fallback Properties for information about using the fallback property to perform an alternative lookup if the cache lookup does not find any data.

The following example uses a CohQL query to get the values of DeviceName for the entry in the a1cache cache with DeviceID set to 1. If the query fails to return any data, it performs an alternative database lookup and caches the result, using a cache entry key with Device:1 as the key and the device name returned by the query as the value. In either case, it saves the results to local memory in the localmem.cacheresults field.

{
    "lookup": {
        "source": "cache",
        "properties": {
            "object": "Device",
            "module": "query",
            "query": "Select DeviceName from a1cache where DeviceID = 1;"
        },
        "fallback": {
            "source": "db",
            "properties": {
                "database": "Assure1",
                "variables" : {
                    "deviceID" : 1
                },
                "query": "SELECT DeviceName from Devices where DeviceID=:deviceID;"
            },
            "cache": {
                "enabled": true,
                "object": "Device",
                "keys": [ "$deviceID" ],
                "ttl": 360000
            }
        },
        "targetField": "$.localmem.cacheresults"
    }
}

You could use the following alternative query property in the previous example to get the DeviceName from the entry with the key of Device:1 in the a1cache cache:

"query": "Select DeviceName from a1cache where key() = 'Device:1';"

The following example shows how to use the object and keys properties to look up a cache entry by its key. It adds the keys value to the objects value to search for the entry with the key Device:1234. If the entry does not exist, it uses the same fallback as the previous example, but with a device ID of 1, which it adds to the cache with the appropriate key.

{
    "lookup": {
        "source": "cache",
        "properties": {
            "object": "Device",
            "keys": [ "1234" ]
            "module": "default"
        },
        "fallback": {
            "source": "db",
            "properties": {
                "database": "Assure1",
                "variables" : {
                     "deviceID" : 1
                },
                "query": "SELECT DeviceName from Devices where DeviceID=:deviceID;"
            },
            "cache": {
                "enabled": true,
                "object": "Device",
                "keys": [ "$deviceID" ],
                "ttl": 360000
            }
        },
        "targetField": "$.localmem.cacheresults"
    }
}

math

This processor runs a calculation on a source number and stores the result in the target field. It uses the properties described in the following table.

The following example multiples the number of events by two and stores the result in local memory in the localmem.CountTimesTwo field.

{
    "math": {
        "source": "$.event.Count",
        "value": 2,
        "operation": "*",
        "targetField": "$.localmem.CountTimesTwo"
    }
}

regex

This processor runs a regex pattern on the value of the source property. The results, and an indication of whether there was a match, are stored in the target field. The results are stored as a double dimensional array, and each array can contain multiple strings that match the pattern. The first element of each array is the entire matched substring and the following elements are the submatched strings within the regex pattern.

This processor uses the properties described in the following table.

The following example runs a regex pattern on a static string and stores it in the event.RegexLocation field.

{
    "regex": {
        "source": "IPAddress: 192.0.2.1 IPAddress: 192.0.2.2",
        "pattern": "(\\w+): (\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})",
        "targetField": "$.event.RegexLocation"
    }
}

This results in the following value for event.RegexLocation:

"RegexLocation": {
    "matched": true,
    "results": [["IPAddress: 192.0.2.1", "IPAddress", "192.0.2.1"], ["IPAddress: 192.0.2.2", "IPAddress", "192.0.2.2"]]
}

The value of event.RegexLocation.results.[1].[0] is "IPAddress: 192.0.2.2".

The following example runs a regex pattern that uses variables. The value of targetField is empty in order to capture the variable text from the regex pattern.

{
    "regex": {
        "source": "Events are cleared",
        "pattern": "Events are (?<text>.*$)",
        "targetField": ""
    }
}

The value of $text is cleared.

remove

This processor deletes the key and value at the JSON path in source. It uses the properties described in the following table.

The following example removes the key and value for the trap.timeTicks field:

{
    "remove": {
        "source": "$.trap.timeTicks"
    }
}

rename

This processor renames the field at the JSON path in source with the specified target. It uses the properties described in the following table.

The following example renames the Details field to DetailsOld.

{
    "rename": {
        "source": "$.event.Details",
        "targetField": "$.event.DetailsOld"
    }
}

replace

This processor applies the pattern to the source, replaces all matching instances, and stores the new result in the target field. To use a regex pattern, you must also set the regex field to true. If the source is an array, the processor matches and replaces against each value in the array.

This processor uses the properties described in the following table.

The following example replaces a test in the string This is a test with not a test. It stores the resulting string, This is not a test, in local memory in the localmem.example field.

{
    "replace": {
        "source": "This is a test",
        "pattern": "a test",
        "replacement": "not a test",
        "targetField": "$.localmem.example"
    }
}

set

This processor takes the source value, applies any specified variadic arguments, and stores the result in the specified target field. It uses the properties described in the following table.

The following example sets the value of the event.Details2 field to be the same as the value of the event.Details field.

{
    "set": {
        "source": "$.event.%s",
        "args": [ "Details" ],
        "targetField": "$.event.Details2"
    }
}

setOutputStream

This processor overrides the output stream that the message is sent to at the end of processing. This is applied individually for each message, and the original output stream is reset at the beginning of processing. The processor uses the properties described in the following table.

The following example sets the output stream for the message to the Event Sink Pulsar topic.

{
    "setOutputStream": {
        "output": "pulsar+ssl:///assure1/event/sink"
    }
}

sort

This processor sorts a source array lexicographically and stores the sorted result in a target field. It uses the properties described in the following table.

The following example sorts the trap.variables array and stores it in trap.sortedVariables:

{
    "sort": {
        "source": "$.trap.variables[0]",
        "targetField": "$.trap.sortedVariables"
    }
}

split

This processor splits a string by the specified delimiter and stores the result as an array in the target field. It uses the properties described in the following table.

The following example splits the string using , as the delimiter and stores the result in local memory in the localmem.splitarr field.

{
    "split": {
        "source": "1,2,3,4",
        "delimiter": ",",
        "targetField": "$.localmem.splitarr"
    }
}

The resulting value of localmem.splitarr is:

{
    "splitarr": ["1", "2", "3", "4"]
}

strcase

This processor applies a case type on the value of source and stores it in the target field. It uses the properties described in the following table.

This example applies lower case to the HELLO, WORLD string and stores the result in local memory in the localmem.lowercase field.

{
    "strcase": {
        "source": "HELLO, WORLD",
        "type": "lower",
        "targetField": "$.localmem.lowercase"
    }
}

The resulting value of localmem.lowercase is hello, world.

substr

This processor stores a substring of source in a target field. It uses the properties described in the following table.

This example gets the substring of the source Hello starting with the second letter and stores it in local memory in the localmem.substr field.

{
    "substr": {
        "source": "Hello",
        "start": 1,
        "targetField": "$.localmem.substr"
    }
}

The resulting value of localmem.substr is ello.

switch

This processor checks the source value against the case array using the operator value and runs processors against it. It uses the properties described in the following table.

Switch Case Array

The case property of the switch processor uses the properties described in the following table.

This example checks whether a value in local memory is not equal to 2 or is equal to 5, and discards it if so. If neither case is true, it uses the log processor to log a message.

 {
    "switch": {
        "source": "$.localmem.val1",
        "operator": "!=",
        "case": [
            {
                "match": 2,
                "then": [
                    {
                        "discard": {
                        }
                    }
                ]
            },
            {
                "match": 5,
                "operator": "==",
                "then": [
                    {
                        "discard": {
                        }
                    }
                ]
            }
        ],
        "default": [
            {
                "log": {
                    "type": "info",
                    "source": "Do nothing since none of the cases were met"
                }
            }
        ]
    }
}

trim

This processor trims a string of values, specified in the cutset, from the beginning and end of a string. It uses the properties described in the following table.

This example trims the string H from the string Hello, storing the string ello in local memory.

{
    "trim": {
        "source": "Hello",
        "cutset": "H",
        "targetField": "$.localmem.trim"
    }
}

FCOM Lookups

The FCOM Processor can read a lookup file and store it in memory for reference within an override. You can use this to create a set of constant values for an override. Lookup files use the properties described in the following table.

This example lookup file maps integer values to text values for alert types.

{
    "name": "alertTypeMap",
    "_type": "lookup",
    "lookup": {
        "1": "Fault",
        "2": "Outage",
        "3": "Overload",
        "4": "Reboot",
        "10": "Failover",
        "12": "Restore"
    }
}

This example shows how to refer to this lookup file in an FCOM override using a set processor. It maps the value of trap.variables[0].value based on the alertTypeMap lookup file and stores the result in trap.varMapping.

{
    "set": {
        "source": "$.lookups.alertTypeMap.%s",
        "args": [ "$.trap.variables[0].value" ],
        "targetField": "$.trap.varMapping"
    }
}

If the value of trap.variables[0].value is 10, then the processor sets trap.varMapping to Failover.

FCOM Grok Definitions

The FCOM Processor can load a set of custom grok patterns to use in overrides. You can see a list of vendor-defined commonly used patterns in the vendor _grok folder within the FCOM_FILES_LOCATION SVN path or default patterns in the default-grok.json file located in the following directory in the Rules UI:

Core Rules (core)/Default read-only branch (RO_LOCKED)/processing/event/fcom/_groks

Grok files use the properties described in the following table.

The following example applies the VALUE, COMMONMAC, and DATA patterns:

{
    "name": "Custom Grok Definition 1",
    "_type": "grok",
    "grok": {
        "VALUE": ".*",
        "COMMONMAC": "(?:(?:[A-Fa-f0-9]{2}:){5}[A-Fa-f0-9]{2})",
        "DATA": ".*?"
    }
}

The following example shows how to use a custom Grok pattern in an FCOM override using a grok processor:

{
    "grok": {
        "source": "$.syslog.datagram",
        "pattern": "%CISCO-LINK-5: The error message is: %{VALUE:message}",
        "targetField": "$.syslog.variables"
    }
}

The processor sets syslog.variables to an object containing a message field with a value of whatever string is after The error message is:.