Installation Guide

Editions

itnetX Send Mail for System Center Service Manager (SCSM) is available in two editions:

  • itnetX Send Mail for System Center Service Manager Free
  • itnetX Send Mail for System Center Service Manager Pro

The following table lists the features available in both versions of the product:

Feature Free Pro
Support for Incidents x x
Support for Service Requests x x
Support for Problems x x
Support for Change Requests x x
Support for Release Records x x
Support for Activities x x
External recipients x x
Multiple recipients x x
Recipient picker with lookup in CMDB x
CC recipients x x
BCC recipients x x
Disable/Hide BCC recipients x x
Multiple notification templates x x
Multiple languages for notification templates x x
Rich-text editor x
Paste images in-line with email body x
Set Incidents to Pending if user feedback is required (Is Question) x
Attachments from clipboard x x
Browse for file attachments x x
Attachments from work item x
Add attachments to work item x
Add email message body to the action log x x
Uses default SCSM SMTP notification channel x x
Auto-complete addresses x x
Addresses handled as objects x x
Non-modal window x x
Configurable Return address x
Message Templates x x
Resolve incident from Send Mail x
Assign work item to analyst if AssignedTo is not set x
Set First Response Date when Send Mail is used x
Advertisement in user interface x

Installation

Prerequisites

Before installing itnetX Send Mail for System Center Service Manager (SCSM), you must have:

  1. A correctly configured SCSM environment (SCSM 2012 SP1 or SCSM 2012 R2).
  2. The E-Mail Notification Channel under AdministrationNotificationsChannels in SCSM must be configured.
  3. Optionally you can configure the incoming email processing options under Incident Settings or the Exchange Connector if the processing of replies is required.

Installation

The installation is performed using the management pack import functionality of SCSM. Please refer to the Microsoft TechNet Library for more information on how to import management packs:

http://technet.microsoft.com/en-us/library/hh524269.aspx

LastModified date of incidents will change

The management pack you are about to import contains a class extension for the Incident class. This will cause the Last Modified date of all incidents in SCSM to be updated to the current date and time.

