IT Monkey:   Join the Cireson Community today for your chance to win $50!
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.


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_DzyackyAdam_Dzyacky Customer Contributor Monkey ✭✭✭✭✭
edited May 2017 in Community Uploads
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:
  • 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_Wiest ;for 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.


  • Adam_DzyackyAdam_Dzyacky Customer Contributor Monkey ✭✭✭✭✭
    edited August 2017
    Added two new features that are now available on the GitHub repo.

    • Merge Email Replies: Someone emails your workflow account and several others. A person in the chain Replies All. As a result, the Exchange Connector on its next sync creates two new default work items. This new feature will now write the Exchange Conversation ID into the Description of the File Attachment, enabling "Get-SCSMObject -Filter" to quickly query on the data and allow replies to be merged into the correct Work Item instead of creating duplicates whether it be during the current or previous processing loops
    • Schedule Work Items: Now you can book calendar appointments with your workflow account that will set the Scheduled Start/End time of the work item. Appointments can be re-scheduled which in turn update the calendar and work item respectively. In addition, if you're leveraging the Cireson Outlook Console to schedule reminder's on work items this now enables you to CC your workflow account and thus update its calendar and set the scheduled start/end times on the work item. This also applies to wholly new work items as well, so booking appointments with the workflow account will still create new default work items and set their scheduled start/end dates in addition to the creation. Finally, the Action Log is updated based on who scheduled the work item (Analyst/End User) and marking the comment as isPrivate = $false so as to automatically notify the other party per Cireson's Action Log Notify.

    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.
  • Adam_DzyackyAdam_Dzyacky Customer Contributor Monkey ✭✭✭✭✭
    edited November 2017

    The next version is now live on GitHub and with it, more features:

    • SCOM integration: Now configurable authorized users/groups can interact with Operations Manager to retrieve Distributed Application Health and Alert count. Just request the [health] in the subject and the [Distributed Application] in the body of your email
    • Cireson Portal Task, Send Outlook Meeting: I'm a bit biased, but I really liked the previous versions "Schedule Work Items" feature. To make this experience even more seamless, a new Cireson Portal task is available on Work Items to kick open your local email client with pre-formatted Attendees and [Work Item] in the Subject (generates an *.ics file)
    • Search Available Requests: Much like the Search Cireson Knowledge Base function, this feature will parse the inbound messages and email back a list of relevant request offerings within that user's Service Catalog Scope using the Cireson web portal API. If you're using this feature in addition to the Knowledge Base feature, this will combine results into a single email
    • Digitally Signed/Encrypted emails: Thanks to the open source MimeKit project, processing digitally signed or encrypted messages is now possible. Just place the necessary certificate in the Local User/Local Machine store and you're ready to go
    • Announcement integration: Maybe your users don’t read all of your Service Manager emails, so you use Announcements on the Cireson SCSM Portal. Maybe your users don’t live on the Cireson SCSM Portal, so you use Cireson's SCSM Ticker App. Maybe you just aren't using announcements altogether and instead just sticking with emails...I just got a feeling of deju vu. The point is you must pick and tailor these disjointed experiences to cover all of your announcement bases. This new feature of the connector now enables the ability to email or schedule meetings with the connector that will create/update either SCSM Announcements and/or Cireson SCSM Portal Announcements from your email client of choice with the new [announcement] keyword. Cireson Portal customer? The connector will create announcements for each group discovered on the message. Need to set the Priority? Just tag the message with an additional #low or #high

    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.

  • Brett_MoffettBrett_Moffett Cireson PACE Super IT Monkey ✭✭✭✭✭
    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.
  • Tom_HendricksTom_Hendricks Customer Ninja IT Monkey ✭✭✭✭
    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.
    You are absolutely correct about both parts of that statement, @Brett_Moffett, but I want to address that group that is somewhere in the middle, looking at the pros and cons and comparing them to their own risk profile and requirements. 

    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.
  • Jerrett_FergusonJerrett_Ferguson Customer IT Monkey ✭
    Tom, We're in the same boat as you.  We currently have 60 Exchange Connectors running in SCSM 2012 R2 and the performance hits from that many connectors running every ten minutes is finally starting to bite us. 

      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. 

    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.   
  • Tom_HendricksTom_Hendricks Customer Ninja IT Monkey ✭✭✭✭
    Sure!  I have modified a copy of Adam's script with an optional additional feature.  I will share the modification soon so it can be considered for merging with the rest of the script.

    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 that redirects its mail to, the script will see that the message was sent to, check the configs and apply the appropriate template that all messages received by 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.
  • Jerrett_FergusonJerrett_Ferguson Customer IT Monkey ✭
    I would love to get ahold of your modified script.  That's exactly what I've been wanting to do in our environment as a replacement for our 60 Exchange Connectors, but I didn't know how to implement it.  Please let us know when you've updated that.  Thanks!
  • Nick_FlintNick_Flint Customer Adept IT Monkey ✭✭
    This looks great. Does it handle SR Acknowledgments?
  • Adam_DzyackyAdam_Dzyacky Customer Contributor Monkey ✭✭✭✭✭

    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.

Sign In or Register to comment.