Logging
With the New-SMEXCOEvent function introduced in v3.x of the connector, you can get detailed logging events on several aspects of the connector. In addition, you can also introduce your own logging wherever you want in the connector, define it's event criteria, and then choose via the Settings UI how detailed you want to log (if at all).
You can optionally choose to introduce your own logging simply by calling the New-SMEXCOEvent function wherever you'd like in the connector
New-SMEXCOEvent -Source "New-WorkItem" -EventId 4128 -LogMessage "my custom message goes here" -Severity "Information"To use the function, you must declare:
- Source. This should be the name of a function you are in that is going to trigger a new event. In the above example, the call was made within the New-WorkItem function hence its source
- Event ID. This technically does not have to be unique, but by picking a unique value that doesn't overlap with an out of box value you can quickly find your own custom event through UI filter, PowerShell, or Operations Manager (SCOM)
- Log Message. This is the message to write to the Windows Event Log. It can be whatever you want and accepts variables given your current context in the connector.
- Severity. This must be set to "Information", "Warning," or "Error"
- 0 - Off. No logging is performed
- 1 - Information
- how many messages there are to process in the current loop
- new users need to be created for the new work item
- when meetings are processed against work items
- when Regex patterns are matched to override default work item type creation (i.e. create an IR instead of a default SR)
- 2 - Information + Warnings
- If File Attachments or Work Items can't be found through Verify-WorkItem
- 3 - Information + Warnings + Error
- Logs if there are issues connecting to Exchange
- 4 - Verbose (detailed logging in addition to Information + Warnings + Error)
- Show when work items are created/updated
- Shows the [action] to be taken during Updates or the Comments left
- shows when emails are sent from the workflow account (i.e. suggestion KA or RO)
- Shows Azure events as they pertain to use of Cognitive Services or Machine Learning
Note: By default the Windows Event Log keeps 1mb of data per log. That means at most the SMLets Exchange Connector log will only ever total 1mb. If you wish to change this behavior, right click on the "SMLets Exchange Connector" Event Log in Event Viewer on your SCSM Workflow Server, select Properties, and then adjust as you so choose.
Certain events not showing up? Make sure you're up to date with the latest version of the connector!
These logs exist out of the box with the SMLets Exchange Connector and will appear based on your defined logging level above. When using running the connector via the SCSM Workflow Engine and using the Windows Event Log, a new event log called "SMLets Exchange Connector" will be created that details all of the following events. If exceptions occur that have not been outlined below they will appear in the "Operations Manager" event log.
These events define connectivity to Exchange and processing information about the current run of the connector
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Successfully connected to Exchange |
| 1 | Error | 3 | (this message is dynamic based on the error thrown by Exchange e.g. failed to authenticate, failed to impersonate, etc.) |
| 2 | Information | 1 | Messages to Process: (total messages to process) |
| 3 | Information | 1 | Processed: (message count processed so far) |
| 4 | Error | 3 | The address/SCSM Run As Account used to sign into 365 is not a valid email address and is currently entered as USERNAME + "@" + DOMAIN. This will prevent a successful connection. To fix this, go to the Run As account in SCSM and for the username enter it as an email address like user@domain.tld |
| 5 | Information | 1 | Filtering Mailbox on: (the messages types being searched for in the inbox) |
| 6 | Information | 1 | Processed x messages in Minutes, Seconds, Milliseconds |
| 7 | Information | 4 | Successfully retrieved an OAuth token from 365 |
| 8 | Error | 3 | Could not retrieve OAuth token from 365: (full error message from M365) |
These events appear if you are leveraging the CustomEvents script to perform additional functionality not provided out of the box by the SMLets Exchange Connector. These are the only two events that exist for logging this functionality. You are free to create any additional logging for your own CustomEvents by virtue of this starting at Event ID 2 and up
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Custom Events PowerShell loaded successfully |
| 1 | Warning | 2 | (dynamic based on the error raised by PowerShell e.g. file could not be found, file format is not in a correct format, etc) |
These events appear if you are are processing digitally signed and/or encrypted messages
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Email certificate loaded |
| 1 | Error | 3 | (dynamic based on the error raised by PowerShell e.g. cert could not be found) |
| 2 | Information | 4 | Digital signature is valid |
| 3 | Warning | 2 | Digital signature could not be verified |
| 4 | Error | 3 | (dynamic based on the error raised by PowerShell e.g. the email could not be decrypted) |
These events appear if you are using Custom Rules (v4+)
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 1 | No out of box Work Item match found. Attempting to reconcile against custom defined matching patterns. |
| 1 | Information | 1 | Evaluating Work Item Patterns. |
| 2 | Information | 1 | Building Email Subject Switch Pattern: (SWITCH STATEMENT) |
| 3 | Information | 1 | Building Email Body Switch Pattern: (SWITCH STATEMENT) |
| 4 | Information | 1 | Email Subject Patten Search will either return true or the matched pattern: (RESULT) |
| 5 | Error | 3 | Email Subject Switch Pattern failed. Examine Event ID 2. |
| 6 | Information | 1 | Email Body Patten Search will either return true or the matched pattern: (RESULT) |
| 7 | Error | 3 | Email Subject Switch Pattern failed. Examine Event ID 3. |
| 8 | Information | 1 | The pattern matched a Custom Rule, but nothing was updated. Create a New Work Item of type (Custom Rule Type). Write (MATCHED PATTERN) into it's (CLASS PROPERTY) property so subsequent updates can be performed against it. |
| 9 | Information | 1 | Evaluating Patterns for a custom defined Work/Config Item type. |
| 10 | Information | 4 | A Pattern was matched for the Subject, but Custom Events are not being used. A Default Work Item will be created. |
| 11 | Information | 4 | A Pattern was matched for the Body, but Custom Events are not being used. A Default Work Item will be created. |
| 12 | Information | 1 | No Work Item or Config Item was created or updated through Custom Rules. Create a Default Work Item. |
These events appear if you are using multi-mailbox functionality
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Mailbox redirection is being used. Attempting to identify Template to use. |
| 1 | Information | 1 | To: (all To Recipients) |
| 2 | Information | 1 | Recipient Address: (loops through each To recipient) |
| 3 | Information | 1 | Redirection from known mailbox: (To/MultiMailbox match). Using custom templates. |
| 4 | Information | 1 | Redirection from known mailbox: (CC/MultiMailbox match). Found in CC field. Using custom templates. |
| 5 | Warning | 2 | No redirection from known mailbox. Using Default templates" |
These events define when an email without a [Work Item] in the subject will create a brand new Work Item
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Creating (workitem type) From: (the sender) CC Users: (email addresses on cc) Title: (email subject) |
| 1 | Information | 4 | User Relationships for (email subject) Affected user: (AffectedUser DisplayName) Related Users (Related Users Display Name comma seperated) |
| 2 | Information | 4 | Created ID: (workitem id) Title: (work item title) Affected User: (affected user displayname) Related Users: (related users display names) |
| 3 | Warning | 2 | The Created By User for (workitem id) could not be set. |
| 4 | Warning | 2 | The Affected User for (workitem id) could not be set. |
These events define updates to Work Items that currently exist in Service Manager
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 1 | Information | 4 | (keyword action vs. comment) |
| 2 | Information | 4 | Voting on (Review Activity ID) SCSM User: (voting user) Vote: (approve, reject, or keyword not matched) |
| 3 | Warning | 2 | (Work Item ID) could not be Resolved By (User Display Name). |
| 4 | Warning | 2 | (Work Item ID) could not be taken by- (User Display Name). |
| 5 | Warning | 2 | (User Display Name) could not be related to (Work Item ID). |
| 6 | Warning | 2 | Attempting to change (Work Item ID) to a Status of (Status) due to Affected User Reply could not be performed. (dynamic based on the error). |
| 7 | Warning | 2 | The Affected User of (Work Item ID) could not be found. |
| 8 | Warning | 2 | The Assigned user of (Work Item ID) could not be found. |
| 9 | Warning | 2 | (Work Item ID) could not be related to (Other Work Item ID). |
| 10 | Error | 3 | Self-Assignment for (Work Item ID) via the [take] keyword(s) failed for (User Display Name) |
| 11 | Error | 3 | AD User (User Display Name) could not vote on behalf of AD Group (Group UserName). They are either not a member of the AD group or their Comment did not contain a valid keyword. Their comment was: (Comment) |
| 12 | Error | 3 | Voting on Behalf of AD Groups is currently set to (true/false). SCSM User: User Display/User Name: (User Display Name) / (Username). Vote: (Comment) |
| 13 | Error | 3 | (Sender Email)/(Comment Left by Display Name) could not be matched to a corresponding Reviewer on (RA Work Item ID). Either they are not a Reviewer or their User object in SCSM does not have a valid and related SMTP Notification Channel. |
When working with Activities, this function is called to determine the Parent most Work Item
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | [PROCESS] Retrieving WI with GUID" |
| 1 | Information | 4 | [PROCESS] Activity: $($ActivityObject.Name) |
| 2 | Information | 4 | [PROCESS] Retrieving WI Parent |
| 3 | Information | 4 | [PROCESS] Activity: $( |
| 4 | Information | 4 | [PROCESS] This is the top level parent |
| 5 | Information | 4 | [PROCESS] Not the top level parent. Running against this object |
These events occur when a lookup is performed against an email address to a user in SCSM. They occur when creating and updating Work Items in Service Manager.
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Address: (email address) was matched to SCSM User: (domain\username) |
| 1 | Warning | 2 | Address: (email address) could not be matched to a user in SCSM |
This event occurs if you have opted to attach email to work items
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Warning | 2 | Email from (sender) on (workitemId) was not attached. Current Attachment Count: (currentCount)/(maxAttachments). File Size/Allowed Size: (currentFileSize)/(allowedFileSize) |
| 1 | Warning | 2 | Email from (sender) on (workitemId) could not be attached. (dynamic based on the error) |
This event occurs when File Attachments are added from an email
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Warning | 2 | A File Attachment from (sender) could not be added to (Work Item ID). (dynamic based on the error)" |
These events only occur if you have opted to create new users when the email address can't be matched to a user in SCSM
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | New User created in SCSM. Username: (username) |
| 1 | Information | 4 | New User: (username) successfully related to their new Notification: (email address) |
These events occur if you are sending Suggestions for Knowledge Articles or Request Offerings for the Cireson Portal. They will also occur should you choose to leverage this function through Custom Events
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Email sent from Workflow account Subject: (email subject) Body: (email body) |
These events occur if you are processing Outlook Meetings/Calendar Appointments
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 1 | Meeting scheduled for (work item id). Scheduled Start/End Times have been set. |
| 1 | Information | 1 | Meeting cancelled for (work item id). Scheduled Start/End Times have been cleared. |
These events occur if you have enabled the Merge Replies functionality
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 1 | Information | 4 | File Attachment: (file name) found |
| 2 | Information | 4 | File Attachment: (file name) has related work item (work item id) |
| 3 | Warning | 2 | A File Attachment was found to merge this email with a known Work Item. But the Work Item could not be found. |
| 4 | Warning | 2 | A File Attachment was not found to merge this email with a known Work Item |
This event typically occurs if you are performing Dynamic Analyst Assignment
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Get AD Group Associated with enum: (SCSM Tier Enum Id) |
| 1 | Information | 4 | Get SCSM object/Group for: (SCSM Group Id) |
| 2 | Information | 4 | AD Group Name: (AD Group Name) |
| 3 | Information | 4 | AD Group Members: (AD Group Members Display Name) |
| 4 | Warning | 2 | (dynamic based on the error) |
This event typically occurs if are reserving [take] functionality to only members of the Work Item's currently assigned group
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Warning | 2 | (dynamic based on the error) |
This event occurs when using Dynamic Analyst Assignment and performing assignment based on which Analyst in the Group has the lowest volume of active Work Items
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | (User's Display Name) : (AssignedCount) |
This event occurs when using Dynamic Analyst Assignment
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 1 | Using Dynamic Analyst Assignment: (Random, OOORandom, Volume, OOOVolume) |
| 1 | Error | 3 | (dynamic assignment type) is not supported. No user will be assigned to (Work Item ID). Please use the Settings UI to properly set this value." |
| 2 | Information | 4 | Assigned (Work Item ID) to (Domain\Username) |
| 3 | Warning | 4 | The Assigned To User could not be set on (Work Item ID) Using Template: (Template Display Name). This Template either does not have a Support Group defined that corresponds to a mapped Cireson Portal Group Mapping OR the Template being used/was copied from an OOB SCSM Template |
These events occur if you are using Azure Cognitive Services to detect the perceived attitude (sentiment) of the email to dynamically drive the creation of an Incident or Service Request. A lower score leans towards negative sentiment (Incident), while a higher score leans toward positive sentiment (Service Request)
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Azure Sentiment Score: (percent score) |
| 1 | Error | 3 | (dynamic based on the error) |
These events occur if you are using keyword matching to create an Incident or Service Request based on words found in the email
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 1 | Override keywords found in email. Will create: (work item type IR/SR) instead of: (default work item type IR/SR) |
These events occur if you have used trained AML with your Data Warehouse so AML can 'think' and decide if an email should create an Incident/Service Request, the Support Group, the Classification, and the Impacted Configuration Items
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | (All predictions are written into the log event) |
| 1 | Error | 3 | (dynamic based on the error e.g. the AML Web Service could not be contacted, etc.) |
| 2 | Error | 3 | work item type (string, IR/SR) prediction not written |
| 3 | Error | 3 | work item type (decimal, %) confidence score not written |
| 4 | Error | 3 | work item classificiation (enum) score not written |
| 5 | Error | 3 | work item support group (decimal, %) confidence not written |
| 6 | Error | 3 | work item support group (enum) prediction not written |
| 7 | Error | 3 | work item classification (enum) not written |
| 8 | Error | 3 | support group not set |
| 9 | Error | 3 | classification not set |
| 10 | Error | 3 | impacted configuration item not related to work item |
These events occur if you are performing language translation with Azure Speech Services.
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Source Language (2 letter language code) Target Language: (2 letter language code) Text to Translate: (emailBody) Translated Text: (translated emailBody) |
| 1 | Error | 3 | (dynamic based on the error) |
These events occur if you are performing language translation with Azure Speech Services.
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | (the email's identified 2 letter language code) |
| 1 | Information | 4 | (dynamic based on the error) |
These events occur if you are using ACS to identify keywords in an email to either simplify Knowledge Base or Request Offering Suggestion Emails.
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | Keywords identified from Azure: (keywords) |
| 1 | Error | 3 | (dynamic based on the error) |
These events occur if you are using ACS to describe an image (tags) or extract text from an image (optical character recognition/OCR).
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | (extracted text) |
| 1 | Error | 3 | (dynamic based on the error) |
These events occur if you are converting wav/ogg files from audio to text using Azure Speech Services.
| Event ID | Severity | Logging Level | Message (variables) |
|---|---|---|---|
| 0 | Information | 4 | (extracted text) |
| 1 | Error | 3 | (dynamic based on the error) |