Web Client - Installation Guide

The Perfion Web Client is a browser-based tool that enables users to manage Perfion items in a browser as an alternative to the Windows client.

This document explains how to install and configure the web client.

Open

Prerequisites

System requirements

For details on system requirements for installing the Perfion Web Client application, please refer to System Requirements.

Enable the Internet Information Server on Windows

Before installing the Perfion Web Client, you must enable Internet Information Server (IIS) on the Windows operating system.
Please refer to the following guide on how to install How to Install IIS on Windows 8, 10, or 11.

Install Windows features for IIS

Open Windows feature by doing the following:

1. Open Control Panel

2. Go to Programs and Features

3. Click on Turn Windows features on or off in the left side of the window

4. Make sure these highlighted items are checked:

Open

Installation

Installer

The installer installs all the necessary API’s and the web client.

It is possible to either install a new site or upgrade an existing site. When upgrading an existing site, you have the possibility to choose all your IIS sites, but it will fail if it is not a Perfion Web Client installed with this installer.

When installing a new site, you have the possibility to choose a different folder for the installation.

Installation settings

HTTPS: Enable or disable HTTPS

HTTP(S) Port: the port you want the application to run on

Certificate: Certificate for HTTPS

Hostname: Hostname you want the application to run on. Leave empty for localhost

Secure API: Enable or disable secure API

SQL Server: SQL server name (leave empty to use local data source)

Database name: Name of Perfion database (Can be chosen from a list of databases in the connection by pressing the tree dot button and opening the dropdown)

Username: Username for Perfion database connection

Password: Password for Perfion database connection

Perfion User: Admin user for Perfion

Perfion Password: Password for user

Manual installation

Follow these steps to install the Perfion Web Client manual.

Download the installation zip file

1. Download the installation zip file from the Perfion Knowledge Base

2. MAKE SURE to right-click the downloaded zip file, choose Properties, and Unblock It before extracting all files.

Unpack the installation zip file

1. Unpack the files from the installation .zip file. It contains three folders PerfionWebClient, PerfionAPIService, and PerfionClientAPI. Copy the folders and place them in the C:\inetpub directory(it can be advantageous to collect them in a folder called Perfion).

Create a new IIS website

1. Open IIS Manager.

2. Right-click on Sites in the Connections panel and select Add Website.

3. Use the following settings:

   1. Set the Site name to PerfionWebClient

   2. Set the Physical path to where you placed the folder PerfionWebClient, it could be C:\inetpub\Perfion\PerfionWebClient

   3. Set IP address, Port, and Hostname to relevant local settings

4. Click OK to create the website.

Add PerfionAPIService to the site

1. Expand Sites and right-click PerfionWebClient and chose to Add Application.

2. Set the Physical path to where you placed PerfionAPIService, it could be C:\inetpub\Perfion\PerfionAPIService

3. Click OK

Add PerfionClientAPI to the site

1. Expand Sites and right-click PerfionWebClient and chose to Add Application.

2. Set the Physical path to where you placed PerfionClientAPI, it could be C:\inetpub\Perfion\PerfionClientAPI

3. Click OK

The Perfion Web Client has now been installed and the result looks like this:

Create Cache folder for images and files

1. Go to folder C:\inetpub\PerfionWebClient\Perfion

2. Create a folder called Cache

3. Right-click on Cache folder and choose Properties

4. Add the AppPool Group User PerfionWebClient and grant full control of the folder:

You must now proceed to configure the Perfion Web Client.

Configuration

Follow these steps to configure the Perfion Web Client.

PerfionAPIService - configure database connection

1. Start Windows Explorer and go to C:\inetpub\Perfion\PerfionAPIService

2. Create a copy - in the same folder - of Web.config.example and name the copy Web.config

3. Open Web.config with a text editor

4. Edit PerfionConn to match your Perfion database setup. Example:

5. Save and close the file

PerfionAPIService - configure authentication (SecureAPIService)

The Perfion API supports either authenticated and unauthenticated requests. When authentication is enabled, the API executes queries in the context of the authenticated user. If authentication is disabled, the API will execute in the context of the user account specified in the ‘PerfionConn’ connection string (see above).

If authentication is enabled, and the API request does not include authentication, the API will reject the request with an error. For more information about how to authenticate, please refer to Authentication - Perfion Knowledge Base - Perfion Knowledge Base (atlassian.net).

To enable authentication, set Perfion.SecureApiService to true in the PerfionAPIService web.config file

PerfionClientAPI - configure database connection

6. Now go to C:\inetpub\Perfion\PerfionClientAPI

7. Create a copy - in the same folder - of Web.config.example and name the copy Web.config

