AIOps 2.4.2-3 - Key Updates

Import Alert Enrichment

URL

https://smartops-dev03.eastus.cloudapp.azure.com/paas/itops/alertmapping/api/importAlertEnrichment

Method

POST

Headers

USER, Organization-key, Authorization, organization-name

Authorization should be the Bearer token for an itopsadmin user, Offline token will be invalid. Expected format : Bearer <token of logged in itopsadmin>
USER field should match the preferredusername field within the Authorization token

Body

Type – form-data

KEY	Description
file	Excel file containing alert enrichment data
project_id	The project for which this enrichment applies
file_name	Unique name for the attached file. This will be used in sequence_after field for sequential execution of the file
sequence_after	The order of processing the current file. A valid sequence_after indicates that the current file will be processed after the file in field. A blank value for this field indicates that this file should be executed first (it should not be executed after any specific file). Any existing file with blank sequence will automatically be executed after the current file
enrichment_types	Types of enrichments to be performed on the file. It should be a json in the following format [{"enrichment_type": "", "enrichment_code": "", "enrichment_fields": ["",""], "lookup_fields": ["",""]}] Allowed values for the json enrichment_type : can be any of Field Lookup or Refined Field Lookup when alert just need to be enriched based on fields in the excel without any additional processing. For this selection, both the lookup and enrichment fields should be present in the excel and the column names should match the alert store with case sensitivity Refined when enrichment fields need to be derived based on additional rules. The excel should contain the lookup fields (matching alert store fields) and additional fields for processing the rules to derive enrichment field values For a file, there can be a maximum of one Field Lookup and one u lookup enrichment types are allowed enrichment_code : should be a unique value for each enrichment_type enrichment_fields : List of fields to be enriched by the process For enrichment_type = Field Lookup, this should only include the fields in attached excel – not including those in reserved field list For enrichment_type = Refined, this can include any of the fields in alert store not including those in reserved field list Reserved field list - "alertCreatedTime", "alertID", "alertMessage", "alertMessageFullText", "alertTime", "alertModifiedTime", "alertTimeParseError", "assignedGroup", "assignedGroupId", "assignedTo", "assignedToUserId", "correlated", "createdTime", "flapEndTime", "flapStartTime", "parentClusterId", "requestReceivedTime", "slaLastUpdated", "smartopsCorrelationKey", "surge", "sysId", "ticketBusinessDuration", "ticketBusinessTimeLeft", "ticketNumber", "ticketPriority", "ticketStatus", "ticketingPolicy", "cluster", "clusterInfo.*" Reserved field list can be managed in config.ini within alertmapping project Lookup_fields : List of fields from the incoming alerts that need to matched up for processing alert enrichment. These fields should be present in attached xls and they should match the name of the fields (with case sensitivity) in alert store

In case of additional enrichment data, the same url can be used for file updates per rules below:

The file_name, project_id and enrichment_type + enrichment_code should match that of existing enrichment
Uploading full excel file does not delete missing records in the current file. This url is only considered for updates/additional insert and not delete
The lookup and enrichment fields can be changed and will be considered as an update
Column addition/deletion in the attached xls file will not be considered as an update
For an existing data, an additional enrichment_type (Field Lookup or Refined if not used already) can be introduced and will be considered updates. Example scenario below

For an existing file named sample.xls with file_name=sample, project_id=10, enrichment_type=”Field Lookup” and enrichment_code=”sample-lookup”, uploading same file with the following parameters, will be considered as update: file_name=sample, project_id=10, enrichment_type=”Refined” and enrichment_code=”sample-refined”
Max Limits :

For enrichment_type = Refined, additional processing fields are allowed to a maximum of 5

No of files per project is set to a default max = 5 and number of entries within a file is set to a max limit of 500. Both of these settings can be configured via Alert Enrichment Metadata API
Excel file preparation:
1. Only .xls type allowed
2. Excel file should not have duplicate columns – columns with a <existing column in excel>.<number> is not allowed . Ex. If excel has nodeName column, another column with nodeName.1 is not allowed
3. Only Text, Boolean, Number fields are allowed in excel
4. Column Name rules should be as specified in the rules for enrichment_type above
5. If severity field is specified in the excel, it should follow the rules specified in reference tables
6. Custom fields should be specified in flattened format within the excel file and alert enrichment templates

