Software Product Docs

Administration Guide

General

This document describes how to customize the configuration for the itnetX ITSM Portal. In this section, general settings that affect the entire portal are explained. For settings specific to either the End User Portal or the Analyst Portal, please read to respective chapters.

Portal Settings

You can access the portal settings page by clicking Portal Settings from the user menu in the topright corner of the portal, and then, click on Main Settings

Only members of the SCSM Administrators user role can access the portal settings

Main Settings

The following table explains the settings affecting the entire ITSM Portal.

Clearing the browser cache

When you change settings, you must click on Save Settings. After clicking OK, please make sure to refresh your browser cache by pressing Ctrl-F5 on the keyboard.

Setting Description
SCSM Server Enter the host name, IP address, or FQDN of your SCSM management server. The portal will always use this server to connect to SCSM
Default Portal This setting defines which portal will be loaded when users browse to the root URL. Available options are EndUser and Analyst
Theme Here you can define the theme used by the portal. By default, the base theme is used. More information about themes can be found in the Themes chapter.
Default Culture This setting allows you to define the culture that will be used when the user’s culture is not supported by the portal. The culture defines what format to use for dates, time, numbers, etc.
Default User Interface Language This setting allows you to set the default display language that will be used when the user’s language is not available. More information on languages can be found in the Localization chapter
Authentication Method Here you can change the Authentication Method to Forms Authentication. Please refer to the Forms Authentication chapter for more information
Default Domain for Forms Authentication This setting allows you to specify the default domain users will be searched in when using Forms Authentication.
Hide Language Picker This setting allows you to remove the language picker from the header of the portal
Enable “Change Password” Feature When this option is enabled, your users will be able to change the password of their Active Directory user account in the user menu in the header portal
FilterDeletedConfigItems If this option is set to “false” the portal will return items with status PendingDelete for queries (e.g GridPicket). By default this option is set to “true”. Note: This option is not available on the Portal Settings UI, you must add this setting in the Appsettings.json file in the root directory of your ITSM Portal installation.
ThrowErrorOnStaleObjectInTemplate This option is enabled by default. When enabled, the portal will suppress any error prompts related to Templates trying to load objects which do not exist in CMDB
AllowUseWorkItemIdInUrl Enabling this setting will allow your users to type the WorkItem ID (e.g. IR1234) instead of its GUID in the url to navigate to the corresponding WorkItem Form.
Note: Enabling this option may cause a performance penalty.
DisableRedirectRoFeature This setting must be set in appsettings.json directly with a texteditor.
If set to "True" the portal will not load the portal extensions required for the Redirect Request Offering feature. This may improve performance in some scenarios. However, You will not be able to use the Redirect Request Offering Feature.

Appsettings.json

All the portal settings are stored in the file appsettings.json in the root of the ITSM Portal installation directory. By copying this file from one portal installation to another, you can easily transfer your portal settings between environments.

Web.config

The web.config file contains vital settings for ITSM Portal. Changing these settings can cause unexpected behavior of the portal.

DO NOT make changes to web.config unless instruced by support.

Security and Permissions

The portal is using the logged on user’s credentials to log on to SCSM. This means that you must configure your user roles in SCSM properly to make sure the users have permissions to read the desired data. For regular end users, you should always create custom user roles of type End Users in SCSM. More information is available in the End User Security and Permission chapter.

For the Analyst Portal to function properly, you must configure more powerful user roles, such as Advanced Operators, Incident Resolvers, and so on. More information is available in the Analyst Security and Permission chapter.

Forms Authentication

The default authentication method for ITSM Portal is Windows Authentication. The itnetX ITSM Portal supports Forms Authentication. If you enable Forms Authentication, the user will be taken to a logon screen when accessing the portal. This configuration is useful if you want to publish the portal to computers outside of your domain environment.

Forms Authentication

To enable Forms Authentication:

  1. Go to Portal Settings and change the Authentication Method to FormsAuthentication. Optionally, define a Default Domain for Forms Authentication. Please refer to the General Portal Settings chapter for more information
  2. Open Internet Information Services (IIS) Manager, click the itsmPortalv3 site, and under Authentication:
    a. Disable Windows Authentication
    b. Enable Anonymous Authentication
  3. Restart IIS by executing iisreset from an elevated command prompt (Run as Administrator)

Anonymous Access

Anonymous Access allows you to configure the portal so that users do not have to sign in to the portal before being able to use it. You can define what anonymous users are able to see on the portal, and you can even enable anonymous users to fill certain request offerings.

Anonymous Access requires Forms Authentication and is only available for the End User Portal.

By combining Anonymous Access with custom landing pages, your end users will see a custom page when they go to the portal with some content that you can define. They can access views that you made available, and access request offerings that are published for anonymous access. Once they need to access more, they can sign in and get the full content of the end user portal presented. More information can be found in the Custom Landing Pages chapter.

To configure anonymous access:

  1. Create an Active Directory user account you will use for anonymous access.
  2. Make sure the user account exists in the SCSM CMDB by running the AD Connector or creating it manually.
  3. Run the following script, replacing web-anonymous with the user name you chose in step 1
    $userCls = Get-SCSMClass "System.Domain.User$" $anonym = Get-SCSMObject -Class $userCls -Filter "UserName = 'web-anonymous'" $settings = Get-SCSMObject -id d5e56c30-f265-5c50-dfd3-cdad63df07ed $rel = Get-SCSMRelationshipClass -id 1fc28c91-4ccc-abf1-a544-9d1ccefd1e60 New-SCSMRelationshipObject -Relationship $rel -Source $settings -Target $anonym -Bulk
  4. Create a SCSM User Role of type Read-Only Operators and make sure the user role has access to only the desired catalog items and views. Add the user from step 1 to this user role.
  5. Enable Forms Authentication by following the instructions in the Forms Authentication chapter.
  6. In IIS, under Authentication, click on Anonymous Authentication, click Edit, and change the user identity to the user account created in step 1
  7. Make sure that the IISSiteName setting in appsettings.json matches the name of the website in IIS. The default value is "itsmPortalv3".
  8. Change the value for EnableAnonymousAccess in appsettings.json to True.
  9. Save all changes, and restart the website in IIS.

CORS configuration

Cross-Origin Resource Sharing (CORS) allows you to perform API calls from another domain than the one of your ITSM Portal. Add the following configuration to the web.config file of your ITSM Portal instance to enable CORS:

Most of the sections and items of ITSM Portal can be accessed using direct links. This allows you to use hyperlinks to specific items in other places such as intranets, documents, or SCSM notification templates.

SCSM Notification Templates

All direct links that point to a specific item use the SCSM GUID of the item in the URL. If you want to use such a link in a SCSM notification template, you must use the following syntax:

http://[server]/EndUser/Forms/Form/$Context/?$Id$?

The following tables list the most important URLs and direct links:

End User Portal

Link to URL
Home /EndUser
Service Catalog /EndUser/ServiceCatalog
Knowledge Base /EndUser/KB
View /EndUser/Items/View/[GUID of the folder]
Request Details (IR, SR, …) /EndUser/Forms/Form/[GUID of work item]
Activity Details (RA, MA, …) /EndUser/Forms/Form/[GUID of work item]
Service Offering /EndUser/ServiceCatalog/[GUID of service offering]
Request Offering /EndUser/ServiceCatalog/CreateRequest/[GUID of request offering]

Analyst Portal

Link to URL
Home /Analyst
View /Analyst/View/Open/[GUID of view]
Item Details (any WI, CI, …) /Analyst/Forms/Open/[GUID of item]

End User Portal

This document describes how to customize the configuration for the End User Portal of the itnetX ITSM Portal.

Free Edition

When no license is installed, or the installed license is invalid or expired, the End User Portal will run as a Free Edition. The Free Edition of the End User Portal offers a reduced set of features. The following features are not available in the free edition:

Security and Permission

For the end user portal to function properly, you must create a custom SCSM user role of type End Users and assign it to your portal users. By using custom user roles, you can granularly control…

  • …which service offerings and request offerings should appear in the service catalog (use catalog item groups to restrict access)
  • …which work items are displayed in the portal views (use queues to restrict access)
  • …which configuration items are displayed in the portal and inside query results in request offering forms (use groups to restrict access)