8. Open Web.config with a text editor

9. Edit the ConnectionString to match your Perfion database setup. Example:

10. Save and close the file.

PerfionClientAPI - configure runtime settings

The web.config file contains certain settings that configure the IIS runtime. This includes settings of the maximum allowed size of requests that the server will process. If requests are sent to the server, that are bigger than this settings, the server will deny handling the request and instead return an error.

There are two relevant settings, which both needs to be set in the web.config file for the PerfionClientAPI.
Per default, Perfion is pre-configured to allow a maximum of approximately 50MB.

• MaxRequestLength (HttpRuntimeSection.MaxRequestLength Property (System.Web.Configuration) | Microsoft Learn)
  This settings configures the maximum request size supported by ASP.NET.

• MaxAllowedContentLength (Request Limits <requestLimits> | Microsoft Learn)
  This setting configures the maximum request size supported by IIS.

Example - MaxRequestLength

The maxRequestLength settings is set on the httpRuntime element within system.web.
Please notice that the value is in kilobytes.

Example - MaxAllowedContentLength

The maxAllowedContentLength settings is set on the requestLimits element element within system.webServer - security - requestFiltering.
Please notice that the value is in bytes.

PerfionWebClient - update config.json

1. Go to the C:\inetpub\Perfion\PerfionWebClient folder

2. Create a copy - in the same folder - of config.json.example and name the copy config.json

3. Open config.json with a text editor. The file looks like this:

4. The settings ImageServerUrl, FileServerUrl, and ReportServerUrl point to the Perfion API installed with the Web Client. If you want the Web Client to retrieve images and files via another Perfion API, you can adjust these settings.

5. The setting customerDefinedLogo allows you to load your company’s logo and show it in the Web Client. Copy the logo file to C:\inetpub\Perfion\PerfionWebClient\Perfion and reference the file like this:

Restart IIS website

1. Go back to IIS Manager

2. Click on the first item in the Connections panel and in the Actions panel click Restart.

Start the web client

You are now ready to start the web client.

1. Start your favorite browser

2. Go to the start page:

   1. Local installation: Go to http://localhost:port (use the port which you have set up in IIS)

   2. Server installation: Go to http://ip-address:port (use the IP/domain and port which you have set up in IIS)

3. Enter a valid Perfion username and password and click login

Upgrading the Web Client

Installer upgrade

Follow the Installer guide and select the instance you want to upgrade. It is only possible to upgrade instances that are installed with the installer.

Manual upgrade

Upgrading the Perfion Web Client requires the following steps.

Prepare upgrade

1. Download a new .zip installation file

2. Unpack all files

3. Stop the website in your IIS manager

Delete old files

1. Go to C:\inetpub\Perfion\PerfionWebClient

2. Delete all files - except config.json - in the folder C:\inetpub\Perfion\PerfionWebClient

3. Go up one level to C:\inetpub\Perfion\PerfionAPIService and delete the bin folder with all its content

4. Go to C:\inetpub\Perfion\PerfionClientAPI and delete the bin folder with all its content

Add new files

1. Go to folder PerfionWebClient in the unpacked files

2. Copy ALL files and subfolders

3. Go to C:\inetpub\Perfion\PerfionWebClient\ and paste all copied files

4. Go to folder PerfionAPIService in the unpacked files

5. Copy ALL files and subfolders

6. Go to C:\inetpub\Perfion\PerfionAPIService\ and paste all copied files

7. Go to folder PerfionClientAPI in the unpacked files

8. Copy ALL files and subfolders

9. Go to C:\inetpub\Perfion\PerfionClientAPI\ and paste all copied files

10. Say YES to overwriting all existing files

    1. Don’t worry – your existing config files will be saved as only example-config files are included in the installation package.

    2. NOTICE: With a new web client version, changes to config files might be necessary. It is therefore important to check if the two web.config.example files and the config.json.example file includes changes over the already installed config files.

    3. If in doubt, create new config files by following the instructions in the Configuration chapter of this guide.

Start website

1. Now go to IIS Manager and start the Perfion Web Client site.

Your upgrade is complete.

Azure Installation

Introduction

This section describes how to set up Perfion services in Azure. These services include the following products.

• Perfion SOAP API

• Perfion Client API

• Perfion JSON API

• Perfion Web Client

This “how-to” expects that you have the necessary user right in Azure to create new resources, and a valid subscription to pay for the services.

Creating resources in the Azure portal

When logged onto the Azure portal, it is possible to create resources. Resources are the building block of Azure and can be many different things. This guide will focus on the following resource types.

• Resource group

• App Service Plan

• API App

