Software Product Docs

Installation Guide

Requirements

It is required that you install Operaio ITSM Portal on a Service Manager management server. You can deploy any number of the servers with the Portal, but all of them must have management server installed.

Installing Operaio ITSM Portal on a server that is not a SCSM management server is not supported

Using Kerberos (Negotiate) for authentication requires additional configuration for Kerberos, delegation, and SPN records. Please contact customer@operaio.ch

Please make sure that you meet the following requirements:

  • Server Hardware Requirements
    • 4-core 2.66 GHz CPU
    • 16GB RAM
    • 600MB hard drive space
  • Operating System Requirements
    • Windows Server 2016
    • Windows Server 2022
  • Service Manager Requirements
    • System Center 2016 Service Manager
    • System Center 2022 Service Manager
    • System Center 2025 Service Manager
  • Browser Requirements
    • Microsoft Edge
    • Mozilla Firefox 42 and later
    • Google Chrome 46 and later

New Installation

Please execute the following tasks on the portal server as an administrator:

  1. Make sure you are using the latest version of Operaio ITSM Portal. You can download it from our Operaio Software Catalog
  2. Install IIS with all required features by using the following command from an elevated PowerShell command prompt (Run as Administrator):
    Add-WindowsFeature NET-Framework-45-Core,NET-Framework-45-ASPNET,Web-Server,Web-Http-Redirect,Web-Http-Tracing,Web-Log-Libraries,Web-Windows-Auth,Web-Net-Ext,Web-Asp-Net45,Web-Mgmt-Console
    If you already have IIS installed, you should still execute the above script to ensure that any possibly missing components are added to the server
  3. Make sure you have the .NET Framework Runtime 4.8 or later installed.
    You can download an offline installer from the following URL: https://dotnet.microsoft.com/en-us/download/dotnet-framework/net48
  4. Download and install the Microsoft Visual C++ 2015 Redistributable:
    https://go.microsoft.com/fwlink/?LinkID=615460
  5. Download and install the .Net Core 8.0 Windows Server Hosting bundle. Please choose latest available version of 8.0.xx, then under ASP.NET Core Runtime choose Windows and then Hosting Bundle:
    https://dotnet.microsoft.com/en-us/download/dotnet/8.0
  6. Restart IIS by using the following command from an elevated command prompt: iisreset
  7. Download the latest version of Operaio Advanced View Editor from our Operaio Software Catalog and unzip it to a temporary location on the portal server.
  8. Download the latest version of Operaio Checklist Activity from our Operaio Software Catalog and unzip it to a temporary location on the portal server.
  9. Download and install the SMLets:
    https://github.com/Microsoft/smlets
  10. Read the Release Notes