You can follow these instructions if you want to create a custom user role with no restrictions for your end users.

  1. Open the SCSM Console, under Administration – Security – User Roles, Create a new user role of type End User
  2. Click Next, and then enter a name such as Portal Users.
  3. Click Next six times until you reach the Users section (leaving all options at their default values)
  4. Add your Active Directory users. If you want to add all users, you can simply add the Domain Users Active Directory user group.
  5. Click Next, and then click Create to create the group. Click Close.

You can use multiple user roles for different groups of users where each group is restricted to certain items in your service catalog or CMDB. Please read the SCSM documentation to find out more about using groups and queues.

Working with scoped user roles

ITSM Portal stores extended features made available through the Edit RO for ITSM Portal wizard in an extension object in the SCSM CMDB. These features include:

  • Conditional Questions
  • Repeating Tables
  • Multimapping
  • etc.

If you are using user roles with restricted access to service catalog items, work items, or configuration items, these users will not be able to read the extension objects from the CMDB. As a result, these features will not be visible (i.e. conditional questions are always displayed, repeating tables do not work, etc.).
To resolve this, go to \Administration\Security\User Roles in the SCSM console, and do the following for all your custom End Users roles:

  1. In the Queues tab, if All work items can be accessed is NOT selected, provide access to the All ITSMPortal CMDB Extensions group.
  2. In the Configuration item Groups tab, if All configuration items can be accessed is NOT selected, provide access to the All ITSMPortal CMDB Extensions group.
  3. In the Catalog item Group tab, if b is NOT selected, provide access to the All ITSMPortal CMDB Extensions group.

End User Portal Settings

The portal settings can be accessed by following the instructions in the General Portal Settings chapter. The following table explains the settings affecting the End User Portal.

Clearing the browser cache

When you change settings, you have to click on Save Settings. After clicking OK, please make sure to refresh your browser cache by pressing Ctrl-F5 on the keyboard.

Setting Description
Default number of user prompts per page in Request Offering This number defines how many pages will be displayed per page in a request offering form. When this number is reached, a page break will be automatically added in the request form. The default value is 0, which means that no auto-paging occurs. You can manually define page breaks in the request offering configuration. Please refer to Insert a page break before a question and set the page title
Hide Generic Request from Service Catalog When this option is enabled, the Generic Request is displayed in the Service Catalog. The Generic Request is a Request Offering which ships with Service Manager out-of-the-box. If you enable this option, you should also make sure to Publish the Generic Request in all languages you require.
Service Catalog Mode Here you can define which layout of the Service Catalog you would like to use. There are a total of 3 modes. The modes are explained in the Service Catalog Modes chapter.
GUID of Default Service Offering When you select Browser as the service catalog mode, you have to enter the GUID of the Service Offering which should be selected by default when the page is loaded.
Collapse Service Offerings When you select OneClick as the service catalog mode, you have the option to collapse the service offerings automatically when the service catalog is loaded. This is useful when your service catalog contains many offerings.
Hide action log entries Setting this option to true will hide system messages from the action log on the request forms. Only user comments and analyst comments will be displayed.
Add hidden questions to user input User prompts inside a request offering can be hidden based on conditions you define (see section Add show/hide conditions to questions for more information). If you enabled this option, prompts which were hidden are still added and will appear in the user input of the request. Note: Hidden prompts inside a repeating table will always be added to the user input regardless of this setting.
Show Assigned To and Reviewers of Activities When this option is enabled, the assigned to person and the reviewers of activities will be displayed in the Activities section of the service request, change request, and other forms.
Use custom landing page When enabled, the landing/start/home page of the end user portal will be replaced with a custom page. See section Use Custom Landing Pages.
Show Summary Page before submitting Request Offerings When this option is enabled, a summary page will be displayed to the end user before a request can be submitted. Disable this option if you want to show Summary Pages for certain Offerings only. See section Request Offering Summary View.
Use Request Offering Templates By enabling this option, your users will be able to save filled request offering forms as templates for re-use. See section Request Offering Templates.
Do not require a comment when completing activities When this setting is enabled, the user does not have to provide a comment when completing manual activities, review activities, or checklist activities (the comment textbox is not required to be filled).
(Performance) Do not query permissions in forms (Review Activity form mainly affected) This setting allows to increase the loading speed of several Forms by bypassing the permission check. This was implemented with the intention to increase the loading speed of the Review Activity form.
Show "Submit request on behalf of the user" if user is in this AD group(s)... This setting allows to specify multiple AD Groups. If a user, which is a member of one of the defined AD Groups is Filling a request offering, the user is presented with a prompt “Submit request on behalf of user”. If any user is selected for this prompt, this user will be the affected user of the workitem created. If no user is selected, the current user will be the affected user.
Open this URL instead of the Home page when subitting Request Offering If any value is set for this option any User submitting a request offering will be redirected to the specified URL after submission

Service Catalog Modes

There are 3 different modes you can use for the Service Catalog. You can choose which mode to use in the End User Portal Settings.

Browser with Overview

This is the default mode. When users access the Service Catalog, they first have to choose the Service Offering. The Service Offerings are displayed with icon, title, and brief description, and are grouped by service offering category.

After selecting the Service Offering, the user will be taken to the Browser (see next chapter).

Browser

The browser displays your Service Catalog in a three-column layout, similar to the one used in ITSM Portal v2.

The first column displays the Service Offerings, the center column displays the details of the selected Service Offering, and the right column displays the available Request Offerings.

One-Click

The One-Click service catalog layout is very useful when you do not make use of Service Offering details and you want your users to get to the request form as quick as possible (in one click). The Service Catalog displays all available Request Offerings grouped by Service Offerings and categories on one page.

End User Portal Views

The views which are displayed on the Home screen, and the views available under Requests and Activities can be customized. You will find the views in the Administration section of the SCSM console.

Please note that the views shipped with the portal are using multiple type projections in the back. This feature is provided by Advanced View Editor. Editing these views requires some knowledge in XML. Also, if you want to edit the columns, you will need to export, edit and re-import the itnetX.ITSMPortalSupporting.EndUser.Configuration.xml management pack.

