Besides creating an incident for a single source event and bi-directionally keeping it in sync, Clip can attach a source event to an existent incident created for another event which results in a "N:1" association of multiple events to the same incident. Updates of any event then causes an update of the incident, and an update of the incident updates all associated events.

Attaching events to existing incidents

You might want to attach several events to a single incident if one problem causes (or has already caused) several other problems in different, but related areas or events are auto-closed by newer events but the same problem still persists. Use cases for this "attach" feature include

  • Aggregate related events: Instead of creating several incidents all related to e.g. disk space usage that need to be assigned and maintained, an existing, open incident for this topic will be updated and the new event attached to it as an additional worklog entry
  • "Flapping" events: a common scenario is e.g. that an event related to high CPU usage causes an incident, but the event can be closed automatically and a new event for the same problem can reoccur which will then create a second incident. The "attach" feature can be used to "collect" these events that show up one after the other.
  • Import of incidents: in addition to attaching an event to an incident created by CLIP, CLIP can also query BMC Remedy or ServiceNow to identify the incident to attach to and import it into CLIP if it has been created by a different source or manually.

Using attachment, it is possible to define a search qualification which is then used to locate an incident, to which the submitted event should be attached. Attachment is configured by means of one or more <attach/> elements which are evaluated in order of occurence and placed between a destination target's <incidentDescription/> and <createXXX/> tags in ClipConfig.xml. Each <attach/> element consists of two subelements:

  1. Subelement <conditions/>:
    The <conditions/> subelement contains a list of conditions that must ALL evaluate to "true" so that the <attach/> element is applied. The conditionlist checks new events whether they meet your criteria to group it together to the same incident as attachments. If the conditionlist does not evaluate to "true", CLIP continues with the next <attach/> or <suppress/> element and finally, if there is no match, applies the <create/> section
  2. Subelement <attachToSourceID/>, <attachToSourceKeyPattern/>, <attachToSourceKey/>, <attachToDestID/> or <attachTo/> ( Qualifier )
    To identify the incident to which the source event should be attached to, CLIP offers four options for a "Qualifier", which differ in the criteria to find the incident and whether the search should be performed in the CLIP DB or the destination target. Each option is described in a separate section below.

    The search for an incident to attach to can have exactly one, more than one or no incidents as a result:

       a) If exactly one incident has been found for attachment, it is updated according to the <updateXXX/> section in the destination target instead of creation of a new incident according to the <createXXX/> section. The <update/> section can be extended to include mappings for attached events by checking the CLIP state of the event for an "update" – an event that is attached has the state "NEW" instead of "MODIFIED".   b) If multiple incidents are found, the submitted event is attached to the first incident in the list. For queries in the CLIP DB, the first incident in the result list is the one with the most recent creation date.

       c) If no incident is found for attachment, either the evaluation of subsequent sections is continued to create or attach to an incident, or the evaluation fails, according to the setting "continueIfNotFound" described below.

The <attach/> element itself has the attributes

  • Description: this serves as a descriptive text that is used in CLIP status messages to identify the <attach/> section as more than one can be configured
  • "continueIfNotFound": in case the query according to the qualifier does not return any results, Clip continues to evaluate subsequent attach sections, or finally instead of attaching the new event, CLIP will perform a normal incident creation according to the definitions in the <createXXX/> tag ( continueIfNotFound ="true", default). If continueIfNotFound is set to "false", the incident creation completes as "failed".
  • "importIfNotFound" - only relevant for qualifying option <attachTo/>: in case the query in the destination target identifies an incident to attach to, but it was not created by CLIP, this attribute controls whether the incident is imported into CLIP (importIfNotFound="true", default), or the attachment operation results in status "failed".

To distinguish between the different use cases performed in the <update/> section of a destination targets incident, e.g. normal update of the event, closure of an event or attachment of a new event, the Clip variable "RL_STATUS" can be used : a new event which is attached to an existing incident can be identified by its Clip status ("RL_STATUS") which is "NEW" in case of attachment - the following excerpt shows a conditionlist that adds a worknote entry to an incident "Attaching new …" for the attachment scenario: 