Please perform the following tasks as an SCSM Administrator to install Operaio ITSM Portal v6:

  1. Create a subdirectory named ITSMPortalV6 in the C:\inetpub folder
  2. Unblock the \Portal\ITSMPortal_v6_Installer.zip. If this option is not available in the File Properties dialog, you can skip this step.
  3. Extract the content of \Portal\ITSMPortal_v6_Installer.zip to the folder created in step 1.
  4. Open Internet Information Services (IIS) Manager
  5. If you do not host any other websites on this server, stop the Default Web Site
  6. Create a new site by clicking on Add Website…
  7. Enter ITSMPortalV6.Front as the site name and choose the folder C:\inetpub\ITSMPortalV6\ITSMPortal.Front as the physical path.

    Choose appropriate binding options so as to not run into a conflict with an already existing website. If this is the only website you intend to be hosting on this server, the easiest way to configure binding is to use http as the Type, All Unassigned as the IP address, and 80 as the Port. Under Host name, you can enter a custom DNS name for your website (if you have one). If you want to use https, you must have a SSL certificate available on the web server.
    If you see a message about duplicate binding, click Yes
  8. Navigate to Application Pools, select the pool of your newly created site and open the Basic Settings
  9. Change the .Net CLR Version to No Managed Code
  10. Open the Advanced Settings of the Application Pool and change the Identity to the SCSM Service Account by selecting Custom account and entering the user name in the format [Domain]\[User Name] and the password.
  11. Navigate to Sites, select the newly created site ITSMPortalV6.Front, double-click Authentication and make sure that Anonymous Authentication is Disabled and Windows Authentication is Enabled
  12. Navigate to Sites, select the newly created site ITSMPortalV6.Front, double-click Configuration Editor and select the Section “system.webServer/security/authentication/windowsAuthentication”. In this configuration, set authPersistSingleRequest to true
  13. Create a new site by clicking on Add Website…
  14. Enter ITSMPortalV6.API as the site name and choose the folder C:\inetpub\ITSMPortalV6\ITSMPortal.API as the physical path.

    Choose appropriate binding options so as to not run into a conflict with an already existing website. This site can be configured to listen localhost only, you can choose any available port for binding.
  15. Navigate to Application Pools, select the pool of your newly created site and open the Basic Settings
  16. Change the .Net CLR Version to v4.0.xxxxxx
  17. Open the Advanced Settings of the Application Pool and change the Identity to the SCSM Service Account by selecting Custom account and entering the user name in the format [Domain]\[User Name] and the password.
  18. Navigate to Sites, select the newly created site ITSMPortalV6.API, double-click Authentication and make sure that Anonymous Authentication is Enabled and Windows Authentication is Enabled
  19. Navigate to Sites, select the newly created site ITSMPortalV6.API, double-click Configuration Editor and select the Section “system.webServer/security/authentication/windowsAuthentication”. In this configuration, set authPersistSingleRequest to true
  20. Open file C:\inetpub\ITSMPortalV6\ITSMPortal.Front\appsettings.json and update the ApiUrl parameter with the port set on step 14.
  21. Import the following management packs in given order into your SCSM environment. You can either find them in the files you downloaded or in the \MP directory of the ITSM Portal installation media:
    - itnetX.AdvancedViewEditor.2016.mpb (for SCSM 2016 and above)
    - itnetX.ChecklistActivity.2016.mpb (for SCSM 2016 and above)
    - The licensing library
    - Your license management pack
    - itnetX.ITSMPortal.SupportingObjects.2016.mpb (for SCSM 2016 and above)
    - itnetX.ITSMPortal.Analyst.mpb
    - Syliance.ITSMPortalSupporting.Objects.xml
    - itnetX.ITSMPortal.Analyst.Configuration.xml
    - itnetX.ITSMPortal.EndUser.Configuration.xml
    - itnetX.ITSMPortalSupporting.Groups.xml
    - itnetX.ITSMPortalSupporting.TasksConfig.xml
    - if you are using the Operaio Productivity Pack, import itnetX.ITSMPortal.Analyst.ProductivityPack.xml
  22. Restart the SCSM Console
  23. Change the permissions for the folder C:\inetpub\ITSMPortalV6\ITSMPortal.API\Logs and C:\inetpub\ITSMPortalV6\ITSMPortal.Front\Logs to write, read and modify for Everyone
  24. Change the permissions for the folder C:\inetpub\ITSMPortalV6\ITSMPortal.API\App_Data\upload to write, read and modify for Everyone
  25. Browse to the URL and start using the Operaio ITSM Portal. Please refer to the Administration Guide for information about configuring and using the portal

Reduce startup time

The default configuration in IIS will terminate the ITSM Portal application pool after being idle for more than 20 minutes. The first user to open the portal after it has been terminated may experience a loading time around 30 seconds, depending on your servers performance.
To reduce this startup time change the following settings in the advanced settings of your ITSM Portal application pools:
Start Mode: AlwaysRunning
 Idle Time-out Action: Suspend

Upgrading an existing installation

You can upgrade to the ITSM Portal from following versions: 1. Any version of ITSM Portal v4 2. Any version of ITSM Portal v5 3. Any version of ITSM Portal v6 (minor version upgrade)

IMPORTANT
Direct upgrade from ITSM Portal v2 and below to ITSM Portal v6 is not supported, please upgrade this version to v4 or v5 before move to v6

Upgrade from ITSM Portal v6 (minor version upgrade)

If you have already installed an earlier version of the ITSM Portal V6, please follow these steps to update your installation:

Customizations

Your customizations of ITSM Portal will remain untouched in case you have followed the recommendations of the Admin Guide.