Make sure to use the format [#]_[Title] for naming folders and views, where [#] is used to define the order in which the element is displayed in the portal.

Home Screen

The views My Open Requests and My Open Activities which are displayed on the home screen can be modified by editing the respective views in the SCSM console.

You can add more views to the 0_Home folder and these views will be displayed on the Home screen in the portal.

Requests and Activities

The way how folders, sub-folders and views are reflected in the portal is illustrated in the following picture.

You can edit the existing views, or add your custom views and folders if you want to extend the data displayed to your users.

Custom views

If you want your custom data to be displayed in a main section in the portal, you can add a new folder such as Assets or Devices under the EndUser Portal folder. This folder will be represented as a main navigation menu entry. Then, following the schema explained in the previous chapter, you can define your sub-folders and views.

Custom view might need custom forms

The first column in each view will be clickable to the end user. Upon clicking an item in the view, the user is taken to the form of the selected item. If you are creating a view for a class for which ITSM Portal does not ship a form, the default work item or configuration item form with only a few attributes will be displayed. In this case, you can add a custom form which will expose the desired attributes for your class. For more information on custom forms, please read the Custom Forms chapter.

Web Views

You can embed external websites inside the End User Portal by using Web Views. A Web View points to an URL of your choice and is exposed to your end users in the form of an item in the main menu of the End User Portal. When the menu item is clicked, the target website will be loaded inside the portal (using a technology called IFRAME).

You can create web views in the SCSM Console. Use the Create Web View task to create a new web view under the EndUser Portal folder in the Administration section of the SCSM Console.

Advanced Request Offerings

The itnetX ITSM Portal allows you to take advanced control over request offerings. The following settings can be configured:

  • Create request offerings for change requests
  • Insert a page break before a question and set the page title
  • Prevent automatic preloading for the query result picker
  • Show query results automatically
  • Hide search bar
  • Close search results and clear search after selection
  • Use custom relationships in query results
  • Add objects to user input and target relationship
  • Use current user as default selection for query results
  • Configure prompt layout, constraints and default values
  • External Validation
  • External Data (PowerShell, CSV, SQL)
  • Auto-forward to next page when all questions are answered
  • Display questions in repeating tables
  • Add show/hide conditions to questions
  • Map object properties to prompts
  • Display icons for Configuration Items

To access these advanced features, you have to use the Advanced Request Offering Editor. You can access this editor using the Edit RO for ITSM Portal and Create RO for ITSM Portal tasks.

Create request offerings for change requests

ITSM Portal allows you to create request offerings which are mapped to a Change Request template. To create a request offering for a Change Request, click Create RO for ITSM Portal, and then select the Change Request template type from the Select template picker on the General tab

You can only create request offerings based on Change Request templates that you created manually in the SCSM console. The out-of-box standard change request templates will not work.

Insert a page break before a question and set the page title

To insert a custom page break before a question and optionally set the page title:

  1. Either create a new RO for ITSM Portal or edit an existing RO as described above.
  2. In the layout section click on the green Plus icon next to the prompt and select New Page.
  3. Enter a title for the new page.

Prevent automatic preloading for the query result picker

By default, the query result picker preloads data from the CMDB when the request offering page is opened. This can cause long loading times when the query result returns many results. Follow these steps to prevent this behavior:

  1. Launch the SCSM console
  2. Navigate to Library\Service Catalog\Request Offerings
  3. Open the desired Request Offering for editing using “Edit RO for ITSM Portal”
  4. Scroll down to Configure Prompts section
  5. Select the Query Result type prompt and click Advanced Configuration.
  6. Check the checkbox “Do not preload results (user must type something to search)”
  7. Click OK twice to exit the RO Editor.

When preloading of query results is prevented, the user must begin to type in the search box and press the Search button (or the Enter key) to load data from the CMDB. This is useful for large tables.

Show query results automatically

By default, the query result picker is collapsed even if the results are already loaded. To show the query results automatically:

  1. Click Advanced Configuration
  2. Check the checkbox Expand results by default

By default, the query result picker contains a search bar. With this bar you can expand\collapse result view and perform the search. In case when the Show query results automatically option is enabled, or when you are using query results in Display Only mode, the search bar can be unnecessary. In this case you can hide it.

To hide the search bar:

  1. Click Advanced Configuration
  2. Check the checkbox Hide search bar

Close search results and clear search after selection

When this option is enabled on a query result, and the user types something in the search bar and clicks search, and then the user selects an item, the search result will be closed and the search bar will be cleared after selection of an item.

Use custom relationships in query results

By default, you can map selected objects in query results on only two relationships: Affected Configuration Items and Related Configuration Items. To map selected objects to any relationships (including your custom relationships):

  1. Launch the SCSM console
  2. Navigate to Library\Service Catalog\Request Offerings
  3. Open the desired Request Offering for editing using Edit RO for ITSM Portal
  4. Scroll down to Configure Prompts section
  5. Select a prompt of Query Result type and click Advanced Configuration
  6. Check Add object as related items with custom relationship, select the object template, select the relationship and press the Add button
  7. To remove the mapping press the button

The relationship Reviewer is the special case. It is always displayed for Review Activities and will be handled as two relationships: RA -> Reviewer -> ReviewerIsUser. This allows to add Query Result selection as Reviewers to Review Activities.

Add objects to User Input and target relationship

This option is only available if the Query Result is in Display Only mode. If it is disabled, then the selected object(s) from the Query Picker will not be added to the request and user input. This is very helpful if you need to just display some data to your users or use them as a token (current user, for instance).

You should use the option Expand results by default in this case to display the data.

To change the Add objects to User Input and target relationship option:

  1. Click Advanced Configuration
  2. Check or uncheck the checkbox Add objects to User Input and target relationship

Use current user as default selection for Query Results

By default, no objects are selected in Query Result. If your Query Result based on User class or any derivedclasses\combination classes, then you can user current logged on user as default selection. This option doesn’t work if the Do not preload results option enabled.

To change the Use current user as default selection for Query Result option:

  1. Click Advanced Configuration
  2. Check or uncheck the checkbox Set user logged on to portal as default value (only for User class)

Configure prompt layout, constraints and default values

To configure the prompts:

  1. Launch the SCSM console
  2. Navigate to Library\Service Catalog\Request Offerings
  3. Open the desired Request Offering for editing using Edit RO for ITSM Portal
  4. Scroll down to Configure Prompts section
  5. Select a prompt and click Configure or Advanced Configuration (for Query Result type).
Display single line and multiline text boxes

For questions of type text, you can define the type of the text box: single line or multiline. The single line text box is used only if the total length constraint of the question is less than or equal to 256 chars. In all other cases the multiline text box is used.

The total length constraint is calculated based on the question’s length constraints and the length of the mapped field:

  1. If the question’s length constraints are set then this value is used to select the type of text box to display. For instance, for the configuration shown below, the single line text box is used:
  2. The minimum length of all mapped fields is used to select the type of text box to display. For instance, if the question is mapped to the Title and Description fields of the Incident class then a single line text box is used, because the maximum length for the Title property of the Incident class is 256.
  3. The minimum values of step 1 and step 2 are used to finalize selection of the type of text box.
Define prompt constraints

The ITSM Portal allows you to set constraints for questions of type:

  • Text
  • Date
  • Integer
  • Decimal
  • File Attachment

To set constraints:

  1. In Configure, select which constraints to apply to the text prompt input.
  2. Date prompts can be constrained to date ranges, either set as a specific range or dynamically using the user’s current time.

    Note: For Date prompts a Time Picker is also available
  3. Integer and Decimal prompts can be constrained to ranges

    Note: The Minimum and Maximum Values for integers are -2147483648 and 2147483647 respectively.
  4. File attachment size can be restricted.
Setting the default value

The ITSM Portal allows you to set the default value for questions of type:

  • Text
  • Date
  • Integer
  • Decimal
  • MP Enumeration List
  • Simple List
  • Boolean(True/False)

In Configure, check the checkbox set default value

Text can be any string.

Date can be an exact date or relative to user's current time.

Integer can be any valid whole number (minimum and maximum values for integers apply)

Decimal can be any decimal number.

MP Enumeration List can be selected from available enumerations

Simple List

Boolean

In addition, you can use a URL parameter to set the default value for any given question. To set the default value please add “question#=value” to the URL, where # is the number of the question, starting from 1, For example:

http://portal/EndUser/ServiceCatalog/CreateRequest/13c4d00a-b049-4887-3c46-0cc050047ca8?serviceId=165bfd8a-1149-a046-1da1-30f2f71aac6f&question1=YourDefaultValue

Control the behavior of child items in MP enumerations

You can control the behavior of questions which are bound to MP Enumeration Lists when it comes to child enumeration items.

You can prevent the user from clicking an item in the list which has children. When enabling this option, the user will have to select a leave element in the list, i.e. an item which does not have any child items. To enable this option:

  1. In Configure of a user prompt of type MP Enumeration List, under Selection Mode, choose Only elements without children

You can also bind a user prompt to a child item in a MP Enumeration List. When doing this, only child items of the selected item will be available for selection. To enable this option:

  1. In Configure of a user prompt of type MP Enumeration List, enable Bind to child item and choose a child item
Password prompts (hide input from user)

You can enable the option Hide value from end user (****** will be saved to User Input) on text prompts.

When this option is enabled, the value input by the end user will be replaced with asterixis (*) while entering it, and in the user input.

Use simple table view

The simple table view option changes the behavior of the query results dropdown. The advantage of the simple table view is, that the table will adjust its size to its content. This can be useful if data with long texts or large images shall be displayed to the user.

The disadvantage is, that this table does not allow any kind of sorting or filtering.

To configure a query results prompt as simple table, select the Use simple table view (no sorting, simple UI) in the advanced configuration of the prompt.

Use paging

Query results prompts offer the option to use paging. This will improve loading speed of query results if large datasets are used.

To enable paging, open the Advanced configuration of the Query Results Prompt and select Use paging

Do not add to User Input

This option allows you to hide the answer of this question from the user input table.

External Validation

External Validation allows you to run a validation process on the server-side. The validation logic needs to be implemented as a PowerShell script. You can enable external validation for any type of question or a complete request offering.

External validation can be used for three things:

  • Validate the input of a user prompt. If the validation fails (the script returns $false), an error message is displayed, and the user cannot submit the request offering, if the script returns a string instead of $false, the string will be displayed as validation message
  • Validate all inputs of a request offering. Enable the Summary Page of a request offering to be able to access this option
  • Show/hide user prompts based on a validation of another prompt. For more information, see section Add show/hide conditions to questions].