Once CLIP has attached the event to an incident, it sets the CLIP state of the incident to „ATTACHED" which can be further used to update the event which has been attached by executing the <updateOMi> section:

As CLIP variables without modifier refer to attributes on the peer side, the variable \[RL_STATUS\] in the following <updateOMi/> section refer to the incident state which is "ATTACHED" in case of an attachment, the following excerpt shows how an annotation "Attached to Incident…." Can be added to an event once it has been attached to an incident:

Table Correlation / Attachment Options:



Clip

Ticket
Identification
Method

Lookup Method

Import

Create if not found

Description

<V6

Remote Query

Target System

X

X

Clip performs remote query in the target system to identify the ticket to attach event to ( Remedy, ServiceNow, Cherwell, Jira …)
Example: Clip can correlate events to tickets created by ServiceDesk

>= V6

Destination ID
(Ticket ID)

Lookup in local Clip DB

N/A

X

Incoming event has reference to Incident number to attach to ( e.g. in a „custom attribute" )

>= V6

Source ID
(Event ID)


N/A

X

Incoming event has reference to other event ID with a synchronized incident to attach to ( e.g. in a „custom attribute" )
Example: Clip can leverage MF OpsBridge „Track Event Ids" feature for related events

>= V6

Source Key-Pattern


N/A

X

Every event can store a key,for a new event, Clip searches for previous event with key matching a pattern
Example: Clip can leverage MF OpsBridge event „Key" and „Close Key Pattern"

by Source ID

To identify the incident to attach to by means of a source ID in the Clip DB, the subelement <attachToSourceID/> is used. When an event is transferred to Clip to create an incident, it can have an attribute set with a reference to another event ( the ID of the other event ) as an indication to attach it to the incident created for the other event referred to.


Configuration Example:

The example configuration above shows an <attach/> section with the qualification type <attachToSourceID/>. A source event which has the attribute "CA_ChangedStateOfEvent" set to the ID of another source event previously submitted and an active, associated incident is attached to that existing incident.
In this scenario, an initial "warning" event with ID 881f806e-e599-71e8-1b56-c39e81530000 is received about a filesystem usage problem and Clip creates an incident with the ID INC0010317 for it:

The initial event is then automatically closed by a second event:

The second ( „closing" ) event of severity "minor" indicates that a higher threshold for the same file system usage problem has been crossed and it has the custom attribute „ChangedStateOfEvent" set to the ID of the first event - this causes Clip to apply the <attach/> section and perform an update for Incident INC0010317:

The same mechanism is applied for subsequent events, e.g. a "major" event, and finally, a "normal" Reset-event – all events are associated with the same incident:

An event which has been closed by another event can be identified by its state="closed" and the attribute identifying the "closing" event being not empty ( the ID contains e.g. dashes, "-" ):

If MF OMi/OMi is used as the source target, a custom attribute can automatically be added to a new event automatically closing another event, and also to the closed event thereby referencing each other. To enable this feature, in OMi refer to:

  • Administration -> Setup and Maintenance -> Infrastructure Settings
  • Application: "Operations Management": "Change State of Related Events Settings"
  • Track Event IDs in Custom Attributes: if enabled, the event ID of the newly received event will be put into custom attribute 'StateChangedByEvent' for each updated existing event. The event IDs of all updated existing events will be put into custom attribute 'ChangedStateOfEvents' for the newly received event. Activate this setting to be able to find the following types of events using custom attributes:
    • Events closed or resolved by a more recent event.
    • Event responsible for closing the selected event.

Please note, that the custom attribute 'ChangedStateOfEvents' can contain a list of event ID's separated by a blank " " – Clip does support this and chooses the most recent, active incident created for all events in the list for attachment.

by Source Key Pattern

To identify the incident to attach to by means of a source key pattern in the Clip DB, the subelement <attachToSourceKeyPattern/> is used.
When Clip receives a new event, it can check by means of a search pattern in the Clip DB whether a similar event has been received previously with an active incident associated so the new event is attached to that. Attachment by search key pattern involves two configurations:

  • the source target must define a key for an event that is supposed to support attachment
  • the destination target has an <attach/> section defined with subelement <attachToSourceKeyPattern/>

Configuration Example:
For a source target of type "MF OMi/OMi", a Clip correlation key is set to the OMi event key by default, and for events of application "NFS" to "NFS::" concatenated with its event object:

In the destination target, two <attach/> elements assure that

  • all events of application "NFS" are collected within the same incident and
  • new events are attached if their "closeKeyPattern" match the key of a previously received event:

As an example, a first event creates an incident INC0010335 and sets the correlation key which is stored in the Clip DB:

The second events' „closeKeyPattern" matches the key of the first event, so it is attached to the same incident:

Clip uses "Source Key Patterns" which are Java regular expressions (regex) and applied to the keys to find a match. They can be anything from a simple character, a fixed string or a complex expression containing special characters describing the pattern. For a reference and constructs for regular expressions, please refer to the Java pattern definition.
MF OMi/OMi uses its own syntax for patterns in policy templates, i.e. to define "close key patterns" for smart event correlation. Please review the OMi Admin guide, part 6: Monitoring: "Pattern Matching in Policy Rules" for further information. To make Clip work flexible with the OMi patterns directly, Clip supports the following basic, but not all OMi patterns and converts them to Java regexp equivalents: <*>, <@>, <#> and <_>.
The key length is limited to 128 characters by default but can be adjusted by setting attribute keyLength in the database settings .

by Source Key

In some cases finding an attach candidate by a source key pattern is not wanted because the query string that is used to find attach candidates may contain special characters that are not escaped. In such cases the usage of the element <attachToSourceKey> instead of <attachToSourceKeyPattern> might be a better approach. In the case of an "attachToSourceKey" usage a simple string comparision is done in order to find the attach candidate. Special characters like a backslash or quotes are escaped in this case.

by Destination ID

To identify the incident to attach to by means of a destination ID in the Clip DB, the subelement <attachToDestID/> is used.
When an event is transferred to Clip, it can have an attribute set with a reference to an existing incident to attach it to.

Configuration Example:

The example configuration above shows an <attach/> section with the qualification type <attachToDestID/>. A source event which has the custom attribute "IncidentID" set to the ID of an existing incident is attached to this incident.

The first event creates incident INC0010336, and as the custom attribute "IncidentID" is set to INC0010336 in the second event it is attached to the same incident.

by Query in Destination target

To identify the incident to attach to by means of a query in the destination target, the subelement <attachTo/> is used. Using this option, e.g. the ServiceNow, BMC Remedy or other supported destination targets are queried for incidents that match a qualification criteria.
The content of the <attachTo/> element specifies the qualification criteria for this search and depends on the target type. The query should return exactly one or no result incident, but can theoretically return more than one result incidents. In case there are more than one result incidents, the first one will be used for the attachment - if no incident is found, the attributes of the <attach/> element control the flow of operation.
For example qualifiers of your target type, please refer to the ClipConfig_New.xml for examples and hints on how to build the qualifiers.
Here is an example <attach/> section with a qualifier for a ServiceNow target:

Here is an example <attach/> section with a qualifier for a BMC Remedy target:

As CLIP variables without modifier refer to attributes on the peer side, the variable [RL_STATUS] in the following <updateSN/> and <updateARS/> sections refer to the event state which is "NEW" in case of an attachment:
Here is an example <updateSN/> section for a ServiceNow target:

Here is an example <updateARS/> section for a BMC Remedy target:

Please see the ClipConfig.xml file for examples for attachments.