Cireson Partners, Customers and Community members share your customizations and examples here to help benefit the community as a whole to earn Kudos and badges.
DISCLAIMER
All files and projects located here are provided and come "as-is" and without any warranty or support. Use at your own risk. Your use of Community Uploads is subject to our Terms of Use.
Cireson does not and will not support or maintain these enhancements, extensions, and scripts.
For Team Cireson uploads click here.
An SMlets based Exchange Connector
Adam_Dzyacky
Product Owner Contributor Monkey ✭✭✭✭✭
Call me crazy, but the idea of replacing the stock Exchange Connector with one written entirely in PowerShell leveraging the community built SMlets and adding some Cireson based functionality seems like a worthwhile endeavor. And with that said -
I cannot preface the following enough:
If this proves of benefit, you find a bug, see something that could be written cleaner/better, by all means please comment and/or re-share! As such, all 60kb of this has been published onto GitHub. I hope this provides a framework for you to innovate further on within your respective organizational processes.
The fun stuff - things this does, that the stock connector doesn't:
Minimum File Attachment Size
You can set a minimum size in KB. In doing so, files less than the defined size will not be added to the work item (i.e. corporate signature graphics won't be added)
File Attachment "Added by"
When an email is sent with attachments, the "File Attachment Added By User" relationship will be set based on the Sender if the user is found in the CMDB
Incident, Service Request, Change Request, Problem
[Take] - When emailing your workflow account, it will assign the Incident, Service Request, Change Request, or Problem to you (from address) when this keyword is featured in the body of the email.
Incident, Problem
[Reactivate] - When submitted to a Resolved Incident, it will be reactivated. When submitted to a Closed Incident, a New Incident will be created and the two related to one another.
Change Request
[Hold] - Place the Change Request On-Hold when this keyword is featured in the body of the email
[Cancel] - Cancel the Change Request when this keyword is featured in the body of the email
Manual Activity
[Skipped] - Skip the activity when this keyword is featured in the body of the email
Misc - Anyone who is not the implementer will have their email appended to the "Notes" area of the MA
If the Implementer leaves a comment that is not [Skipped] or [Completed] the comment is added to the highest level Parent Work Item
Review Activity
Any reviewer who leaves a comment that doesn't contain [Approved] or [Rejected] will have their comment added to the highest level Parent Work Item. This addresses a scenario where users not familiar with SCSM (i.e. departments outside of IT) respond back to the email thinking someone is reading the message on your workflow account. Now their comments aren't simply lost, but instead given the visibility they deserve!
Incident and Service Request
#private - When the message is attached to the action log, it will be marked as private if #private is featured in the body of the message.
Assigned To/Affected User relationships on the Action Log
When someone who isn't the Assigned To/Affected User leaves a comment on the Action Log the comment's "IsPrivate" flag is marked as null (this is a bug in the EC that has yet to be addressed by Microsoft). As such Cireson's Action Log Notify has no qualifier to go of off. With this script, the same functionality is present but now can be altered to get in line with SCSM and Cireson's MP. You can read more about this bug here from @Joe_Burrows and/or @chris_keander here.
Search HTML Knowledge Base
If enabled, your respective Cireson Portal HTML KB will be searched when a New Work item is generated using its title and description. The Sender will be sent a summarized HTML email with links directly to those knowledge articles about their recently created Work Item using the Exchange EWS API defined therein. As an example email, I've included an email body that features a [Resolved] and [Cancelled] link should the Affected User wish to mark their Incident/Service Request accordingly in the event the KB addresses their request. It should be noted, this is using the Cireson Web API to get KB through a now deprecated function. While this works, it goes without saying if Cireson drops this in coming versions it would cease to work. It has been tested and confirmed working with v7.x
What's next (besides maybe another version):
Schedule Work Items - When sending a calendar appointment to your workflow account about a Work Item, Scheduled Start/End times will be set accordingly and Affected User/Assigned To will be sent respective meeting invitations. That'd be cool. Right? Maybe? No?
Cireson Asset Management - It feels like there are a ridiculous amount of possibilities around updating Purchase Orders, Vendors, Licenses, etc.
Help - The idea of emailing the connector [help] to retrieve Knowledge Articles based on the email body seems like an interesting way to interact with SCSM. Not sure how useful this actually is.
Status - The idea of emailing the connector something along the lines of [status] or [health] to get the current Status of a SCSM Work Item, Health of a SCOM Distributed Application, etc. seems like an interesting way to interact with System Center at large and would only continue to make SCSM the central hub of the System Center suite. What's more, would introduce some bot like/Cortana-esque capabilities
Logging - Leverage the current Exchange Connector's registry key to introduce various levels of Windows Event Log logging, but make the descriptions far more decipherable and parametrized for future PowerShell based searches in the event deep troubleshooting is required
Finally - I have to mention @Leigh_Kilday, @Martin_Blomgren, @Tom_Hendricks, and @Brian_Wiestfor your contributions and reviews in helping create this early working version in your respective free time. You have my thanks gentlemen. And of course the developers at Cireson as portions of this simply just aren't possibly without your very awesome work.
I cannot preface the following enough:
- This is has only been tested in a development capacity. Know what you're getting into by trying this!
- This has only been tested against an on-premise Exchange server, but I honestly can't imagine how 365 is all that different given...
- This is using the identical Web Services API as required by the stock Exchange Connector (EWS API 1.2)
- It would probably make a great deal of sense to SMA/Azure runbook this and then inline script against your Workflow server
- I believe I have reproduced all functionality of the connector (v3.1), but it is entirely possible I've overlooked something
If this proves of benefit, you find a bug, see something that could be written cleaner/better, by all means please comment and/or re-share! As such, all 60kb of this has been published onto GitHub. I hope this provides a framework for you to innovate further on within your respective organizational processes.
The fun stuff - things this does, that the stock connector doesn't:
Minimum File Attachment Size
You can set a minimum size in KB. In doing so, files less than the defined size will not be added to the work item (i.e. corporate signature graphics won't be added)
File Attachment "Added by"
When an email is sent with attachments, the "File Attachment Added By User" relationship will be set based on the Sender if the user is found in the CMDB
Incident, Service Request, Change Request, Problem
[Take] - When emailing your workflow account, it will assign the Incident, Service Request, Change Request, or Problem to you (from address) when this keyword is featured in the body of the email.
Incident, Problem
[Reactivate] - When submitted to a Resolved Incident, it will be reactivated. When submitted to a Closed Incident, a New Incident will be created and the two related to one another.
Change Request
[Hold] - Place the Change Request On-Hold when this keyword is featured in the body of the email
[Cancel] - Cancel the Change Request when this keyword is featured in the body of the email
Manual Activity
[Skipped] - Skip the activity when this keyword is featured in the body of the email
Misc - Anyone who is not the implementer will have their email appended to the "Notes" area of the MA
If the Implementer leaves a comment that is not [Skipped] or [Completed] the comment is added to the highest level Parent Work Item
Review Activity
Any reviewer who leaves a comment that doesn't contain [Approved] or [Rejected] will have their comment added to the highest level Parent Work Item. This addresses a scenario where users not familiar with SCSM (i.e. departments outside of IT) respond back to the email thinking someone is reading the message on your workflow account. Now their comments aren't simply lost, but instead given the visibility they deserve!
Incident and Service Request
#private - When the message is attached to the action log, it will be marked as private if #private is featured in the body of the message.
Assigned To/Affected User relationships on the Action Log
When someone who isn't the Assigned To/Affected User leaves a comment on the Action Log the comment's "IsPrivate" flag is marked as null (this is a bug in the EC that has yet to be addressed by Microsoft). As such Cireson's Action Log Notify has no qualifier to go of off. With this script, the same functionality is present but now can be altered to get in line with SCSM and Cireson's MP. You can read more about this bug here from @Joe_Burrows and/or @chris_keander here.
Search HTML Knowledge Base
If enabled, your respective Cireson Portal HTML KB will be searched when a New Work item is generated using its title and description. The Sender will be sent a summarized HTML email with links directly to those knowledge articles about their recently created Work Item using the Exchange EWS API defined therein. As an example email, I've included an email body that features a [Resolved] and [Cancelled] link should the Affected User wish to mark their Incident/Service Request accordingly in the event the KB addresses their request. It should be noted, this is using the Cireson Web API to get KB through a now deprecated function. While this works, it goes without saying if Cireson drops this in coming versions it would cease to work. It has been tested and confirmed working with v7.x
What's next (besides maybe another version):
Schedule Work Items - When sending a calendar appointment to your workflow account about a Work Item, Scheduled Start/End times will be set accordingly and Affected User/Assigned To will be sent respective meeting invitations. That'd be cool. Right? Maybe? No?
Cireson Asset Management - It feels like there are a ridiculous amount of possibilities around updating Purchase Orders, Vendors, Licenses, etc.
Help - The idea of emailing the connector [help] to retrieve Knowledge Articles based on the email body seems like an interesting way to interact with SCSM. Not sure how useful this actually is.
Status - The idea of emailing the connector something along the lines of [status] or [health] to get the current Status of a SCSM Work Item, Health of a SCOM Distributed Application, etc. seems like an interesting way to interact with System Center at large and would only continue to make SCSM the central hub of the System Center suite. What's more, would introduce some bot like/Cortana-esque capabilities
Logging - Leverage the current Exchange Connector's registry key to introduce various levels of Windows Event Log logging, but make the descriptions far more decipherable and parametrized for future PowerShell based searches in the event deep troubleshooting is required
Finally - I have to mention @Leigh_Kilday, @Martin_Blomgren, @Tom_Hendricks, and @Brian_Wiestfor your contributions and reviews in helping create this early working version in your respective free time. You have my thanks gentlemen. And of course the developers at Cireson as portions of this simply just aren't possibly without your very awesome work.
11
Comments
I think Schedule Work Item here opens up a lot of interesting possibilities around getting back to Affected Users (i.e. setting internal expectations, modifying SLOs, creating Skype meetings, etc.), inventing new automation opportunities for SCO/SMA, and of course continuing to leverage Cireson specific features that key off of the Scheduled Start/End dates respectively for things like Cireson's Outlook Console, Change/Release Request Calendars, and Portal Calendars.
The next version is now live on GitHub and with it, more features:
The Announcement feature opens up new automation avenues for SCO/SMA that can trigger emails in response to various Work Items that dynamically create announcements and their respective priority while fully integrating with core System Center and Cireson platforms.
This is pure genius!
I'll certainly be spreading the word about this to people who want to try it out in their environments. Being an open source unsupported solution might be a show stopper for some, but I know of many who want some of this functionality so bad, they wont care.
Great work good sir.
We are one of those places that would normally see the lack of support and the fact that it is open source as showstoppers, but we are implementing this script.
The Exchange Connector simply cannot provide the same functionality as "most other" ITSM platforms. The number of "the old system did that, why can't this one" comments and the HUGE performance impact caused by having to (i.e. actual business requirements) support a large number of distinct mailboxes put the Exchange Connector as the root cause of many issues we currently experience with SCSM. It just doesn't scale--Microsoft verbally stated 15 as the maximum number anyone should attempt to run, and it is necessary for us to run more than 3x that number to meet our requirement. If I replace all of those Exchange connectors with this single script running once every ~5 minutes, I can still monitor all of those mailboxes but without reducing my primary management server to paperweight status and breaking other workflows, etc.
As for the "other system" functionality, one example that Adam added early on was the [take] keyword, which lets someone self-assign to a ticket via e-mail. Basic stuff, but it is non-existent in the Exchange Connector. One of the great things about this script is that PowerShell is the only limitation to other functionality that one would like to add, and "limitation" does not often appear in the same sentence as "PowerShell."
Finally, I would add that the "lack of supportability" argument is easier to mitigate when one realizes that this script is primarily made up of other PowerShell modules and EWS, which are supported. What about the open-source SMLets which are not supported, you ask? There is a version of this script that utilizes the OOB Service Manager cmdlets instead of SMLets, for those who are more comfortable with that arrangement or prefer using them in SCORCH runbooks, for example.
I know that this will not match everyone's experience or address all concerns, but there is a lot to gain from leaving the Exchange Connector behind for this, and the "cost" is very low in my situation. If these examples seem similar to your own situation, I hope I have added something meaningful to your decision-making process.
Can you provide a little more instruction on how you use the script to monitor multiple mailboxes? Or do you mean you would have a scheduled task running a specific script for each mailbox to be monitored? So if I have 60 mailboxes to be monitored(our accounts live in O365 and we don't do impersonation), I'd have 60 scheduled tasks and 60 separate scripts? I'm still digging through the script and I'm still figuring out how to implement it.
In my test environment, all of my mailboxes have redirection rules to send their mail to a single, "central" mailbox. By redirecting instead of forwarding, all of the header information is preserved as originally written, and the script can read which mailbox the message was originally sent to. In the script configs, I specify the name of an SR template and an IR template to apply for messages that were sent to them, in a hashtable. When the script reads the messages from the inbox of the "central/main" mailbox, it looks for a matching address in this list of templates. If it finds a match, it uses the templates for that mailbox. If it does not find a match, it just uses the defaults.
As an example, if I send a message to team1Mailbox@company.com that redirects its mail to serviceManager@company.com, the script will see that the message was sent to team1Mailbox@company.com, check the configs and apply the appropriate template that all messages received by team1Mailbox@company.com should get. (if there was no match, it would have applied the default template, sending the ticket to the service desk, in my case).
More importantly, I am only running one script against one mailbox, but I still have 50 unique mailboxes that get their own templates and appear to operate independently. In my particular case, I am running the script in SMA so that my calls to Exchange do not burden it. In a clean environment with no load on it, the script runs in about 1-2 seconds, whether it processes messages or not.
This is working in my QA environment so far, and I hope to share it in the next few days. It is actually a very small modification to what Adam wrote, IMO.
Hey @Nick_Flint - looks like it isn't there but I've created an issue on GitHub to get it added into the next version as it's a rather simple addition. If you can't wait, I've also updated the issue to include how you could modify the current version to support this with a simple copy and paste of a single line.
Now live on the master branch is version 1.4 of the connector:
Being able to create additional Work Item types opens up a wealth of new avenues for organizational process. For example, you could create other mailboxes to handle Change Requests submitted by Vendors, introduce email reply scenarios that only allow a specific tier of analysts to generate Problems, or you simply want to grow your SCSM deployment to new departments that wish to use their own custom inbox without weighing down your workflow server. Perhaps you already have a growing number of inboxes and wish to collapse them into a single one to simplify? Now using mail redirection on Exchange you can redirect mail all into a single inbox and still apply unique templates. No matter which path you choose, you can continue to push SCSM to the central hub of your ITSM organization and process automation endeavors - and continue to do it all through email.
I hope your chair has seat belts, because you should probably buckle up for this.
Now available on GitHub is minor release v1.4.3 and with it - a new and highly experimental feature…
Artificial Intelligence Analyst: An inherit problem with the stock connector and this one is simple - they're a bit dumb. "Email becomes Work Item. Email updates Work Item. Done." Not to mention, when it comes to the connector you've always had to pick either Incidents or Service Requests as the default Work Item type. But what if you didn't have to? What if Service Manager could just do it for you? Now leveraging the power of machine learning through Microsoft Azure Cognitive services, emails can now be optionally scrubbed for keywords and run through sentiment analysis.
This feature requires an Azure subscription along with a deployed instance of Cognitive Services Text Analytics API. It may incur monthly costs depending on usage. Please ensure you understand the potential financial costs to your organization before enabling this feature. Here's how to find information on Microsoft pricing, how you can test the service out for free via the web, and see if your language is supported. Finally, an explanation on Microsoft's algorithm can be viewed here on TechNet.Azure Cognitive Services offers a wealth of APIs to tap into including Vision, Knowledge, Language, Speech and general Search. While the above introduces just a small part of the Language API, items such as the Speech API would potentially open up the possibility of parsing missed called/voicemails to Work Item descriptions (speech to text) and the Knowledge API could further extend the search capabilities of one's growing SCSM knowledge base.
Don't forget that a GitHub account along with Watching the repo means you can receive notifications as new Issues (feature requests, questions, bugs) are raised and of course means you can submit your own changes to the connector. So if you don't have one, get one!
@Michael_Clark's question
@Rick_Reyes' question
Creating a Custom Administration Setting - I think it's fair to say most of us know the name Travis Wright. Maybe you've seen that blog post of his for building a Settings MP that lets you write values into SCSM through the Admin Settings pane through a custom UI and management pack? If you're a skilled developer the article was probably just enough to push you over the edge to full understanding. But if you're not a developer, the chances of understanding where all of this code goes is a different story entirely. That's why apart from announcing the plan to begin the creation a custom Settings MP for the connector so as to persist settings through script upgrades; I'm even more excited to share that after several of my own head-to-desk hours later I will be entirely rewriting Travis' blogpost from scratch showing all the non-developers out there how to go about creating such a thing. It's my goal to make it a complete, step by step, start to finish series that anyone of any skill level can follow along. But where would those articles those get published?
SMlets Exchange Connector, The Blog - If you were looking closely at the Github repo within the last couple weeks, a blog was added through GitHub pages (e.g. docs folder). I'm rather excited about this because apart from being able to provide more content on the connector it gives readers the ability become contributors by submitting Fork and Pull Requests to said blog. That means if something isn't quite as clear as it should be or some grammar is bothering you have the power to change it. All you need is a GitHub account.
Artificial Intelligence, GitHub Project - In the most recent version, the connector gained Azure Cognitive Services abilities enabling the connector to parse emails for the Affected User's perceived attitude thereby automatically understanding how to create Incidents vs. Service Requests. Then moving one step further and picking out keywords for improved Request Offering/Knowledge Article suggestion. As I've been saying, this really feels like its just the tipping point. Things like voicemail transcription, OCR for screenshots, and providing image content tagging are more Azure APIs just waiting to be integrated. So apart from them being their own requests on the repo featuring functional and working PowerShell examples you can try out for yourself, they've now been grouped together under the new AI Project to provide a clearer picture of this subset of enhancements.
Hi Adam,
regarding your admin settings - I have done this (for another purpose), too with VS (creating singleton classes for the settings...) - but what about creating a standard class (with multiple instances) where each instance holds a specific configuration setting - if you servicing more than one exchange connector - so each instance holds the whole settings for one connector instance
If the GUI is not that important to have it inside SCSM Console - why not creating this with plain PS ? (e.g. maybe someting like a configuration PS module for theSMLets Exchange Connector)
Just some thoughts on this - regards
Roland
@Roland_Kind - Hrm.
You know what time it is? Time for another release on GitHub!
1.4.4 of the connector has bug fixes, optimizations, and of course more features:
First Response Date on Suggestions: This is a really useful data point for reporting, but depending on who you ask it's a feature within native SCSM that can easily be overlooked. So if you've enabled Suggest Cireson Knowledge Articles or Suggest Cireson Request Offerings, the connector can now optionally mark this date for you. Credit to @Brett_Moffett for this process improvement idea that came up during discussion on the article he wrote about the connector!
[take] Manual Activities: Do you like the ability to self assign Work Items from email? No reason to stop at the core Work Item classes because now it's possible to [take] a Manual Activity for yourself
Support Group [take] enforcement: Continuing along from previous versions, you can prevent Analysts from using [take] unless the Work Item is currently assigned to a Support group they are in. This functionality now works against Manual Activities and Change Requests if you've performed Support Group class extensions against these classes
Configurable private keyword: This keyword is now configurable to support non English deployments of SCSM
Minimum Word Match for Knowledge Article Suggestion: To have a closer parity with the Suggest Request Offering feature, if you turn on Suggest Cireson Knowledge Articles when your Knowledge Base is searched it will only email back suggestions to the Affected User whose original email contained at least some configurable minimum number of words matched. This provides an inherently tighter scoping of relevant Knowledge Articles regardless if you're using Azure Cognitive Services to drive the results or not
Default Resolution Categories: A gap in the native Exchange Connector is that if an Incident gets [resolved] the Resolution Category is left blank. Now you can optionally set a default Resolution Category on Incidents/Problems and Default Implementation Results on Service/Change Requests
Enhanced Action Logging: Up until this point, any actions taken against a Work Item (e.g. Take, Resolve, Reactivate, etc.) most of the time were marked as an Analyst Comment in a Work Item's Action Log. Now Action Log entries mimic native SCSM Console functionality thereby bringing consistency between console, Cireson SCSM portal, optional data warehousing, and the SMLets Exchange Connector. In addition, the PowerShell function written for this feature can be used independently of the connector for those looking to perform Action Log entries against Work Items for your own processes outside of email
Flexibility around Azure Cognitive Services features: The connector's Azure AI ability on the previous release (v1.4.3) was a rather all or nothing move. Now you can independently enable Azure Cognitive Services for dynamic Work Item Creation (Incident or Service Request based on perceived user attitude), Suggest Request Offerings, Suggest Knowledge Articles, or all of them.
This update closed a near equal amount of feature requests and optimizations along with a few bugs. Thanks again to @Nick_Flint for reporting that Skipped MAs don't Render as Expected in the Cireson Portal and rameuses for your Issues. As always if you want to get involved with building for the connector all it takes is a GitHub account, forking the repo, and then making changes.
I had never thought about it before, but there are a few other useful general-purpose functions in the script, too. I like how simple it is to get up and running with the script in its current form vs. having to also install a module, but there's something here to ponder.
I wonder what other folks who are using this think?
$defaultNewWorkItem = "ir"
$UseMailboxRedirection = $true
What am I missing?