To enable external validation:

  1. In Configure of a user prompt (or Advanced Configuration in case of Query Result prompt type), enable External Validation
    Note: Enable the Summary Page of a request offering to be able to use External Validation for the whole request offering
  2. Choose an existing validation script or create a new one by pressing the Add button
    Note: The validation script must return $true or $false as the last object in the execution context. You may return any string instead of $false. This string will then be used as the custom validation message instead of the validation message defined in step 3.
  3. Optionally, provide a text for External validation message. This text will be displayed to the user in the portal if the validation fails. If no value is provided, then the default message “External validation failed” will be used.

External validation can validate only non-empty values. If you need to make sure that a value is provided, please set the prompt as required.

Here is a sample validation script which checks for the existence of an Active Directory computer:

Import-Module ActiveDirectory
try { $c = Get-ADComputer $value } catch { return $true }
return $false

For more information about creating validation scripts and samples, please refer to the Customization Guide.

Set default value with script

The “set default value with script” option allows you to set the value of any prompt by a powershell script. Additionally you may configure your prompt to set the default value by script again if another specific prompts value has been changed.

To enable default value with script:

  1. In Configure of a user prompt (or Advanced Configuration in case of Query Result prompt type), enable Set default value with script
  2. Choose an existing script or create a new one by pressing the Add button
  3. Optionally, check the questions which should update the current prompt if they are changed.

Here is a sample script which checks the type of the current prompt and returns a corresponding default value:

$controleType = $question.ControlType
switch($controleType)
{
    "System.SupportingItem.PortalControl.InstancePicker" {
        return "bb7e7109-3f72-f21b-b996-007c09d2ca3b"
    }
    "System.SupportingItem.PortalControl.DateTime"{
        return [DateTime]::Now
    }
    "System.SupportingItem.PortalControl.String"
    {
        return "Test string from script"
    }
    "System.SupportingItem.PortalControl.Double"
    {
        return 2.1
    }
    "System.SupportingItem.PortalControl.Integer"
    {
        return 1
    }
    "System.SupportingItem.PortalControl.InlineList"
    {
        return "Value 1"
    }
    "System.SupportingItem.PortalControl.List"
    {
        return "defb6baf-8291-7d62-c2e6-68ce80485d80"
    }
    "System.SupportingItem.PortalControl.Boolean"
    {
        return $false
    }
} 
return $null

External Data

It is a limitation of SCSM that data which you expose using prompts of type Query Result in request offerings must be stored in your CMDB. There are scenarios where you want data to be selectable without the need to storing them in the CMDB. External Query is a custom prompt type introduced by itnetX ITSM Portal which you can use in your request offerings to allow your users to select data which you retrieve directly from a SQL database, from a CSV file, or using a PowerShell script.

To use an external data source, create a prompt in your request offering and pick the type External Query.

Then, under Configure Prompts, you can select the desired data source: PowerShell Script, SQL Query, or CSV Import.

PowerShell Script

You can choose an existing PowerShell script or create a new one by pressing the Add button. There are a couple of important aspect you need to be aware of when writing your scripts:

  • Your script must return JSON data. We recommend using the ConvertTo-Json PowerShell Cmdlet.
  • If you want your portal users to be able to search the returned rows, you must implement the search logic in the script. You can retrieve the search string entered by the user using the $filterValue variable
  • If you want your portal users to be able to order the returned rows by certain columns, you must implement the ordering logic in the script. You can retrieve the order column and sort order using the $queryParams.OrderBy object variable.

Here is a sample script which returns all organizational units in your Active Directory, and supports sorting and searching.

Import-Module ActiveDirectory

if ($filterValue)
{
  $res = Get-ADOrganizationalUnit -Filter * | ?{$_.DistinguishedName -like "*$filterValue*"} | select Name, DistinguishedName
}
else
{
  $res = Get-ADOrganizationalUnit -Filter * | select Name, DistinguishedName
}

if($queryParams.OrderBy)
{
   if($queryParams.OrderBy.EndsWith(" desc"))
   {
      $res | sort $queryParams.OrderBy.Replace(" desc", "") -Descending | ConvertTo-Json     
   }
   else
   {
      $res | sort $queryParams.OrderBy | ConvertTo-Json
   }
}
else
{
  $res | ConvertTo-Json
}

You can return debug information by writing to standard output (e.g. using Write-Host). The data will be displayed in the portal if you enable the Enable debug output option.

SQL Query

Enter a SQL connection string and your SQL Query, and then click Test connection. The columns will be populated automatically.

If you are using Integrated Security in your connection string, the connection will be made using the portal Application Pool account set in IIS. You can use the option Connect using current portal’s user account to connect using the portal user, however please note that this might require Kerberos configuration.

CSV Import

Enter the path to your CSV file. When you use a local path, the CSV file must the present on the portal server. If you use multiple portal nodes in a NLB cluster, make sure the file is available on all nodes, or use a UNC path instead.

Enter the CSV Delimiter you use in your file, and check the option Has headers in case you want to ignore the first row in the CSV file.

Columns definition and mapping columns

Under Columns definition, you must add a column for each column returned by your PowerShell script, SQL query, or CSV file.

The Field Name is the name of the column, as returned by the query or script. The Display Name is the name used in the portal. Pick the correct Type, and select Visible if the column should be visible in the portal. Additionally you may select Add To User Input to set which columns should be added to the user input field.

Each column you define will be available to be mapped to any properties under Map Prompts. You can also use invisible columns (such as primary keys) in your mapping configuration.

If you enable the option Allow multiple selection, there will be only one column named JSON available for mapping, and this column contains the selected rows as a JSON string.

Options

You can use the same options for External Query like you can use for Query Results. Please see the relevant sections in this chapter for more information.

The ITSM Portal version 3.8.5 introduced a new option for external queries which allows you to specify if the external query shall be refreshed if any of the specified prompts was changed

Auto-forward to next page when all questions are answered

When you create a custom page break (see chapter Insert a page break before a question and set the page title), you have the option to enable auto-forwarding to the next page when all questions are answered.

In the example of this screenshot, the portal will automatically forward to page 2 when QR1 and QR2 have been answered. This behavior is useful when you have query results which return user-based objects, and you want to automatically forward to the next page if only one object is found (in which case the item will be selected automatically).

The auto-forward happens as soon as the page is valid. You should not use this feature with questions which require user input, such as text or number.

Display questions in Repeating Tables

Within a Request Offering you can include Repeating Tables. These Repeating Tables can display a set number of questions for a set or infinite number of iterations.

To insert a Repeating Table:

  • Create a new Request Offering or edit an existing Request Offering for ITSM Portal.
  • Configure the user prompts, then in the Layout section click the green Plus sign to add a Repeating Table.
  • Give the Repeating Table a name then chose the iterations:
    • Min Appearance (minimum 1)
    • Max Appearance (0 = infinite)
  • A new Repeating Table can be added at any time by clicking on the green Plus sign.
  • The Repeating Table can only contain prompts defined in the User Prompts section of the offering.
  • The Use in summary option adds the entered data to the summary of each repeated instance of the table when OK is clicked, so that the data can be easily seen when the instance is in a collapsed state.

Add show/hide conditions to questions

Except for the first question in an offering, any subsequent question can be configured with a show/hide condition, these apply to questions in Repeating Tables also. The conditions are formed from a Boolean expression and a conditional expression and relate to one of the preceding questions.

The Boolean part evaluates the conditional expression and returns true or false. Then the question is shown or hidden.

The conditional expression can be one of:

  • Equals (Must be exact match. No wildcards allowed)
  • Not equals (Must be exact match. No wildcards allowed)
  • Contains (Compares Strings and Simple Lists. Wildcards are implied and no wildcard characters are required)
  • Not contains (Compares Strings and Simple Lists. Wildcards are implied and no wildcard characters are required)
  • RegExMatch (Must be a properly formed regular expression)
  • Greater than (Compares integers and decimals)
  • Less than (Compares integers and decimals)
  • Greater than or equal (Compares integers and decimals)
  • Less than or equal (Compares integers and decimals)
  • External Script (uses a PowerShell script to validate. See section External Validation)