Custom themes will remain untouched by the upgrade. If you have done modifications to the CSS files, you must manually merge your changes with the new CSS files shipped with the base theme. If you have only modified the LESS files, you will need to recompile them.

Custom forms will remain untouched by the upgrade. It could be that the new version of the portal will bring changes to the out-of-the-box forms. If you have altered these forms, it is recommended that you manually merge your changes with the cshtml files shipped with the new version.

Should you have altered the out-of-the-box source files, your customizations will be overwritten.

Upgrading from ITSM Portal V3 or V4 or V5

The ITSM Portal V6 introduces a complete facelift of the entire Portal including

  • Complete new Stylesheets
  • Mobile friendly forms
  • New Grid Control (for Views, Query Results Prompts, External Query Prompts etc.)

The New Grid Control is used in the Analyst Portal as well which means you might need to update the Analyst Part of your custom theme.

The portal now using two web application: one for Frontend (based on .net core 8) and one for API to communicate with the Service Manager SDK (based on .NET Framework 4.8).

High level steps

Based on changes in the Portal, we can offer two different ways to upgrade:

  1. Delete all content of the Portal and install a new version while keeping the old portal's settings. This is the most simple and accurate way to upgrade the portal and take advantage of the new improvements. We call this procedure Replace Upgrade
  2. Manually upgrade each part of the portal. The manual upgrade of each part will not be covered in detail in this document. Please contact our support team customer@operaio.ch in case you need to perform the manual upgrade.

Both ways have the following common steps:

  1. Make a backup of the current ITSM Portal installation folder.
  2. Install all pre-requirements listed in this guide
  3. Migrate your styling schema as usual. The v6 contains a lot of style improvements for entire Portal, so please contact our support team customer@operaio.ch if you need help.
  4. Perform the upgrade using the chosen procedure
  5. Import new management packs to SCSM

Note: you can perform side-by-side upgrade of the portal on the same server, just create copy of the v3 site with same settings and bind it on another port

Waring: if you did modification of any default .cshtml files in the portal you have to move those modification to _custom.cshtml file see Customization Guide for more details. _Modification of default .cshtml files are not supported in any way_. Please contact our support team customer@operaio.ch in case if you need assistance.

Important Note: Any customizations of the Portal must be re-developed. Any _custom.cshtml files intended for the both, EndUser and Analyst Portal will no longer work correctly due to the Portal facelift introduced with the ITSM Portal V6. Any custom styles for the End User Portal in your custom theme must be re-developed as well as most, if not all existing stylesheets will no longer work correctly with the End User Portal facelift.

Upgrade custom plugins

The custom plugins (*.ITSMPortal.Plugin.dll) can be used to extend back-end functionality of the Portal. To upgrade such plugins you must re-build them with new references to asp.net core 2.2.0 packages.

IMPORTANT
Current version of the ITSMPortal V6 does not support plugins from the old version and do not have support for the plugin system. We plan to introduce this in the future minor release. Please contact our support team customer@operaio.ch for more information.

Upgrading from a previous version of Operaio Advanced View Editor

You must upgrade to Operaio Advanced View Editor 3.x for ITSM Portal v3 to work. If you are currently using a version older than 2.0.1561.79, or if you are using any version of SCSMSolutions Advanced View Editor, then you must update your views after the upgrade. Please read the Operaio Advanced View Editor for SCSM - Release Notes for more information on upgrading to the latest version. This document can be found in the ZIP file you downloaded in step 7 of the previous chapter.

Updating Unsealed Management Packs

Depending on what type of customizations you already performed in the portal, you will have to merge your changes with the latest version of the management pack. Please read through and follow the instructions in the following two chapters if applicable.

Upgrading the Analyst Configuration management pack

Have you already published or unpublished any views in the Analyst Portal? If you have not done any changes to the published views, or if you are okay to revert to the standard and re-publish your views manually (recommended), then please import the itnetX.ITSMPortal.Analyst.Configuration.xml management pack into your environment.

