Configuration: Request Offering and Knowledge Article Suggestions

Requirements

In order to use this feature, the following conditions must be met:

• You are using the Cireson Portal
• You are licensed/paying for the Cireson Portal (APIs will not work without a valid license)
• To suggest Knowledge Articles, you must be using the Cireson HTML Knowledge Base

General

Once the SMLets Exchange Connector has been configured to process email, additional configuration will enable you to leverage your Cireson investments by suggesting relevant Request Offerings and/or Knowledge Articles to the Affected User (From) on the portal when New Work Items are created. Depending on which version of the connector you are using (v1 or v2), configuration will be ever so slightly different.

Additionally, suggesting Request Offerings to users honors your environment's RBAC. That is to say, a user will only ever be suggested Request Offerings they themselves could access through the portal.

Version 1.x
In the pure PowerShell based connector (v1), configuration takes places across the following variables.

$searchCiresonHTMLKB = $false
$numberOfWordsToMatchFromEmailToRO = 1
$numberOfWordsToMatchFromEmailToKA = 1
$searchAvailableCiresonPortalOfferings = $false
$enableSetFirstResponseDateOnSuggestions = $false
$ciresonPortalServer = "https://portalserver.domain.tld/"
$ciresonPortalWindowsAuth = $true
$ciresonPortalUsername = ""
$ciresonPortalPassword = ""
...
$htmlSuggestionTemplatePath = "c:\smletsexchangeconnector\htmlEmailTemplates\"

Version 2.x and up
In the Settings MP (v2), configuration takes place in the Administration -> Settings -> SMLets Exchange Connector UI. Like the version before it, head first into "DLL" and define the path to the HTML Templates. Then head into the "Cireson" tab and define the settings similar to the above (v1).

Customizing the Templates

When you download the SMLets Exchange Connector, a directory exists called "HTMLEmailTemplates". This contains the 3 HTML files you can edit to match any branding you may have performed for the rest of SCSM. They are:

• suggestKA.html - Template used only when Suggest KA has been enabled
• suggestRO.html - Template used only when Suggest RO has been enabled
• suggestKARO.html - Template used when both Suggest KA and RO have been enabled

These three templates all make use of tokens as seen inside of their respective files. These tokens are replaced with URLs to Request Offerings and/or Knowledge Articles when matches are made. For the sake of consistency, the tokens always mean the same thing regardless of template.

• {0} = Knowledge Articles
• {1} = Request Offerings
• {2} = Resolve/Cancelled Keyword

Take the following example as seen in the suggestKARO.html file

body>
    <table width="100%" border="0">
      <tr>
        <th scope="row">We found some knowledge articles and requests that may be of assistance to you: <br /><br/>
        {0}<br /><br/>
        {1}</th>
      </tr>
      <tr>
        <th scope="row">If any of the above helped you out, you can {2} your original request.</th>
      </tr>
    </table>
</body>

When the email goes out, these tokens are replaced with URLs. In the case of the Resolved/Cancelled keyword, it's replaced with a mailto: link back to the primary SCSM inbox.

Templates can be customized with any amount of HTML you desire and are preserved throughout upgrades of the connector - just don't overwrite them when you upgrade!

Performance Consideration: Suggest Request Offering

As of v8.x of the portal - the Stored Procedure in the ServiceManagement database that returns Request Offerings does so with the the icon (base64 image data) chosen for the Request Offering. This adds some weight to the call so it's recommend to modify this stored procedure as described here - https://community.cireson.com/discussion/3468/light-weight-version-of-api-getservicecatalog#latest. This modification is supported by Cireson, would have to be applied after every portal upgrade, and does nothing more than remove the base64 image data from being returned through the API call.

To help frame the decision making process around whether or not to modify. Consider the following environment variables -

• The total size of your Service Catalog
• The amount of Request Offerings being suggested for a single email
• The average amount of emails to process in a single loop of the connector
• The average file size of the icons chosen for Request Offerings