For example, to show question 2 only when question 1 equals a text string which exactly matches “This is a text string” the condition on question 2 would look like this:

The conditions are configured in the Layout section of the RO Editor, to the right of each question. By default each question will have a condition of ”Show always”.

When you configure a condition on a question which is the first question in a new page, you have the option to use the condition for the entire page by checking “use for entire page”:

When you configure a condition on a question which is the first question of a repeating table, you have the option to use the condition for the entire repeating table by checking “use for entire repeating table”

When prompts are not displayed in the ITSM Portal due to the resultant conditional evaluation then the Response Type (Required, Optional or Display Only) configured in the User Prompts section is suppressed. Only when the prompts are shown do these conditions play a part.

Map object properties to prompts

Responses and answers to prompts and questions can be mapped to writeable properties of SCSM objects. For instance, map one or more prompts to the description field of a Service Request.

All prompt types, other than File Attachment, can be mapped to object properties. Individual prompts can be mapped to individual properties, in addition you can map multiple prompts to single properties, called Multimapping. Within Multimapping you can add additional text strings, for example a Simple List prompt called HWType in a RO to order hardware could prompt for selection of hardware type (Desktop, Laptop, Monitor) and be mapped to the Title property of a Service Request with an additional string of “Hardware Order:”. This would look like “Hardware Order: [1.HWType]” and is configured as follows:

  • Edit or Create RO for ITSM Portal
  • In the Map Prompts section scroll to find the property you want to map to a prompt or prompts
  • In the Prompt Output column choose the desired prompt from the dropdown list

-OR-

  • Click on the ellipsis to the right of the Multiple Mapping column: here you can type text and select prompts from the dropdown list; click on Add to insert the prompt to the mapping.
  • When finished, multiple mappings will show in the editor window like arrays “{1}{2}{3}…” and any additional strings will also be displayed, e.g.: “Hardware Order: {1}”

Display icons for Configuration Items

The ITSM Portal allows you to show icons (images) for any configuration items inside the Query Result.

To enable this feature, you must:

  1. Set the icon using the SCSM Console or SDK
  2. Create an additional type projection.
  3. Configure a Query Result
Set the icon using SCSM console or SDK

To set the icon using the SCSM Console:

  1. Open the SCSM Console
  2. Locate the desired configuration item
  3. Click the Assign Icon console task
  4. Click the Browse… button and select the required image
  5. Click OK to save changes

Note: recommended size of images is 16x16 or 32x32 pixels

To set the icon using the SDK please create a new object of System.FileAttachment class and set the relationship between the created attachment and the desired configuration item using a Syliance.ConfigItemHasIcon relationship class. Please refer to the SDK documentation for more details.

Create an additional Type Projection

To be able to use icons inside the Query Result you must first create an additional Type Projection (or combination class in terms of the SCSM Console). This Type Projection must contain a component with the Path attribute set to the Syliance.ConfigItemHasIcon relationship class and the Alias attribute set to Icon.

Out-of-box, the Type Projection for the Business Service class exists in the Syliance.ITSMPortalSupporting.Objects Management Pack.

<TypeProjection ID="Syliance.ITSMPortalSupporting.Objects.BusinessService.ProjectionType" Accessibility="Public" Type="ServiceDesigner!Microsoft.SystemCenter.BusinessService">
  <Component Path="$Context/Path[Relationship='ITSMPortalSupporting!Syliance.ConfigItemHasIcon']$" Alias="Icon" />
</TypeProjection>

You can use this Type Projection as an example to create your own Type Projections.

Configure the Query Result

To display an icon at the Query Result:

  1. Open the SCSM Console
  2. Open the desired Request Offering for editing
  3. Add a question and set the type to Query Result
  4. Scroll down to Configure Prompts, select the created question and click the Configure button
  5. On the Select Class tab change the filter to Combination Classes and find the combination class created at the prevision step.
  6. Optionally, configure the criteria
  7. On the Display Columns tab, click on Has Icon and click on the Content column
  8. Optionally, add other columns
  9. Save Query Result and Request Offering

Set prompts values by url

You may set values of prompts by specifying those values in the as parameters (e.g. q1=Hello). This allows you to send links with certain values already pre-defined.

The following example url will set the string “Hello” as the answer for the first question in the request offering:

/EndUser/ServiceCatalog/CreateRequest/bb24fc4c-8ecf-a6bb-05b0-e1e91be6823e?serviceId=afb23dc8-564e-60aa-b08f-d244e67c058a&q1=Hello

Request Offering Summary View

A Summary page is shown at the end of a request offering if you enable the Show Summary Page option in the Request Offering Editor or if you enable Show Summary Page before submitting Request Offerings in the End User Portal Settings (see the End User Portal Settings chapter).

Enabling Show Summary Page before submitting Request Offerings in the Portal Settings will show a summary page for all Request Offerings, regardless of their configuration

The Summary Page can be configured to use an External Validation Script to validate the whole Request Offering before the user can submit a request. (See section External Validation)

The ItnetX ITSM Portal introduced a “Link Only” Request offering. This type of offering is accessible trough the Service Catalog like any other Request offering, with the difference that this offering will redirect the user to the URL specified.

To create such an offering, open any Request Offering view in your SCSM Console (e.g. Library/Service Catalog/Request Offerings), then execute the Task “Create Redirect RO for ITSM Portal”

Copying/Deleting Request Offerings

Because the itnetX ITSM Portal stores advanced settings in the CMDB and not in the management packs, using the out-of-the-box Create a Copy task in the SCSM console to create a copy of a request offering will not copy over the advanced settings. Please always use the Copy Request Offering task instead. Likewise, when you delete a request offering with the Delete task, the advanced settings will remain in the CMDB. Please always use the Delete with extensions task instead.

Copying Request Offerings between Environments

The itnetX ITSM Portal stores custom request offering settings in the CMDB. This means that if you need to copy request offerings from one SCSM environment to another (from Test to Production, for instance), you will need to import the management packs in the target environment, and then copy the custom request offering extension objects to the target CMDB.

If you only import the management pack in the target environment and forget to copy the CMDB objects, your request offerings will not function properly on the target environment.

To copy the request offerings from one SCSM environment (source) to another (target):

You need the SMLets to run these scripts: https://smlets.codeplex.com/

  1. Export the management pack(s) which contain your request offerings from the source
  2. Import the management pack(s) into the target
  3. On the source system, run the Export-itnetXExtensions.ps1 script from the \Docs directory of the portal, indicating a target file to store the CMDB objects to. Example:
    .\Export-itnetXExtensions.ps1 -pathToXml C:\Temp\ROCustomSettings.xml
    Note: It can happen that the export script does not produce an output. This means that you do not have any custom settings configured for your request offerings. If this is the case, all you need to do is importing the management packs to transfer the request offerings to your target environment.
  4. On the target system, run the Import-itnetXExtensions.ps1 script from the \Docs directory of the portal indicating a target file to store the CMDB objects to. Example:
    .\Import-itnetXExtensions.ps1 -pathToXml c:\temp\impexpRO\exp.xml –overwrite
    If you do not specify the overwrite switch, the already existing request offering extension objects in the target system will not be overwritten.
  5. On your source system, run the Move-ITSMPortalScripts.ps1 scripts from the \Docs directory of the portal to export the scripts used by your request offerings. (e.g. external validation scripts)
  6. Copy the Export from (5) to your target system and run the Move-ITSMPortalScripts.ps1 -Mode “Import” on your target system to import the required scripts.
Importing existing scripts

If you try to import scripts which are already existing on your target system, the script will not be imported unless you specify the Overwrite switch

Filter Scripts to export

If you want to export some scripts, but not all, you may use the -ListToExport parameter on the Move-ITSMPortalScripts.ps1:

.\Move-ITSMPortalScripts.ps1 -ListToExport script1,script2,script3

Filtering Request Offerings by Management Pack

If you want to only export the request offering extensions of a certain management pack, you can use the -byMP switch on the Export-itnetXExtensions.ps1:

.\Export-itnetXExtensions.ps1 -pathToXml C:\Temp\ROCustomSettings.xml -byMP

This will create one XML file per management pack the request offerings are stored in. You can than individually pick the ones you want to import in the destination system.

Request Offering Backups

You can use the Export-itnetXExtensions.ps1 script to periodically export the request offering extension objects to a file if you would like to create backups of the request offerings. But don’t forget to also back up your management packs.