If you have changed the publication of views in the Analyst Portal, and you want to keep your changes, you must merge your changes with the latest version of the management pack:

  1. Copy the \MP\itnetX.ITSMPortal.Analyst.Configuration.xml file which ships with the ITSM Portal installer to a temporary directory on a SCSM management server
  2. Run the script Upgrade-itnetXAnalystMP.ps1 found in the Docs folder in the \Portal\ITSMPortal_v3_Installer.zip archive.
  3. Provide the full path to the file itnetX.ITSMPortal.Analyst.Configuration.xml from the first step.
  4. When the script is finished, import the itnetX.ITSMPortal.Analyst.Configuration.xml from the location of the first step.

Upgrading the End User Configuration management pack

Have you already changed the views that appear in the End User portal home page, the Requests section, or the Activities section, or have you added any custom views or sections? If you have not done any changes to the views, or if you are okay to revert to the standard (recommended), then please import the itnetX.ITSMPortal.EndUser.Configuration.xml management pack into your environment.

If you have changed views or folders in the End User Portal, and you want to keep your changes, you have to merge your changes with the latest version of the management pack:

  1. Copy the \MP\itnetX.ITSMPortal.EndUser.Configuration.xml file which ships with the ITSM Portal installer to a temporary directory on a SCSM management server
  2. Run the script Upgrade-itnetXEndUserMP.ps1 found in the Docs folder in the \Portal\ITSMPortal_v3_Installer.zip archive.
  3. Provide the full path to the file itnetX.ITSMPortal.EndUser.Configuration.xml from the first step.
  4. When the script is finished, import the itnetX.ITSMPortal.EndUser.Configuration.xml from the location of the first step

Updating the Portal

