Software Product Docs

Installation Guide

Requirements

It is recommended that you install Operaio ITSM Portal on a Service Manager management server.
Even for larger deployments where you require to deploy separate server(s) for ITSM Portal, it is recommended to install the Service Manager management server role on the ITSM Portal servers.
This recommendation also applies if you are deploying ITSM Portal to a NLB cluster.

Installing Operaio ITSM Portal on a server that is not a SCSM management server is not recommended and 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
    • 250MB hard drive space
  • Operating System Requirements
    • Windows Server 2012 R2
    • Windows Server 2016
  • Service Manager Requirements
    • System Center 2012 R2 Service Manager
    • System Center 2016 Service Manager
  • Browser Requirements
    • Internet Explorer 10
    • Internet Explorer 11
    • 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 ITMS 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 4.6.1 or later installed.
    You can download an offline installer from the following URL: https://www.microsoft.com/en-us/download/details.aspx?id=53344
    On Windows Server 2016, .NET Framework 4.6 is already included.
  4. Download and install the Microsoft Visual C++ 2015 Redistributable:
    https://go.microsoft.com/fwlink/?LinkID=615460
  5. Download and install the .Net Core Windows Server Hosting bundle:
    https://dotnet.microsoft.com/download/dotnet/thank-you/runtime-aspnetcore-2.2.8-windows-hosting-bundle-installer
  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 v3:

  1. Create a subdirectory named ITSMPortalV4 in the C:\inetpub folder
  2. Unblock the \Portal\ITSMPortal_v3_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_v3_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 ITSMPortalV4 as the site name and choose the folder from step 1 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 ITSMPortalV4, 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 ITSMPortalV4, double-click Configuration Editor and select the Section “system.webServer/security/authentication/windowsAuthentication”. In this configuration, set authPersistSingleRequest to true
  13. 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.2012.mpb (for SCSM 2012)
    - itnetX.AdvancedViewEditor.2016.mpb (for SCSM 2016)
    - itnetX.ChecklistActivity.2012.mpb (for SCSM 2012)
    - itnetX.ChecklistActivity.2016.mpb (for SCSM 2016)
    - The licensing library
    - Your license management pack
    - itnetX.ITSMPortal.SupportingObjects.2012.mpb (for SCSM 2012)
    - itnetX.ITSMPortal.SupportingObjects.2016.mpb (for SCSM 2016)
    - 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 itnetX Productivity Pack, import itnetX.ITSMPortal.Analyst.ProductivityPack.xml
  14. Restart the SCSM Console
  15. Change the permissions for the folder C:\inetpub\ITSMPortalV4\Logs to write, read and modify for Everyone
  16. Change the permissions for the folder C:\inetpub\ITSMPortalV4\wwwroot\App_Data\upload to write, read and modify for Everyone
  17. 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 loadingtime 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 pool:
Start Mode: AlwaysRunning
 Idle Time-out Action: Suspend

Upgrading an existing installation

If you have already installed an earlier version of the ITSM Portal V4, 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.

Before you begin

Please read the following chapters carefully if you are already using either Operaio ITSM Portal v2 or Operaio Advanced View Editor.

Migrating your Request Offerings

In case you are or were using a previous version of ITSM Portal (version 2.0.4.5 or older), you must migrate your Request Offerings for them to work with ITSM Portal v3.

  1. Run PowerShell as an Administrator
  2. Execute the Migrate-itnetXPortalExtensions.ps1 script from the \Docs directory of the portal

If you are adding more request offerings created with ITSM Portal v1 or v2 by importing management packs at a later stage, please run this script again.

Removing and unregistering Request Offering Extensions from Management Packs

Once you have migrated the request offerings, please verify that the request offerings work as expected in the portal. Then, you can remove the request offering extensions from the management packs by executing the Remove-itnetXMPExtensions.ps1 script following from the \Docs directory of the portal v3.

After you have removed the Request Offering Extensions from the management packs, you should unregister the management pack extension of the old ITSM Portal. To do so, you must execute the following script as an administrator: \SylianceITSMPortal\bin\unregisterExtension.ps1

These two scripts will only work when you run them from a server with ITSM Portal version 2.0.4.5 or older installed. Please verify the path to the Syliance.ITSMPortal.Shared.dll file in the scripts before you run them.

Upgrading from ITSM Portal V3 to V4

The ITSM Portal V4 brings the following improvements that require your attention during the upgrade process:

  • Migration to .net core 2.2. This brings performance and stability improvements.
  • The new layout for the Enduser Portal which improves user experience by reducing "page-blinking" during navigation.
  • Re-strucured Admin Section's Portal file locations

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 the ASP.NET Core Runtime 2.2.x Hosting Bundle. You should install the latest available version of 2.2
  3. Migrate your styling schema as usual. The v4 contains a lot of style improvements for End User 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 managment 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.

Upgrade custom plugins