Request Offering Templates

When you enable Use Request Offering Templates in the End User Portal Settings (see the End User Portal Settings chapter), the end user portal will allow the user to save the entries that were made in a request offering form as a template for later use. Once this option is enabled, your users will see the following options when submitting a request:

The saved templates can later be opened in the service catalog next to the respective request offering, using the arrow button as shown in this the screenshot:

The Request Offering Templates are stored per user in the CMDB and are available on any computer the user is using to access the portal.

Unsupported Features

The following features are not supported in Request Offering Templates: Repeating Tables, and Query Results which allow multiselection.

Checklist Activities

A Checklist Activity can be used similarly to a Manual Activity whereby an operator or delegated user is required to confirm that certain actions have been completed by checking the items in the checklist. The Checklist Activity can be completed either in the ITSM Portal or the SCSM Console.

For more information on how to use Checklist Activities, please refer to the itnetX Checklist Activity for SCSM - Usage Guide.

Form Filling Activities

A Form Filling Activity can be used in an activity workflow to provide additional information to a Request Offering where this information should be inputted by a designated person or group. For example, a New Employee request submitted through the ITSM Portal contains a Form Filling Activity to be completed by HR before the request can proceed to either the next Activity or request completion.

Creating a Form Filling Activity

  1. Create a template for the Request Offering associated with the appropriate SCSM Class i.e. Service Request but choose not to configure the template object yet.
  2. Create a RO for ITSM Portal
  3. Choose the newly created Template
  4. Configure the Prompts, Layout and Mappings for the information which needs to be added
  5. Publish the RO but do not add to a Service Offering. This is the Form Filling RO.
  6. Create another RO using Create RO for ITSM Portal
  7. Choose the newly created Template
  8. Configure the Prompts, Layout and Mappings for the information which needs to be added
  9. Publish the RO and add to a Service Offering. This is the Parent RO.
  10. Return to the Template and open the Template Form
  11. Under the Activities Tab add a Default Form Filling Activity workflow
  12. Assign this Activity to the Form Filling RO and save the Template

When an instance of the Parent RO is submitted in the ITSM Portal the Activity workflow is triggered. Once the Activity is assigned an Activity Implementer, either manually in the SCSM console or by an automation workflow, the Activity is available in the ITSM Portal for the Implementer. They can then complete the form fields and submit the change back to the request.

The assignment of the request offering, and the subsequent assignment of activity implementer, is visible in the ITSM Portal to the affected user, as is the status of the request and associated activities.

The Form Filling Activity can ONLY be completed in the ITSM Portal.

Setting custom permissions for Form Filling Activities

By default, users in any User Roles based on the End User profile have no permissions to write custom objects like Tasks for Checklist Activities. To set these permissions run \Docs\Set-itnetXFormFillingActivityPermissions.ps1 with the following parameters:

-profilename: Name of the User Role Profile (normally EndUser)
-scsmServerName: optionally, the name of the management server to connect to. The default value is localhost

To check which profile name to use:

Display Name Use this name
End User EndUser
Activity Implementer ActivityImplementer
Advanced Operator AdvancedOperator
Author Author
Change Initiator ChangeInitiator
Change Manager ChangeManager
Incident Resolver IncidentResolver
Operator Operator
Problem Analyst ProblemAnalyst
Read Only Operator ReadOnlyOperator
Release Manager ReleaseManager
Service Request Analyst ServiceRequestAnalyst

The end user portal allows your end users to search their work items, the service catalog, and the knowledge base using the search feature in the header of the portal.

For work items, the data which is queried and the criteria which is used when a search is submitted comes from a view in the SCSM Console: Administration – itnetX ITSM Portal – Global Search – End User Search

You will receive a warning message when opening this view in the SCSM console. This is expected and can be ignored.

You can modify this view definition to change the data returned in the search results.

For service catalog items and knowledge articles, the search criteria is hardcoded and cannot be changed.

If you want to change the appearance of the search results (such as showing/hiding columns), you must create customized copies of the following files:

  • \Areas\EndUser\Views\Items\GlobalSearch.WorkItems.cshtml
  • \Areas\EndUser\Views\Items\GlobalSearch.ServiceCatalog.cshtml
  • \Areas\EndUser\Views\Items\GlobalSearch.KB.cshtml

For more information on customizing .cshtml files, see section Modifying shared forms and partial forms (aka views and partial views).

Customer Satisfaction

Incidents in status resolved and Service Requests in status Failed, Completed or Canceled can be rated by your end users using star-rating. Also, your end users can submit a comment on their satisfaction with the resolution of their request.

You can see the rating values and comments entered by your users by inspecting the CustomerSatisfaction and CustomerSatisfactionComment properties on the Incident and Service Request class.

You supply a default rate-value as a parameter of the Workitem’s URL.

Example: …/EndUser/Forms/Form/45e6a731-5834-b4ea-5976-198f522db5b1?rate=3

Announcements

You can use the SCSM console to create announcements for your end users. Announcements can be managed under Administration – Announcements in the SCSM console.

Any announcements you create which is not yet expired will appear on the portal home page and in the header. If at least one active announcement with status Critical is available, the bell icon in the header will turn red.

The announcement form in the SCSM console displays some misleading tasks in the tasks pane (Create Announcement, Delete, Edit). Please run the \Docs\fix-SCSMAnnouncementTasks.ps1 script as a SCSM administrator on the SCSM management server to hide these tasks.

Skype for Business Integration

If you are using Skype for Business, and your SIP addresses are imported into the CMDB using an AD Connector or a custom data import, the presence status of your users will be displayed in the portal. You can click the user icon to initiate a Skype Call or IM Conversation directly from within the portal.

This feature is only available in Internet Explorer. The Skype for Business client must be running and the user must the signed in.

Analyst Portal

This document describes how to customize the configuration for the Analyst Portal of the itnetX ITSM Portal.

Security and Permissions

For the Analyst Portal to function properly, you must configure user roles just like you would for using the SCSM console. Normally, you would use the user role profiles Advanced Operators, Incident Resolvers, and so on. You can use groups and queues, as well as restrict access to views, to control what will be made available to your analyst portal users.

More information about managing user roles can be found in the official SCSM documentation:
https://technet.microsoft.com/en-us/system-center-docs/sm/manage/admin-managing-user-roles-in-system-center-2016-service-manager

Analyst Portal Settings

The portal settings can be accessed by following the instructions in chapter 1.1. The following table explains the settings affecting the Analyst Portal.

Clearing the browser cache

When you change settings, you have to click on Save Settings. After clicking OK, please make sure to refresh your browser cache by pressing Ctrl-F5 on the keyboard.

Setting Description
Use custom landing page When enabled, the landing/start/home page of the analyst portal will be replaced with a custom page. See section Using Custom Landing Pages
Limit Analyst portal to one language You can pick a language here to force your Analysts to use the portal in one language only.
Hide action log entries (system messages) Setting this option to true will hide system messages from the action log on the request forms. Only user comments and analyst comments will be displayed.
Enable persistent user view filters If you enable this option, column filters set on views will be saved per user. Users must use the “Reset View” task to remove the filters.
Use custom permissions for tasks When enabled, you will be able to show/hide analyst portal tasks for certain SCSM user roles. See section Task Permissions.
Disable loading of SCSM console tasks When enabled, console tasks defined in SCSM will not be loaded and displayed in the Analyst Portal. It is recommended to enable this option if you do not use custom console tasks, as it improves the overall performance of the portal.
ThrowErrorOnStaleObjectInTemplate This option is enabled by default. When enabled, the portal will suppress any error prompts related to Templates trying to load objects which do not exist in CMDB

Note: This option is not available on the Portal Settings UI, you must add this setting in the Appsettings.json file in the root directory of your ITSM Portal installation.
CreateRelatedWiTemplateOverrides When creating a related Workitem using custom console task this setting defines what data will persist in the newly created Workitem.

If this setting is set to “false” the data from the WorkItem will override those values of the Template

If set to “true” the data of the Template will persist and will therefore not be overwritten by the data of the WorkItem.

Note: This option is not available on the Portal Settings UI, you must add this setting in the Appsettings.json file in the root directory of your ITSM Portal installation.
RespectFilteringOnViewExport When set to true the view filters and sorting defined by the user will be respected during CSV Export