• Web App

Resource group

A resource group is used to group everything together. Say that one wants to set up a Perfion Web Client. A resource group for this would then contain all the app services that is needed to run the Web Client.

Creating a resource group is done by finding it in “create a resource” and filling in the necessary information’s. These are as follows.

• Subscription: Select the payment subscription

• Resource group: Give the resource group a meaningful name

• Region: Select the region that the resource should be created in. It is important to select the same region for all the created resources that should talk to each other. This is to keep latency down.

When everything is filled out, click “Review + Create” to create the resource.

App Service Plan

The App Service Plan is the resource that can be considered the “hardware” of the setup. In this you configure what SKU and size you want you App services to run on.

Note that this is required for the App services that will run the API’s and Website

Creating an App Service Plan is simple as finding it in the “Create a resource” and filling in the necessary information.

• Subscription: Which subscription that should be used for charging the costs.

• A resource group: On which the App Service Plan should be stored

• A meaningful name

• Operating system: For Perfion products, only Windows is supported

• Region: Select the region that the resource should be created in. It is important to select the same region for all the created resources that should talk to each other. This is to keep latency down.

• Pricing Tier: Sku and size determines the horsepower that will be available and the cost

App Service (API app)

This resource type is used to host API’s. For instance, the Perfion Soap API or the Perfion Client API. To create on simply find it by searching for “API app” and creating it.

You then need to fill in the necessary information.

• App name: The name of the API. This will also be used to reach the API.

• Subscription: Which subscription that should be used for charging the costs.

• A resource group: In which the App Service should be stored

• App Service plan: Select the app service plan that the API should run under.

CORS policy

Once created the CORS policy needs to be changes if the API should be reachable from the Perfion Web Client. This is done by opening the app service and scrolling the left menu down until API / CORS is found.

In here a * wildcard should be added.

Adding API’s to the App service

API Data can be added to the App service in many ways. The most suitable way is the “Zip deploy” method. More information can be found here. Deploy files to App Service - Azure App Service

Perfion Soap/Client API

Web.config file

The web.config file is needed as normal. It can be modified either before the upload by adding it to the .zip file or by editing it directly in Azure. Editing it in Azure can be done after the .zip deployment has finished, by simply clicking the little “pen” icon next to the web.config file.

• Add the following to the Web.config file just below </handlers> in the <system.webServer> section

• In Azure -> Configuration > Path Mapping add a Virtual Path ( PerfionWebApi )

App service (Web app)

This resource type is used to host websites. For instance, the Perfion Web Client. To create on simply find it by searching for “Web app” and creating it.

You then need to fill in the necessary information.

• Subscription: Which subscription that should be used for charging the costs.

• A resource group: In which the App Service should be stored

• App name: The name of the website. This will also be used to reach the website.

• Publish: Select “Code”

• Runtime stack: Select “ASP.NET v4.7”

• Operating system: Select “Windows”

• Region: Select the region the web app should be hosted in. Note that it should be the same as the regions selected for the backing API’s

• App Service plan: Select the app service plan that the web app should run under.

Perfion Web Client

Once the Web app has been created in Azure one can start uploading the Perfion web client files to the FTP server of the Web app.

The information for the FTP server can be found: Deployment > Deployment Center > FTPS credentials

From this page copy the FTPS endpoint url and the FTPS username & password, once these three are acquired open a FTP file client and paste the information to connect to the file directory.

Once connected to the FTP file directory browse the installation files for the Perfion web client on the machine from which it will be uploaded from:

Select upload on the web client folder which contains three sub-folders; PerfionWebClient, PerfionClientAPI & PerfionAPIService.

NOTE: for convenience, edit all the example files in the installation folder beforehand, but this can also be edited once uploaded.

Additionally create a “web.config” which contains the following lines:

Save it and upload it into the “PerfionWebClient” folder:

After these step, go back to the Azure Web app and continue the configuration of the application.

Azure virtual application configuration

In Azure find the Settings > Configuration for the Web app created and go to “Path mappings” within in it:

Here start with creating a root directory for the web client uploaded as shown on the screenshot, following the previous steps that will be identical for your installation.

Now create two additional application directories one for the PerfionClientAPI & PerfionAPIService: (when pasting in the physical path for the application remember to change the forward slash to backslash and uncheck “Directory” button)

Once the applications has been created click save and go back to the “overview” page and click browse, the web client will open in a new tab.

Config.json file

The config.json file is needed as normal. It can be modified either before the upload by adding it to the .zip file or by editing it directly in Azure. Editing it in Azure can be done after the .zip deployment has finished, by simply clicking the little “pen” icon next to the config.json file.