Follow these steps to install Send Mail for SCSM:

  1. Log on to SCSM Workflow server using an account with administrative privileges in SCSM. The SCSM Workflow Server is by default the first SCSM Management Server installed.
  2. For SCSM 2012, copy the 2012\itnetX.SendMail.Workflow.dll , and for SCSM 2016, copy the 2016\itnetX.SendMail.Workflow.dll to the SCSM installation directory. By default, this is C:\Program Files\Microsoft System Center 2012\Service Manager\ for SCSM 2012 (including SP1, C:\Program Files\Microsoft System Center 2012 R2\Service Manager\ for SCSM 2012 R2, and C:\Program Files\Microsoft System Center\Service Manager\ for SCSM 2016.
  3. For SCSM 2012, import the itnetX.SendMail.UI.2012.mpb management pack. For SCSM 2016, import the itnetX.SendMail.UI.2016.mpb management pack.
  4. Import the itnetX.SendMail.Configuration.xml Management Pack into your SCSM environment.
  5. Restart the SCSM Console.

Update existing installation

If you are currently running version 1.x of Send Mail, please note that version 2.x of Send Mail requires a new license management pack. Customers under active maintenance & support can request a new license management pack by contacting customers@operaio.ch.

Follow these steps to upgrade Send Mail for SCSM:

  1. Log on to your SCSM Workflow server using an account with administrative privileges in SCSM. The SCSM Workflow Server is by default the first SCSM Management Server installed.
  2. For SCSM 2012, copy the 2012\itnetX.SendMail.Workflow.dll, and for SCSM 2016, copy the 2016\itnetX.SendMail.Workflow.dll to the SCSM installation directory. By default, this is C:\Program Files\Microsoft System Center 2012\Service Manager\ for SCSM 2012 (including SP1), C:\Program Files\Microsoft System Center 2012 R2\Service Manager\ for SCSM 2012 R2, and C:\Program Files\Microsoft System Center\Service Manager\ for SCSM 2016. If the file is locked, you will have to restart the Health Service on the Management Server.
  3. For SCSM 2012, import the itnetX.SendMail.UI.2012.mpb management pack. For SCSM 2016, import the itnetX.SendMail.UI.2016.mpb management pack.
  4. In case you are upgrading from version 1.x:
    a. Import the itnetX.SCSM.SendMailv2.LicenseInfo.mp Management Pack into your SCSM environment
    b. Optionally, delete the itnetX.SCSM.SendMailv1.LicenseInfo.mp Management Pack from your SCSM environment.
  5. Restart the SCSM Console.
  6. In case you are upgrading from version 1.x:
    a. Open the SCSM Console and go to Administration – Settings, and then double-click itnetX Send Mail Settings. Check that all settings are okay and click OK to save the settings. You have to click OK even if you did not change anything. You should receive a message that Send Mail was successfully upgraded.
  7. In case you are using the itnetX ITSM Analyst Portal, copy the content of the Portal folder found in the Send Mail installation archive to the root directory of the ITSM Portal website, replacing already existing files, and then restart the ITSM Portal website and clear your browser cache by reloading the ITSM Portal with Ctrl-F5, ITSM Portal v.3.7.15 or later required

Enabling Pro Features

To enable the Pro features of Send Mail, you require either a trial or full license. You must install one of these license file types to activate the features of the Pro edition. To install the License Management Pack (trial or full license):

  1. Import the itnetX.SCSM.Licensing.Library.mpb Management Pack into your SCSM environment.
  2. Import the itnetX.SCSM.SendMailv2.LicenseInfo.mp Management Pack into your SCSM environment.
  3. Restart the SCSM Console.

Send Mail Permissions for User Roles

itnetX Send Mail for SCSM introduces a new class to the CMDB of SCSM. This new class is required to trigger the sending of emails without the need for a Outlook, or other messaging software, client. The solution, once installed and activated, is scoped at the Administrators SCSM user role (only the users of Administrators have permissions to write instances of this class).

In a typical environment, your analysts are assigned to other user role profiles, such as Incident Resolvers, Service Request Analysts, or Advanced Operators. To enable other user roles access to itnetX Send Mail for SCSM, you must grant permissions to the classes and relationships used by itnetX Send Mail for SCSM.

Please follow these steps to grant the required permissions to a user role profile:

  1. Copy the Set-SCSMProfileOperation.ps1 and Set-SendMailPermissions.ps1 files to your SCSM management server (copy both files to the same folder).
  2. Open Set-SendMailPermissions.ps1 in a text editor of your choice.
  3. Find the line $profilename = "AdvancedOperator" and change the value Operator to the desired user role profile. Possible values are:
    a. EndUser
    b. ActivityImplementer
    c. AdvancedOperator
    d. Author
    e. ChangeInitiator
    f. ChangeManager
    g. IncidentResolver
    h. Operator
    i. ProblemAnalyst
    j. ReadOnlyOperator
    k. ReleaseManager
    l. ServiceRequestAnalyst
  4. Find the line $scsmServerName = "localhost" and change the value localhost to the name of your SCSM management server if needed.
  5. Save and close the file.
  6. Run Set-SendMailPermissions.ps1 in PowerShell as administrator.

Using Send Mail in the itnetX ITSM Analyst Portal

You can use Send Mail with the itnetX ITSM Analyst Portal.

To install Send Mail for the itnetX ITSM Analyst Portal:

  1. Copy the content of the Portal folder found in the Send Mail installation archive to the root directory of the ITSM Portal website.
  2. Restart the ITSM Portal website
  3. Clear the browser cache by reloading the ITSM Portal with Ctrl-F5

Send Mail Plugin for ITSM Portal Versions prior to 5.0
The Send Mail plugin version 2.1.x.39 or later requires the ITSM Portal 5.0 or later to work.
In case you are using a ITSM Portal version older than 5.0 you must replace the ITSM Portal plugin in wwwroot/lib/custom with the plugin provided in the Portal Legacy folder of your installation media.

How it works

itnetX Send Mail for SCSM contains two parts: A Console Task and a Workflow.

When the analyst clicks the Send Mail task in the user interface (please refer to the Usage Guide for more information on how to use itnetX Send Mail for SCSM), a new object of class Send Mail Object will be created and the Send Mail form opens. This form contains information about Send Mail settings selected by the analyst and is related to the work item (Incident Request, Service Request or Problem). A new Action Log record is added to the work item with the title “Email queued for delivery”. If the option Is Question was checked, the status of the incident is changed to “Pending” (this only applies to incidents).

The creation of the Send Mail Object triggers a workflow. This workflow retrieves the notification template from SCSM, parses the template using the selected language, and sends the notification to the selected recipient(s) using the SMTP server defined in E-Mail Notification Channel. If the email send action is successful, then the Action Log record is changed to “Email sent”, otherwise it will be set to “Email delivery failed”.

If sending was successful, then the Send Mail Object is deleted from SCSM. Attachments sent using the sent mail will either be retained in SCSM as a related item or deleted depending on the itnetX Send Mail options.

Please note: Attachments added to the work item will remain in SCSM. If you do not want this default behavior, you can uncheck the option in the settings of Send Mail: Add attachment to work item. All settings of itnetX Send Mail are described in Send Mail Settings.

Configuration

itnetX Send Mail for SCSM is ready to use after the installation completes, however you can configure additional options.

Console Tasks

By default, the Send Mail console task is available for Incident Requests, Service Requests, Change Requests, Release Records, and Problems forms and views. You can show/hide the console task for certain users by using SCSM user roles.

Notification Template

As part of the itnetX.SendMail.Configuration Management Pack, we ship a basic notification template which can be customized to accommodate your needs.

You can find the template named itnetX Send Mail Template under Administration – Notifications – Templates.

Please note that the notification template is targeted at the Send Mail Object class. You can include properties of the related work item through the Send Mail Object Related to Work Item relationship which is available when browsing for properties in the notification template.

All templates targeted to the Send Mail Object class will be available for analysts in a Send Mail task.

The notification template is generic for all work item types. If you want to include properties specific to a class which is derived from the work item class, you have to add all corresponding properties adjacent to each other. As an example, the Status property is a property available for Incidents and Service Requests, but not available on the Work Item class. If you want to add the Status property to the notification template, you have to add the Status property of the Incident class and the Status property of the Service Request class directly next to each other.

Example: Adding the Incident Status and Service Request Status in a notification template.

Status: $Context/Path[Relationship='SendMail!Syliance.SendMail.UI.SendHelperForWorkItem' TypeConstraint='Incident!System.WorkItem.Incident']/Property[Type='Incident!System.WorkItem.Incident']/Status$$Context/Path[Relationship='SendMail!Syliance.SendMail.UI.SendHelperForWorkItem' TypeConstraint='ServiceRequestWI!System.WorkItem.ServiceRequest']/Property[Type='ServiceRequestWI!System.WorkItem.ServiceRequest']/Status$

For more information about working with notifications, please refer to the Microsoft TechNet Library at http://technet.microsoft.com/en-us/library/hh519719.aspx.

Multi-Language Support

itnetX Send Mail for SCSM supports multiple languages for the notification template. Please make sure that all languages that you need are configured in the notification templates.

If you do not configure a default language, itnetX Send Mail for SCSM will use the operator’s current UI language as the default value for the language field on the Send Mail form. However, the analyst can still change the language before sending the email.

If the operator’s UI language does not exist in the notification template, the analyst has to manually select the language in the Send Mail form.

HTML and large message support

itnetX Send Mail for SCSM supports HTML-formatted messages and large email bodies >64KB which might contain inline screenshots. To support both of these features, you must add the Mail Body and the Mail Body (Stream) property to your notification template. Depending on the size of the outgoing email body, itnetX Send Mail for SCSM automatically populates the correct property of the Send Mail object. Hence it is recommended that you insert these two properties right next to each other in the notification template.

Send Mail Settings

itnetX Send Mail for SCSM allows you to define some settings which change the behavior of the user interface of the Send Mail console task. To change these settings:

  1. Open the SCSM Console
  2. Navigate to Administration – Settings
  3. Double-click Operaio Send Mail Settings

Subject pattern

You can define the default subject pattern for the Send Mail task. This pattern will be used when the Send Mail console task is clicked to set the subject for the email. The subject can still be changed by the analyst. The following tokens are available:

  • {0} for the work item ID property (such as IR123)
  • {1} for the work item Title property

The default value is [{0}] – {1}, which may result in a subject similar to [IR123] – Problem with notebook.

Hide BCC field

By checking the Hide BCC field option, the BCC input field will be hidden in Send Mail task.

Add attachments to work item

By checking the “Add attachments to work item” enabled by default option, the Add attachments to work item checkbox in the Send Mail form is enabled by default. Enabling this option results in the attachments of the email message being added to the work item.

Assign work item to analyst if AssignedTo is not set

When this option is enabled, the work item will be automatically assigned to the analyst when Send Mail is used. This will only happen if the work item is currently unassigned.

Default Template

You can define the default notification template to be used when sending emails.

Is Question

By checking the “Is Question” enabled by default option, the Is Question checkbox in the Send Mail form is enabled by default. Enabling Is Question results in the status of the incident, for which an email message is sent, to be changed to a different status, such as Pending. You can define the status using the provided dropdown field. This option is only available for open incidents.

Maximum size of attachments

Here you can define the maximum size for all attachments sent with one message. Send Mail will prevent the operator from sending messages which exceed the size specified here. Leave this to 0 if you do not want to apply a size limit.

Set First Response Date when Send Mail is used

When this option is enabled, the First Response Date property of the work item will be automatically set to the current date and time when Send Mail is used. This will only happen if the property does not yet have a value.

Default language

You can define the default language of the notification template to be used when sending emails. All languages available in the notification template are listed in the dropdown box. If you do not specify a default language, the Send Mail form will default to the operator’s UI language (if available). Please refer to Notification Template for correct configuration of the notification template.

Default Font

You can define the default font family, font size, and color for Comment text in the Send Mail task. This can be useful to differentiate between email text and comment text in the resultant email body.

Message Templates

You can create predefined message templates in Send Mail settings. Your operators can then send emails based on any of the defined message templates. To create a new message template, click Add and type your text. When you use the Pro version of Send Mail, you can define rich-text, including inline images, for your message templates.

Background Color

You can pick a color which will be used as the background for the Send Mail task window.

By disabling the option Show Send Mail using modal window, the Send Mail window will be a non-modal dialog. This means that the operators can still activate and use the work item form from which the Send Mail task was used. Please use this option carefully, as it can potentially cause write collision errors to occur when operators commit changes to the work item before submitting the Send Mail dialog.

Do not delete Send Mail Object after processing (for Debug only)

When this option is enabled, the Send Mail Object will not be deleted by the Send Mail workflow. For more information about the Send Mail Object, please see How it works.

This option is intended for debugging only. It is also useful to enable this option when you want to design notification templates so that you can test them with an underlying Send Mail Object. Please don’t forget to disable the option again when it is no longer used.

Save work item when email is sent

When Send Mail is executed from a form, when you click the Send email… button, a new action log entry is added, but the work item is not saved and the email will not be queued until the user clicks OK. Sometime this can be confusing for analysts because the email is not send if the work item form is closed without pressing OK.

You can change this behavior by enabling this option. If enabled, the work item form will be saved when the Send email… button is pressed.

This option only takes effect when Send Mail is executed from the form, not from the view. The history tab will not reflect changes until the form is re-opened.

Return SMTP address

Type an email address here which Send Mail should use as the sender address. If you leave this field empty, the return address configured in the SMTP channel will be used.

Always add value from Alternate Contact Method as Recipient

If this option is enabled then the Alternate Contact Method will be added (not replaced) to the recipient even if the email address of the affected user was found.

Enable autocomplete for email addresses

If this option is enabled, Send Mail will try to find recipients in the CMDB as you start typing in the To, CC, or BCC field. Please note that this option can slow down Send Mail significantly, depending on the number of users in your CMDB. We recommend disabling this option if you experience performance issues when working with Send Mail.

Email Action Log type

Here you can choose the action log type that is used for logging emails on the respective work items. You can choose between the action log (default) or the Analyst Comment log. Additionally you may specify whether the Analyst Comments are set as private comments or not.