Analyst Portal Views

You can define which views from SCSM are available in the Analyst Portal. To publish views from Service Manager to the Analyst Portal you can follow the steps below:

  1. Browse to the Analyst Portal
  2. Click on your User -> Portal Settings
  3. In the Portal Settings move to the Published Views tab and cv check/uncheck the views you want to publish/unpublish
  4. When you are done click the Publish/Unpublish button in the top-right corner.
  5. Click OK, and then press Ctrl-F5 to clear your browser cache
Permissions in SCSM

Please note that SCSM overrules the settings for published and unpublished views. In other words, if you are publishing a view to the Analyst Portal, but the user accessing the portal is not in a user role that has access to the view in SCSM, the view will not be displayed.

Default Sorting of Analyst View

The Default sorting of Analyst Views can be configured in SCSM

Select the desired View in SCSM and execute the task “Edit View (Advanced)”

Go to the “Order” Section and click the […] Button of the Column you wish to sort. Then, select the desired Sort Direction and Index.

Please note that the “Sort as digits” option is not respected by the ITSM Portal.

Also, you may need to execute the “Reset View” task in the ITSM Portal for the changes to take effect.

Web Views

You can embed external websites inside the Analyst Portal by using Web Views. A Web View points to an URL of your choice and is exposed to your end users in the navigation section of the Analyst Portal. When the menu item is clicked, the target website will be loaded inside the portal (using a technology called IFRAME).

You can create web views in the SCSM Console. Use the Create Web View task to create a new web view in any folder under Work Items, Configuration Items, or a custom section in the SCSM Console.

Make sure that you analysts have permissions to access the view (see previous chapter Analyst Portal Views).

Run views under Application Pool account

Since ITSM Portal v.3.7 you can configure views to run under the Application Pool account to speed up loading times.

By configuring a view to run under the Application Pool account you are effectively bypassing the permissions you configured for this view

Follow these steps to configure a view to run under the Application Pool account:

  • Copy the script Update-ITSMPortalViewRunMode.ps1, which is in the Docs the ITSM portal Installation files, to your Management Server
  • Open PowerShell on your Management Server
  • Execute the Update script and specify either the Id, Name or DisplayName of the view you’d like to run under the Application pool account.

Example: 

> .\Update-ITSMPortalViewRunMode.ps1 -Name System.WorkItem.Incident.Escalated.View

It is recommended to use either Name or Id as using the DisplayName of the view may cause an unexpected behavior where another view will be updated instead of the specified one. This is a known limitation and has yet to be resolved.

Task Permissions

The Analyst Portal includes a series of tasks which your analysts can use to effectively work with the data in SCSM. These tasks are exposed on the right side of the portal:

You can show/hide tasks depending on the SCSM user roles your analysts are members of. To restrict access, go to the Analyst Portal Settings screen (see Analyst Portal Settings) and enable the Use custom permissions for tasks option. You will be presented a matrix showing all tasks in the rows, and all SCSM user roles in the columns. Tick the checkboxes as desired to show tasks for the desired user roles:

Your settings will be saved in the \wwwroot\Settings\ConsoleTasksPermissions.json file. To revert your settings are re-enable all tasks for all users, simply uncheck the Use custom permissions for tasks option and save your settings.

When you make use of this option, please do not forget to enable the desired tasks for the Administrator user role as well. If you forget to do so, your Administrators will not have any tasks available in the Analyst Portal.

Custom Console Tasks

You can define custom console tasks which execute locally on your analysts’ computers. Typical use cases for such tasks are:

  • Pinging the affected computer of a change request
  • Remote Desktop to the affected computer of an incident

You define such console tasks as an Administrator in the SCSM Console under Library – Tasks. Here is an example of a console task which executes Remote Desktop and connects to the affected computer of an incident:

More information on how to define tasks in SCSM can be found in the official Microsoft documentation:
https://docs.microsoft.com/en-us/system-center/scsm/troubleshoot-with-tasks?view=sc-sm-2016

Non-domain-joined and remote computers

Please note that this feature requires a transparent authentication between the client and the server. This means that the feature will only work for domain-joined computers with a transparent connection to the portal server (LAN or VPN).

Non-supported Task options

The settings Log in action log when this task is run and Show output when this task is run do not take effect when executing tasks from the Analyst Portal

Supported browsers

The console task is executed as a ClickOnce application. This type of applications is only supported by Edge and Internet Explorer. You can use Chrome by installing the ClickOnce for Google Chrome add-on:
https://chrome.google.com/webstore/detail/clickonce-for-google-chro/kekahkplibinaibelipdcikofmedafmb

Performance

Loading console tasks from SCSM comes causes additional data to be transferred between the clients and SCSM. If you are not using custom console tasks in the Analyst Portal, it is recommended to enable the setting Disable loading of SCSM console tasks. For more information, see Analyst Portal Settings chapter.

Search

The analyst portal allows your analysts to search work items using the search feature in the header of the portal.

The data which is queried and the criteria which is used when a search is submitted comes from a view in the SCSM Console: Administration – itnetX ITSM Portal – Global Search – Analyst Search

You can modify this view definition to change the data returned in the search results.

HTML Knowledge Base

SCSM includes a knowledge base out-of-the-box. However, the knowledge articles support the Rich Text Format only, which has limited support for advanced formatting, tables, etc.

The itnetX ITSM Portal extends the out-of-the-box Knowledge Base to allow HTML content to be used inside your Knowledge Articles. This includes the following features:

  • HTML content for the knowledge articles’ End User Content
  • HTML content for the knowledge articles’ Analyst Content
  • HTML editor in the Analyst Portal
  • HTML viewer in the End User Portal

If you want to make use of the HTML Knowledge Base, you have to be licensed for both the Analyst Portal. Editing HTML content using the SCSM console is not possible.

To use the HTML editor in the Analyst Portal, all you have to do is publish the Knowledge Article views to the portal (see Analyst Portal Views). You will find these views in the Library section.

When a user accesses a knowledge article in the end user portal, the portal will check if HTML content is available and then display it. If no HTML content is present, the RTF content will be displayed instead.

Custom Forms

itnetX ITSM Portal allows you to customize the forms of the various work items and configuration items in both the End User portal and the Analyst portal.

The following screen shots shows you the out-of-the-box incident form of the End User portal.

The following screen shots shows you the out-of-the-box incident form of the Analyst portal.

itnetX ITSM Portal allows you to perform the following customizations

  • Change existing forms
  • Add new forms for custom classes
  • Add new forms valid for specific users only

Each form in ITSM Portal is bound to a class in SCSM. If an instance of a class is opened for which no form exists, ITSM Portal will try to find a form for the class it inherits from. If no form is found, the portal will pick the next class in the inheritance chain, and so on.

Example: If you open a SCOM Incident in the portal (internal name: Microsoft.SystemCenter.WorkItem.SCOMIncident) for which no form exists, ITSM portal will use the form bound to System.WorkItem.Incident, because the SCOM Incident class inherits from this class.

The End User Portal includes simple forms for the abstract classes System.ConfigItem and System.WorkItem for fallback purposes.

Customizing forms requires knowledge of HTML and a very good understanding of SCSM. You will need to change or create type projections.

Changing existing forms

To change an existing form:

  1. Locate the form you want to customize End User portal forms can be found under \Areas\EndUser\Views\Forms Analyst portal forms can be found under \Areas\Analyst\Views\Forms
  2. Create a copy of the view file(s) and folder (if desired)
  3. Perform your customizations by modifying the .cshtml file(s), and save your changes
  4. Go to Portal Settings (see General Portal Settings), and then navigate to End User Form Settings or Analyst Form Settings.
  5. Add a new form by entering the internal name of the class in SCSM, the internal name of the type projection to use, and picking the form you just created. If your form does not show up, press Ctrl-F5 to refresh the browser cache.
  6. Save your form by clicking Save. If the class already has another form bound to it, you have to remove the form from the Form Settings list using the recycle bin icon.

Do not change the .cshtml files that ship with ITSM Portal directly. Always create copies thereof to make sure you do not lose your customizations during an upgrade.

The changes you make under End User Form Settings or Analyst Form Settings are stored in the EndUserForms.json and AnalystForms.json files in the \wwwroot\Settings directory. You can copy these files to other portal installations if you want to transfer form settings between environments.

