Documentation

BATMN

BATMN is a tool used to send alerts to Shell Event Management (formerly OneBSM, currently Moogsoft AIOps Enterprise). It can be configured to automatically create a ServiceNow incident ticket, or trigger a notification in SNS, or both, or neither - user's choice. It is important to note that submitted values are not validated by BATMN. So make sure that configuration items, assignment groups or SNS distribution lists are correct!

Windows Launch

C:\Program Files (x86)\Shell\BATMN\BATMN.exe {options}

Linux Launch

perl /opt/shell/BATMN/batmn.pl {options}

BATMN Invocation Options

Option Code	Name	Mandatory	Notes
`-a {Class}`	Class	Yes	Moogsoft field: `class` Valid Options `SHELL_EV` (Preferred) Typical alert `SHELL_AP` Minimal alert with limited value, kept for backward compatibility with older deployments
`-n {Environment}`	Environment	Yes	Valid Options `test` (Shell Internal, Moogsoft QA) `pubdev` (External, Moogsoft QA) `prod` Default (Shell Internal, Moogsoft Production) `public` (External, Moogsoft Production) The `public` and `pubdev` options send to the same Moogsoft environments as `prod` and `test` respectively, but are designed for senders that are NOT on the Shell internal network (e.g. public cloud deployments).
`-m "Message Text"`	Description	Yes (SHELL_AP) No (SHELL_EV)	Moogsoft field: `description` Text will be used in the alert description. If not set, alert description will be cobbled up from other fields.
`-p`	Use Proxy	No	Only applies when using `test` or `prod` Sends message to the Moogsoft SaaS endpoint via Shell's corporate proxy server. If not specified, message is sent to a Shell internal endpoint.
`-h` or `-?`	Help	No	Show help message and exit without sending any event.
SHELL_AP Options
`-b "NotifyGroup={SNS Group1;...;SNS Groupn}"`	SNS Recipient	Yes	Moogsoft field: `custom_info.eventDetails.notify_group` Sends the alert to the designated SNS Group distribution lists (separated by ;). The SNS distribution lists are not validated.
SHELL_EV Options
`-r {Severity}`	Severity	No	Moogsoft field: `severity` If this option is not set, the resulting alert will have a severity level of Indeterminate in Moogsoft - we recommend explicitly setting this value Valid Options `normal` Can be used to mark a previous alert as resolved `warning` `minor` `major` `critical`
`-i`	Get Information	No	Invokes BATSIGNL after sending the alert and will return alert, situation and incident ticket information in the form of a JSON string. Important: While this is not enforced, it is essential that the `externalid` value be set in the BATMN request (as part of the `-b` values). This option will cause BATMN to wait for up to 2 minutes until BATSIGNL has completed its work
SHELL_EV -b Options Options must be specified in the form of Option1=Value1;Option2=Value2;
`Asset={Configuration Item}`	ServiceNow Configuration Item	No	Moogsoft field: `source_id` Used as part of the event signature The `Asset` option takes precedence over the `Element` option for populating the Moogsoft `source_id` field if both are specified on a request. An invalid Configuration Item will result in no ServiceNow incident ticket being created.
`Element={Configuration Item}`	ServiceNow Configuration Item	No	Moogsoft field: `source_id` Used as part of the event signature The `Asset` option takes precedence over the `Element` option for populating the Moogsoft `source_id` field if both are specified on a request. An invalid Configuration Item will result in no ServiceNow incident ticket being created.
`Assignment={ServiceNow Assignment Group}`	ServiceNow Assignment Group	No	Moogsoft field: `custom_info.eventDetails.assignment_group` Used as part of the event signature Required if a ServiceNow incident ticket is desired Will assign a ServiceNow incident ticket to the specified group. The Assignment Group specified is not validated, and if invalid may result in no incident ticket created.
`ExternalId={String}`	External ID Reference	No	Moogsoft field: `external_id` Used as a reference value known to the caller - particularly useful if one wants to keep track of alert information
`NotifyGroup={SNS Group1;...;SNSGroupn}`	SNS Distribution List	No	Moogsoft field: `custom_info.eventDetails.notify_group` Sends the alert to the designated SNS Group distribution lists (separated by ;). The SNS distribution lists are not validated.
`SourceRule={String}`	Event Source Rule	No	Moogsoft field: `custom_info.eventDetails.event_source_rule` Used as part of the event signature Used as part of the event description if no description is provided
`ElementState={String}`	Element State	No	Moogsoft field: `custom_info.eventDetails.ElementState` Used as part of the event description if no description is provided
`StateValue={String}`	State Value	No	Moogsoft field: `custom_info.eventDetails.StateValue` Used as part of the event description if no description is provided
`Priority={String}`	Priority	No	Moogsoft field: `custom_info.eventDetails.Priority`
`URL={String}`	URL	No	Moogsoft field: `custom_info.eventDetails.URL`
`OriginId={String}`	URL	No	Moogsoft field: `custom_info.eventDetails.OriginID`
`CF3={String}`	CF3	No	Moogsoft field: `custom_info.eventDetails.CF3`
`Cause={String}`	Cause	No	Moogsoft field: `custom_info.eventDetails.Cause`
`Description={String}`	Long Description	No	Moogsoft field: `custom_info.eventDetails.long_description` Long Description of the event, this will be stored in the Custom Info section of the Alert.
All others	Extra Info	No	Moogsoft field: `custom_info.eventDetails.extra_info` Any other parameter will end up being picked up and placed in the extra_info section of the Alert.