It's highly recommended to do the side-by-side upgrade.

  1. Try to import all of the following management packs in given order. Management Packs which do not have a newer version than the one you have currently installed can be skipped.
    a. itnetX.AdvancedViewEditor.2016.mpb (for SCSM 2016 and above)
    b. itnetX.ChecklistActivity.2016.mpb (for SCSM 2016 and above)
    c. itnetX.ITSMPortal.SupportingObjects.2016.mpb (for SCSM 2016 and above)
    d. itnetX.ITSMPortal.Analyst.mpb
    e. Syliance.ITSMPortalSupporting.Objects.xml
    f. itnetX.ITSMPortalSupporting.Groups.xml
    g. itnetX.ITSMPortalSupporting.TasksConfig.xml
    h. if you are using the Operaio Productivity Pack, import itnetX.ITSMPortal.Analyst.ProductivityPack.xml
  2. Follow the New installation section of this document, using the different from your current portal's port numbers.
  3. Copy appsettings.json from root of your old portal's folder to the Portal.API folder.
  4. Copy all files from %OLD_PORTAL%\wwwroot\Settings to %NEW_PORTAL%\Portal.API\Settings
  5. If you have custom JS code, copy all .js files from %OLD_PORTAL%\wwwroot\lib\custom to the %NEW_PORTAL%\Portal.Front\wwwroot\lib\custom*
  6. If you have customization fo the forms, please copy all _custom.cshtml files to the %NEW_PORTAL%\Portal.Front keeping related paths. Additionally, you must made following changes on your custom chtml files, if applied:
  7. Replace sdkService.GlobalLocalizer to GlobalLocalizer
  8. Replace sdkService.PortalSettings to portalSettingsAccessor.CurrentValue
  9. Replace @Html.Partial( with @await Html.PartialAsync(

You can use script Upgrade-Forms.ps1 script located in the Portal.API\Docs folder to automate this step.

If you have very custom forms with the Razor markup then please follow common guide how to migrate from .net core 2 to .net core 8 and see Additional information section below. 8. Open browser using new URL and unsure that new portal works. 9. Change port\URL for the old portal in IIS and assign port\URL to the new portal. 10. Open browser using new URL and unsure that new portal works on the main URL.

Post-Upgrade Tasks

Follow these steps after each upgrade from any version of ITSM Portal:

  • CSS files could have changed. If you have done modifications to the CSS files, you must manually merge your changes with the new CSS files shipped with the base theme. If you have only modified the LESS files, you will need to recompile them
  • Forms (cshtml) files could have changed. If you have altered out-of-the-box forms, it is recommended that you manually merge your changes with the cshtml files shipped with the new version.

Licensing

Your license is delivered in the form of two management packs:

  • The licensing library: itnetX.SCSM.Licensing.Library.mpb
  • The actual license:
    • Operaio.SCSM.ITSMPortalAnalystv3.LicenseInfo.mp if you own the Analyst Portal
    • Operaio.SCSM.ITSMPortalEndUserv3.LicenseInfo.mp if you own the End User Portal
    • Operaio.SCSM.ITSMPortalSuitev3.LicenseInfo.mp if you own the ITSM Portal Suite

You must import the licensing library management pack and one of the license management packs for the portal to work. If you are upgrading from a trial to a production license, you need to first delete the old license management pack, and then import the new one. You do not need to replace the licensing library management pack.

Free Edition

The End User Portal is also available as a free edition with reduced functionality If you do not install a license management pack, or if your license is invalid or expired, the end user portal will run in Free Edition. The Analyst Portal will not work without a license.

Remove Console Tasks management pack

If you have previously imported the Operaio.ITSMPortalSupporting.TasksConfig.xml management pack, you must remove it again from SCSM, otherwise you will not be able to create and edit request offerings that work with the free edition of the End User Portal. The display name of the management pack as displayed in the SCSM Console is Operaio ITSM Portal Console Tasks Configuration.

docs.microsoft.com - web.config file
docs.microsoft.com - IIS modules with ASP.NET Core

Additional information

This section will be helpful if you have deep code-based customization of the portal.

List of forms (cshtml) that was changed in compare of v5

Forms are located in the Portal.Front subfolder in the new portal

  • Areas\_ViewImports.cshtml
  • Areas\Admin\Views\Admin\FormsList.cshtml
  • Areas\Admin\Views\Admin\LogFiles.cshtml
  • Areas\Admin\Views\Admin\Settings.cshtml
  • Areas\Admin\Views\Admin\TaskPermissionsView.cshtml
  • Areas\Admin\Views\Shared_AdminHeader.cshtml
  • Areas\Admin\Views\Shared_AdminNavigation.cshtml
  • Areas\Admin\Views\Shared_LayoutAdmin.cshtml
  • Areas\Analyst\Views_ViewImports.cshtml
  • Areas\Analyst\Views\Analyst_AnalystMobileNavigation.cshtml (ADDED)
  • Areas\Analyst\Views\GlobalSearch.WorkItems.cshtml
  • Areas\Analyst\Views\Index.cshtml
  • Areas\Analyst\Views\Controls\instancePickerControl.cshtmlAreas\Analyst\Views\Controls\instancePickerControl.cshtml
  • Areas\Analyst\Views\Forms\ActionLogTemplate.cshtml
  • Areas\Analyst\Views\Forms\WI_ActivitiesTab.cshtml
  • Areas\Analyst\Views\Forms\WI_FormFillingActivity\WI_FormFillingActivity_GeneralTab.cshtml
  • Areas\Analyst\Views\Forms\WI_Incident\WI_TroubleTicket_ActivitiesTab.cshtml
  • Areas\Analyst\Views\Forms\WI_UpdateObjectActivity\WI_UpdateObjectActivity_GeneralTab.cshtml
  • Areas\Analyst\Views\Shared\_AnalystHeader.cshtml
  • Areas\Analyst\Views\Shared\_AnalystMainMenu.cshtml
  • Areas\Analyst\Views\Shared\_AnalystNavigation.cshtml
  • Areas\Analyst\Views\Shared\_LayoutAnalyst.cshtml
  • Areas\Analyst\Views\Shared\_LayoutForms.cshtml
  • Areas\Analyst\Views\Shared\_LayoutPopupForms.cshtml
  • Areas\Analyst\Views\Shared\_TaskBar.cshtml
  • Areas\Analyst\Views\View\GridViewType.cshtml
  • Areas\Analyst\Views\View\itnetx.TreeViewViewType.cshtml
  • Areas\Analyst\Views\View\itnetx.WorkItemCalendarViewType.cshtml
  • Areas\Analyst\Views\View\Operaio.KanbanViewType.cshtml
  • Areas\Analyst\Views\View\WebViewType.cshtml
  • Areas\Analyst\Views\View\_ViewImports.cshtml
  • Areas\EndUser\Views\Controls\attachmentsgridControl.cshtml
  • Areas\EndUser\Views\Forms\ActionLogTemplate.cshtml
  • Areas\EndUser\Views\Forms\Activities.cshtml
  • Areas\EndUser\Views\Forms\GenericForm.cshtml
  • Areas\EndUser\Views\Forms\WI_ChangeRequest\WI_ChangeRequest_Form_Desktop.cshtml
  • Areas\EndUser\Views\Forms\WI_ChangeRequest\WI_ChangeRequest_Form_Mobile.cshtml
  • Areas\EndUser\Views\Forms\WI_CheckListActivity\WI_CheckListActivity_DefaultForm.cshtml
  • Areas\EndUser\Views\Forms\WI_Incident\WI_Incident_DefaultForm.cshtml
  • Areas\EndUser\Views\Forms\WI_Incident\WI_Incident_Form_Desktop.cshtml
  • Areas\EndUser\Views\Forms\WI_Incident\WI_Incident_Form_Mobile.cshtml
  • Areas\EndUser\Views\Forms\WI_ManualActivity\WI_ManualActivity_DefaultForm.cshtml
  • Areas\EndUser\Views\Forms\WI_ReviewActivity\WI_ReviewActivity_DefaultForm.cshtml
  • Areas\EndUser\Views\Forms\WI_ReviewActivity\WI_ReviewActivity_Form_Desktop.cshtml
  • Areas\EndUser\Views\Forms\WI_ReviewActivity\WI_ReviewActivity_Form_Mobile.cshtml
  • Areas\EndUser\Views\Forms\WI_ServiceRequest\WI_ServiceRequest_DefaultForm.cshtml
  • Areas\EndUser\Views\Forms\WI_ServiceRequest\WI_ServiceRequest_Form_Desktop.cshtml
  • Areas\EndUser\Views\Forms\WI_ServiceRequest\WI_ServiceRequest_Form_Mobile.cshtml
  • Areas\EndUser\Views\Forms\WI_WorkItem\WI_WorkItem_Form_Desktop.cshtml
  • Areas\EndUser\Views\Forms\WI_WorkItem\WI_WorkItem_Form_Mobile.cshtml
  • Areas\EndUser\Views\Items\GlobalSearch.cshtml
  • Areas\EndUser\Views\Items\Home.cshtml
  • Areas\EndUser\Views\Items\LandingPage.cshtml
  • Areas\EndUser\Views\Items\RequestFilters.cshtml
  • Areas\EndUser\Views\Items\RequestFolders.cshtml
  • Areas\EndUser\Views\Items\RequestView.cshtml
  • Areas\EndUser\Views\Items\WebView.cshtml
  • Areas\EndUser\Views\KB\KBHome.cshtml
  • Areas\EndUser\Views\ServiceCatalog\_fieldInstancePicker.cshtml
  • Areas\EndUser\Views\ServiceCatalog\CreateRequest.cshtml
  • Areas\EndUser\Views\ServiceCatalog\ServiceCatalog.cshtml
  • Areas\EndUser\Views\ServiceCatalog\Submitted.cshtml
  • Areas\EndUser\Views\ServiceCatalog\SummaryPage.cshtml
  • Areas\EndUser\Views\Shared_EndUserHeader.cshtml
  • Areas\EndUser\Views\Shared_EndUserMenu.cshtml
  • Areas\EndUser\Views\Shared_EndUserNavigation.cshtml
  • Areas\EndUser\Views\Shared_EndUserSidebar.cshtml
  • Areas\EndUser\Views\Shared_LanguagePicker.cshtml
  • Areas\EndUser\Views\Shared_LayoutEndUser.cshtml

List of breaking changes in forms (cshtml files) in compare of v5

  • await Html.PartialAsync must be used instead Html.Patrial
  • sdkInstance.GlobalLocalizaer was removed, you must use global GlobalLocalizer
  • Portal's settings in the Front was changed from IOptions to IOptionsMonitor, so you must use .CurrentValue instead .Value
  • ISdkService namespace was changed from itnetX.ITSMPortal.Models.SDK to Operaio.ITSMPortal.Services
  • All methods of ISdkService are awaitable
  • Property ISdkSerice.IsAnonymous was replaces with awaitable method ISdkSerice.IsAnonymous()