Adding new forms

To add a new form, it is recommended you always start by copying an already existing form. Hence, please follow the instructions in the previous chapter Changing existing forms.

Constraining forms by AD groups or SCSM user roles

ITSM Portal allows you to define forms which are only valid for certain users. You can constrain access to such forms by either AD groups, or by SCSM user roles. This feature is useful if you have certain users which should only be able to edit a few attributes of a class. Create a custom form for these users, and then constrain it by an AD group or SCSM user role.

In the following example, members of the AD group LAB\PowerUsers will see the PowerUsers custom form for incidents, and members of the SCSM user role Advanced Operators will see the AdvancedOperators custom form. If the logged on user is not a member of either of the group or role, the default form will be used.

Modifying shared forms and partial forms (aka views and partial views)

Apart from the forms described previously in this chapter, you might also want to customize the shared views or partial views that ship with ITSM Portal. All views have the file extension .cshtml. For instance, if you want to make changes to the way the Home screen of the End User Portal looks like, you would need to work with the \Areas\EndUser\Views\Items\RequestView.cshtml file.

To customize a view or partial view:

  1. Create a custom theme as described in the Themes chapter.
  2. Create a copy of the .cshtml file you want to edit and rename it to [FileName]_[ThemeName].cshtml. For instance, if you want to change the RequestView.cshtml file, and the name of your custom theme is MyCompany, then create a copy of the RequestView.cshtml file with the name RequestView_MyCompany.cshtml.
  3. Apply the desired modifications and save the file.
  4. Restart IIS and then refresh the browser with Ctrl-F5. The portal will now load the custom view instead of the default one.

Using Custom Landing Pages

By using custom landing pages, you can override the page which is displayed as a start page to your portal users. This feature can be enabled in the portal settings for any of the two portals, or for both (see chapters End User Portal Settings and Analyst Portal Settings).

When custom landing page is enabled, the portal will load the following files as the start page:

  • End User Portal: \Areas\EndUser\Views\Items\LandingPage_custom.cshtml
  • Analyst Portal: \Areas\Analyst\Views\Analyst\LandingPage_custom.cshtml

You create these files, and then add your custom HTML content which you want to present to your end users.

If you want anonymous users to see different content than authenticated users, you can follow the example you find in the
\Areas\EndUser\Views\Items\LandingPage.cshtml file.

You can also use an already existing page as your start page. When you use the following code as the content of your LandingPage_custom.cshtml, the Service Catalog will be used as the start page in the end user portal:

@using itnetX.ITSMPortal.Areas.EndUser.Models
@inject ISdkService sdkService
@inject Microsoft.AspNetCore.Http.IHttpContextAccessor httpContextAccessor
@{
    ServiceCatalogHelper helper = new ServiceCatalogHelper(httpContextAccessor);
}

@if (sdkService.PortalSettings.EndUserPortalSettings.ServiceCatalogMode == ServiceCatalogModeEnum.OneClick)
{
    @Html.Partial("/Areas/EndUser/Views/ServiceCatalog/ServiceCatalogPlain.cshtml", helper)
}
else
{
    @Html.Partial("/Areas/EndUser/Views/ServiceCatalog/ServiceCatalog.cshtml", helper)
}

Themes

You can change the appearance of ITSM Portal by creating a custom theme. Typical customizations include changing the logo and altering colors. You will require some knowledge in CSS and HTML to be successful in working with themes.

Never make changes to the base theme. You will lose your changes if you upgrade your portal in the future.

To create a custom theme:

  1. Navigate to the \wwwroot\lib\ui\themes folder
  2. Create a copy of the base folder and all of its content
  3. Rename the copied folder to a custom name without whitespace and special characters
  4. Go to the portal main settings and change the theme (see General Portal Settings)

You can now change the pictures and other files in the copied location as desired.

We recommend you use your browser’s Developer Tools (press F12) to inspect the portal and to find out which CSS classes and pictures to modify.

Changing styles (CSS)

Most of the styles used by the portal are stored in the following CSS files (relative to your custom theme folder):

  • analyst\styles.min.css
  • enduser\styles.min.css

If you intend to make changes to CSS classes, we recommend not to change these files, but to create a file custom.css in the analyst or the enduser folder instead. Inside this file, you can add the same classes used in styles.css and override the desired attributes. By following this procedure, you can safely replace the styles.css files with new versions when you are upgrading the portal in the future.

LESS

If you only intend to change basic things, such as colors and fonts, you can make use of the LESS file that ships with ITSM Portal. You can modify the variables.less file and change the values of the variables.

This file can be found under:

  • \wwwroot\lib\ui\themes\base\less\enduser or
  • \wwwroot\lib\ui\themes\base\less\analyst

When you are done with your changes, you need to recompile the styles.less file. Copy both the variables.less and styles.less file to your computer and compile the styles.less file with a LESS compiler tool. We recommend you use WinLess: http://winless.org/

Make sure to minify the file and rename the compiled file to styles.min.css. The file can then be copied in the corresponding folder of your theme, replacing the existing file.

Localization

The itnetX ITSM Portal uses the language defined as Default User Interface Language (see General Portal Settings) as the default language. The actual language presented to users is determined using the following set of rules in the following order:

  1. Cookies. The cookies contain information about the previously selected or auto-detected language.
  2. Language from user’s browser settings
  3. ITSM Portal default language

The language will be selected only if it is available and loaded in the itnetX ITSM Portal, otherwise it will default to the ITSM Portal default language.

Removing existing languages

You can remove languages from the language picker and force your users to use one or a few predefined languages.

  1. Configure the Default User Interface Language (see General Portal Settings)
  2. Navigate to the \Resources folder
  3. Delete all *.%code%.resx files, leaving only the ones in the language(s) you want to be available
  4. Restart IIS and refresh your browser cache by pressing Ctrl-F5

Changing existing languages

To change specific strings in an existing language:

  1. Navigate to the \Resources folder
  2. Create a copy of the GlobalStrings.%code%.resx file for edit, where %code% is the language code, and change its name to GlobalStrings_custom.%code%.resx
  3. Locate the required string
  4. Change the string inside of the <value> element
  5. Save the file
  6. Restart IIS and refresh your browser cache by pressing Ctrl-F5

Adding custom languages

To add a custom language:

  1. Navigate to the \Resources folder
  2. Create a copy of the GlobalStrings.en.resx file and name it GlobalStrings.%code&.resx, where %code% is the language code of the language to be added
  3. Change all strings inside of the <value> elements
  4. Save the file
  5. Restart IIS and refresh your browser cache by pressing Ctrl-F5

Please note that the names of folders, views and view columns are defined in the management pack. If you want the views that ship with the End User Portal to be displayed in a custom language, you have to add a LanguagePack to the itnetX.ITSMPortal.EndUser.Configuration management pack.

Please share your custom language files with us to allow us to include them in future releases. You can send the files to support@itnetx.ch. Thank you!

Working with custom strings

When you make changes to the forms and views in the portal, you might come into the situation where you want to use an existing display string from the resource files, or you need to add new localized strings.

To reference an already existing resource string from your CSHTML code, you can use the @GlobalLocalizer directive. Here is an example which uses the resource string named AssignedTo to display as the header of a user picker:

<itx-userpickercontrol property="DisplayName" alias="AssignedUser" header="@GlobalLocalizer["AssignedTo"]" use-global-operator="true" columns-span="4" required="false" />

In case you want to create new resource strings, it is recommended to add custom RESX files to the \Resources directory of the portal. For instance, you can add a file MyCustomResources.en.resx and add the resource strings you need to this file. The portal will always load and merge all RESX files of the current language of the user.

Cultures

The culture defines the way the ITSM Portal is formatting numbers, dates, and times. The culture will always follow the user’s language of the browser. If the user’s browser is configured in a language which is not supported by ITSM Portal, the Default Culture (see General Portal Settings) will be used.

If you want to force a specific culture for all users:

  1. Configure the Default Culture (see General Portal Settings)
  2. Navigate to the \wwwroot\lib\external\globalize\cldrdata\main folder
  3. Delete all folder and files, leaving only the culture you want to be available
  4. Restart IIS and refresh your browser cache by pressing Ctrl-F5