The custom pluging (*.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

Previous versions of Operaio ITSM Portal stored custom Request Offering settings in your management packs. Due to a bug introduced in Service Manager 2016, these settings can no longer be stored in management packs, but must be stored in your CMDB instead.

If you are currently using Operaio ITSM Portal version 2.0.4.5 or older, changes you make to your Request Offerings will only be available in the new Portal v3 after the upgrade.

You can check the version of your ITSM Portal by checking the version of the Operaio ITSM Portal Supporting Library management pack.

You must migrate your request offerings from the management pack to the CMDB after the installation of ITSM Portal v3. A script is provided for this task and is explained in Migrating your Request Offerings

If you want both the old v2.x and the new v3 portal to work simultaneously, you first have to upgrade Operaio ITSM Portal v2 to version 2.1.x.x, and then install ITSM Portal v3 as a separate web site. This will allow you to use both portals at the same time.

Upgrading from a previous version of Opraio 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

  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.2012.mpb (for SCSM 2012)
    b. itnetX.AdvancedViewEditor.2016.mpb (for SCSM 2016)
    c. itnetX.ChecklistActivity.2012.mpb (for SCSM 2012)
    d. itnetX.ChecklistActivity.2016.mpb (for SCSM 2016)
    e. itnetX.ITSMPortal.SupportingObjects.2012.mpb (for SCSM 2012)
    f. itnetX.ITSMPortal.SupportingObjects.2016.mpb (for SCSM 2016)
    g. itnetX.ITSMPortal.Analyst.mpb
    h. Syliance.ITSMPortalSupporting.Objects.xml
    i. itnetX.ITSMPortalSupporting.Groups.xml
    j. itnetX.ITSMPortalSupporting.TasksConfig.xml
    k. if you are using the Operaio Productivity Pack, import itnetX.ITSMPortal.Analyst.ProductivityPack.xml
  2. If you are upgrading from a BETA version, import all management packs listed under step 13 in the previous chapter. Also, make sure you try to import already existing management packs, as the version might have changed. You also need to re-import the unsealed management packs for the portal to work
  3. Stop IIS by executing net stop w3svc from an elevated command prompt.
  4. Create a backup of the C:\inetpub\ITSMPortalV4 directory
  5. IMPORTANT: Delete the refs folder located in C:\inetpub\ITSMPortalV4 and all of its content
  6. Unblock the \Portal\ITSMPortal_v3_Installer.zip and extract the content to a temporary directory.
  7. Remove the following files from the temporary directory:
    a. \appsettings.json
    b. \web.config
    c. \wwwroot\Settings\AnalystForms.json
    d. \wwwroot\Settings\ConsoleTasksPermissions.json
    e. \wwwroot\Settings\EndUserForms.json
  8. Copy all files to the C:\inetpub\ITSMPortalV4 directory, overwriting already existing files with the new ones.
  9. Restart IIS by executing iisreset from an elevated command prompt.
  10. In your browser, go to the portal, then clear the cache by pressing Ctrl-F5
Replace upgrade

This is most simple way to upgrade the portal and keep all settings. To perform replace upgrade:

  1. Stop IIS
  2. Remove all files from the ITSMPortal installation folder (c:\inetpub\itsmportalV3 by default)
  3. Copy new files from itsmportalv4.zip to the same folder
  4. Copy following files from the v3 backup if they are exist:
    a. appsettings.json
    b. \wwwroot\lib\custom*.js
    c. \wwwroot\lib\ui\themes\%your_custom_theme%
    d. \wwwroot\lib\ui\themes\base\customization.css
    e. \wwwroot\Settings*.
    f.     _custom.cshtml in all child folders
  5. Compare your custom cshtml files with default, perform changes if needed
  6. Start IIS

Post-Upgrade Tasks

Upgrading from any version

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

  • 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.
Upgrading from a version older than v3.2

Follow these steps if you are upgrading from a version older than v3.2.

Analyst Portal Forms

You must manually add the following forms to the portal, following the instructions found in chapter 5.1, steps 5-6, of the Administration Guide.

Knowledge Article

Target Class: System.Knowledge.Article
Type Projection: Operaio.ITSMPortal.Analyst.KnowledgeArticle.Projection
Default Form: CI_KBArticle\CI_KBArticle_DefaultForm

Checklist Task

Target Class: Syliance.ChecklistTask
Type Projection: Syliance.ChecklistTask.ProjectionType
Default Form: WI_ChecklistActivity\WI_ChecklistActivityTask_DefaultForm

Custom Theme

If you have a custom theme and you modified the CSS file, you have to minify the CSS file and rename it to styles.min.css. If you don’t know what minification means, or if you cannot do it, you can simply rename the file styles.css to styles.min.css.

Custom layout

If you have customized one of the following views, you will need to merge your version with the original file. If you forget to do this, the portal will not function properly.

  • Areas\Analyst\Views\Shared\_LayoutAnalyst.cshtml
  • Areas\EndUser\Views\Shared\_LayoutEndUser.cshtml

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