BATSIGNL

BATSIGNL is a tool used to find and update alerts in the Shell Event Management (formerly OneBSM, currently Moogsoft AIOps Enterprise). If an incident ticket is associated to a Moogsoft alert or situation, it can also be found and updated (via the Moogsoft situation to ServiceNow incident ticket synchronization API).

Windows Launch

C:\Program Files (x86)\Shell\BATMN\BATSIGNL.exe {options}

Linux Launch

perl /opt/shell/BATMN/batsignl.pl {options}

BATSIGNL Invocation Options

Option Code	Name	Mandatory	Notes
`-n {Environment}`	Environment	Yes	Valid Options `test` (Shell Internal, Moogsoft QA) `pubdev` (External, Moogsoft QA) `prod` Default (Shell Internal, Moogsoft Production) `public` (External, Moogsoft Production) The `public` and `pubdev` options send to the same Moogsoft environments as `prod` and `test` respectively, but are designed for senders that are NOT on the Shell internal network (e.g. public cloud deployments).
`-m {Mode}`	Mode	Yes	Valid Options `read` Search Data `update` Write a thread entry for the specified situation `register` Registers the device as a valid BATSIGNL user. This option should only be invoked by a user with sufficient rights to update configuration settings on the device being registered.
`-a {AlertID (numeric)}` `-s {SituationID (numeric)}` `-e {ExternalID}` `-i {IncidentTicket}`	Search Criteria	No	One can use multiple search criteria on the same read or update request if desired. The data returned is the combined result of each individual search.
`-t "Text Message"`	Message	No	Only applicable in update mode Will use the message specified in the collaboration thread entry
`-f {File Path}`	Add File Contents	No	Only applicable in update mode Will append the contents of the specified file to the collaboration thread entry
`-h` or `-?`	Help	No	Show help message and exit without doing any work.
`-x`	Resolving Step	No	Only applicable in update mode Will mark the collaboration thread entry as a resolving step in Moogsoft and will be noted as such for future similar situations. This will also mark the content of the thread entry as the incident ticket resolution in ServiceNow, if applicable.
`-w {Timeout}`	Timeout	No	Only applicable in read mode In read mode, BATSIGNL will wait until the search returns either an incident ticket or a reason why it wasn't. This limits how long BATSIGNL will keep checking, and will return whatever it has available once the timeout expires. Default value is 120 seconds
`-v`	Verbose	No	Returns detailed logging which could be useful for troubleshooting purposes. Please note that this option may interfere with the normal operation of tools/scripts that read the output of BATSIGNL.

BATSIGNL Returned Data

In read mode, BATSIGNL returns a JSON string which contains the following elements

Element	Data Type	Notes
`alert_info`	Array of integers	List of all alert IDs that are associated with the search criteria
`situation_info`	Array of integers	List of all Moogsoft situation IDs that are associated with the search criteria
`incident_info`	Array of strings	List of all ServiceNow Incident Tickets that are associated with the search criteria
`messages`	Array of strings	Usually at least one message describing if the access key was successfully verified. If multiple search criteria are used there will be messages related to this.
`query_field` `query_op` `query_value`	String	Contains the first processed search criterion. If multiple criteria are submitted, the others will be listed in the `messages` area.
`incident_errors`	Array of Objects	This contains the list of alerts which did not qualify to create a ServiceNow ticket. Each entry is an object with the following fields: `alert_id` (integer) `reason` (string) - the reason why the alert didn't qualify for a ServiceNow ticket `ci` (string) - the CI associated to the alert

BATMN Examples

Here are some typical use cases for BATMN:

Trigger an alert which will generate a ServiceNow ticket for Server, waits for the incident ticket to be created. Note that BATMN automatically generates an external ID value which allows its retrieval by BATSIGNL.

perl batmn.pl -n test -a SHELL_EV -b "Element=amsdc1-s-#####.europe.shell.com;Assignment=MyTeamAssignment" -r MAJOR -i

{"messages":["Registration Checked Successfully"],"alert_info":["960508"],"incident_errors":[],"incident_info":["INC0124381"],"query_field":"external_id","query_value":"1894319-gmorepo1.sga-res.com:1625177031","query_op":"=","situation_info":["286332"]}

If one wants to inquire about a potential ServiceNow incident ticket without using the -i option in BATMN, it is recommended to set the ExternalID -b option field with a known unique value

perl batmn.pl -n test -a SHELL_EV -b "externalid=THISISASPECIALTestIdJustForYou;Asset=Shell Availability Engine UAT" -r MAJOR

perl batsignl.pl -n test -m read -e "THISISASPECIALTestIdJustForYou"

{"messages":["Registration Checked Successfully"],"alert_info":["960505"],"incident_errors":[{"ci":"Shell Availability Engine UAT","reason":"Sev[3] Cls[SHELL_EV] Mgr[BATMN] Src[] AG[]","alert_id":960505}],"incident_info":[],"query_field":"external_id","query_value":"THISISASPECIALTestIdJustForYou","query_op":"=","situation_info":["286330"]}

BATMN will return JSON containing the alert, situation and incident ticket information. See the documentation for BATSIGNL for more details.