Ex: The alert store field “customFields”: {“property1”: “abc”}, should be specified as customFields.property1 in excel file and templateRules

Get Alert Enrichment Details

URL

Method

POST

Headers

USER, Organization-key, Authorization, organization-name

Authorization should be the Bearer token for an itopsadmin user, Offline token will be invalid. Expected format : Bearer <token of logged in itopsadmin>
USER field should match the preferredusername field within the Authorization token

Body

Type – form-data

KEY	Description
project_id	The project for which this enrichment applies
file_name	Not a required parameter. This should match the file_name provided during import alert enrichment

If only project_id is specified, the API will retrieve all the alert enrichment mappings available for the project. The following will be the format

{

"statusCode": "200",

"statusMessage": [

{

"file_name": "",

"sequence_after": "",

"enrichment_types": [

{

"type": "<enrichment_type>",

"code": "<enrichment_code>",

"lookup_fields": ["", ""],

"enrichment_fields": ["", ""]

}

]

}

]

}

If file_name is specified, the API will return all the mapping information for the specified file_name under project_id. Sample response below

{

"statusCode": "200",

"statusMessage": [

[

{

"key": {

"<Lookup field name1>": "<Lookup field value1>",

"<Lookup field name2>": "<Lookup field value2>"

"value": {

"enrichment_data": {

"<enrichment field name1>": "<enrichment field value1>",

"<enrichment field name2>": "<enrichment field value2>" },

"processing_data": {

"<excel field not marked as lookup or enrichment field name>": "<value>"

}

]

}

Set Alert Enrichment Metadata

URL

https://<dns-name>/paas/itops/alertmapping/api/configureAlertEnrichmentMetadata

Method

POST

Headers

USER, Organization-key, Authorization, organization-name

Authorization should be the Bearer token for an itopsadmin user, Offline token will be invalid. Expected format : Bearer <token of logged in itopsadmin>
USER field should match the preferredusername field within the Authorization token

Body

Type – form-data

KEY	Description
project_id	The project for which this enrichment applies
max_config_allowed	Total number of enrichment files allowed for the project
max_mappings_per_file	Total number of rows allowed per file

The max_config_allowed cannot be updated to a value less than the number of enrichments available for the project. Similarly, the max_mappings_per_file cannot be less than the maximum rows on each of the existing files

Get Alert Enrichment Metadata

URL

https://<dns-name>/paas/itops/alertmapping/api/fetchAlertEnrichmentMetadata

Method

POST

Headers

USER, Organization-key, Authorization, organization-name

Authorization should be the Bearer token for an itopsadmin user, Offline token will be invalid. Expected format : Bearer <token of logged in itopsadmin>
USER field should match the preferredusername field within the Authorization token

Body

Type – form-data

KEY	Description
project_id	The project for which this enrichment applies

Below is the response format

{

"statusCode": "200",

"statusMessage": {

"project_id": "1098",

"max_config_allowed": 10,

"max_mappings_per_file": 500

}

‎

Delete Alert Enrichment

URL

https://<dns-name>/paas/itops/alertmapping/api/deleteAlertEnrichment

Method

POST

Headers

USER, Organization-key, Authorization, organization-name

Authorization should be the Bearer token for an itopsadmin user, Offline token will be invalid. Expected format : Bearer <token of logged in itopsadmin>
USER field should match the preferredusername field within the Authorization token

Body

Type – form-data

KEY	Description
project_id	The project for which this enrichment applies
file_name	Enrichment file that needs to be deleted
enrichment_code	Optional value, required for deleting a specific lookup_json (excel file row) from the file
lookup_json	Json format of the row data that needs to be deleted from the alert enrichment file

Delete API can be used in two ways – with or without enrichment_code and lookup_json

Without enrichment_code and lookup_json

All mapping data and the enrichment types are deleted along with the enrichment file. The sequence are adjusted such that the next file in sequence will be executed in place of the current file

Ex: If the current sequence is A ->B -> C (A, B, C are the file_names of the uploaded files), deleting B will result in following sequence A -> C
With enrichment_code and lookup_json

When the enrichment_code and lookup_json is specified only that file entry is removed. If this is the only entry on the file, then this operation will result in deletion of all enrichment types and the current file

Expected lookup_json format

{

"<field name1 as in excel>": "<value1 as in excel",

"<field name2 as in excel>": "<value2 as in excel",

}

Rules to be defined for Refined Alert Enrichment processing

The existing ticket template APIs can be used for Alert Enrichment processing with the scenario set as "scenario": "alertEnrichment"

Add Template	https://<dns-name>/paas/itops/alertmapping/api/ticketTemplate
Update Template	https://<dns-name>/paas/itops/alertmapping/api/updateTicketTemplate
Delete Template	https://<dns-name>/paas/itops/alertmapping/api/deleteTemplate

Templates will be processed for Refined alert enrichment only when it contains the field $lookup{<enrichment_code>, <comma separated lookup fields for the enrichment_code)

Sample template rule:

"templateRules" : {

"rules" : [

{

"field": "source",

"value": "icinga",

"operator": "="

{

"operator": "in",

"value": "$lookup{holidayCal, $alertMetric, $businessTimezone, $nodeName, $country, $site}",

"field": "$date{alertTime,'DD-MMM'}"

}

"logicalOperator": "and"

}

$lookup function

In this sample, the enrichment_code = holidayCal and the rest of the parameters $alertMetric, $businessTimezone, $nodeName, $country and $site are the lookup fields identified for the enrichment_code when the alert enrichment xls file was uploaded.

Note: All lookup fields should be specified as parameter to $lookup tag

$date function

The $date operator can be used to convert existing date object to a date string based on the pattern specified in the second parameter to this operator. The following date formats are supported

DAY_OF_WEEK--- converts date object in first parameter to the day of the week
‎MONTH_OF_YEAR, --- converts date object in first parameter to the month
‎DD,  --- to extract date of the month in integer format
‎DDD,   --- to extract abbreviated week day (three letters - Sun, Mon..)
‎MM  --- to extract month of the year in integer format
‎MMM  --- to extract abbreviated month of the year (three letter month

like Jan, Feb)
‎YY --- to extract 2 digit year

YYYY --- to extract 4 digit year

The $date and $lookup can work on other template scenarios as well and can also be used in other rule scenarios as below:

"templateRules" : {

"rules" : [

{

"field": "Saturday",

"value": "$date{alertTime, 'DAY_OF_WEEK'}",

"operator": "="

{

"operator": "in",

"value": "$lookup{holidayCal, $alertMetric, $businessTimezone, $nodeName, $country, $site}",

"field": "$date{alertTime,'DD-MMM'}"

}

"logicalOperator": "and"

For using a new $lookup for an enrichment code that does not exist already, the tables CodeMaster and CodeLookup need to be populated.‎

Complete Template API sample

{

"precedence": 1,

"active": true,

"templateRules" : {

"rules" : [

{

"field": "Saturday",

"value": "$date{alertTime, 'DAY_OF_WEEK'}",

"operator": "="

{

"operator": "in",

"value": "$lookup{holidayCal, $alertMetric, $businessTimezone, $nodeName, $country, $site}",

"field": "$date{alertTime,'DD-MMM'}"

}

"logicalOperator": "and"

"templateMapping" : [

{

"values" : [

{

"fieldValue" : "Cust Field1",

"fieldRules" : {}

}

"fieldName" : "customFields.Property1"

{

"values" : [

{

"fieldValue" : "minor",

"fieldRules" : {}

}

"fieldName" : "severity"

}

"scenario": "alertEnrichment",

"templateName": "holidayCal",

"projectId": 1090

}