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.

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 features by following these steps:

Open Control Panel
Go to Programs and Features
Click Turn Windows features on or off located on the left side of the window
Make sure to check the highlighted options:

Installation

Installer

The installer sets up all required APIs and the web client

You can either install a new site or upgrade an existing one. When upgrading, you can select any of your IIS sites. However, the process will fail unless the site is a Perfion Web Client installed using this installer.

When installing a new site, you can select 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 (selectable from a list of databases in the connection by clicking the three-dot button and opening the dropdown menu)

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 manually:

Download the installation zip file

Download the installation zip file from the Perfion Knowledge Base
MAKE SURE to right-click the downloaded zip file, choose Properties, and Unblock it before extracting all files

Unpack the installation zip file

Unpack the files from the installation .zip file which contains three folders: PerfionWebClient, PerfionAPIService, and PerfionClientAPI. Copy these folders into the C:\inetpub directory (it may be helpful to organize them into a folder called Perfion).

Create a new IIS website

Open IIS Manager
Right-click on Sites in the Connections panel and select Add Website
Make the following settings:
1. Set the Site name to PerfionWebClient
2. Set the Physical path to the directory where the folder PerfionWebClient is located, for example: C:\inetpub\Perfion\PerfionWebClient
3. Set IP address, Port, and Hostname to the relevant local settings
Click OK to create the website

Add PerfionAPIService to the site

Expand Sites, right-click PerfionWebClient, and chose to Add Application
Set the Physical path to the directory where the folder PerfionAPIService is located, for example: C:\inetpub\Perfion\PerfionAPIService
Click OK

Add PerfionClientAPI to the site

Expand Sites, right-click PerfionWebClient, and select Add Application
Set the Physical path to the directory where the folder PerfionClientAPI is located, for example: C:\inetpub\Perfion\PerfionClientAPI
Click OK

The Perfion Web Client has been successfully installed, and the result should now appear as follows:

Create Cache folder for images and files

Go to folder C:\inetpub\PerfionWebClient\Perfion
Create a folder called Cache
Right-click on Cache folder, and choose Properties
Add the AppPool Group User PerfionWebClient and grant full control over the folder:

Next, proceed to configure the Perfion Web Client.

Configuration

Follow these steps to configure the Perfion Web Client:

PerfionAPIService - configure database connection

Start Windows Explorer and go to C:\inetpub\Perfion\PerfionAPIService
Create a copy - in the same folder - of Web.config.example and name the copy Web.config
Open Web.config with a text editor
Edit PerfionConn to match your Perfion database setup. Example:

<connectionStrings>
  <add name="PerfionConn" connectionString="Data Source=(local);User ID=dbuser;Password=dbuser-password;Initial Catalog=perfion;PerfionUserID=admin;PerfionPassword=admin-password;PerfionLanguage=" />
</connectionStrings>

5. Save and close the file

PerfionAPIService - configure authentication (SecureAPIService)

The Perfion API supports both 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 operates under 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).

It is strongly recommended that authentication is always enabled (‘SecureAPIService’ set to true)

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

<appSettings>
	<!-- removed for brevity -->
    <add key="Perfion.SecureApiService" value="true" />
	<!-- removed for brevity -->
</appSettings>

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:

<connectionStrings>
  <add name="PerfionConn" connectionString="Data Source=(local);User ID=dbuser;Password=dbuser-password;Initial Catalog=perfion;PerfionUserID=admin;PerfionPassword=admin-password;PerfionLanguage=" />
</connectionStrings>

Save and close the file

PerfionClientAPI - configure runtime settings

The web.config file contains certain settings that configure the IIS runtime, including the maximum allowed size of requests the server will process. If a request exceeds this size, the server will deny it and return an error.

To configure the maximum request size for the PerfionClientAPI, you need to adjust two settings in the web.config file.
Per default, Perfion is configured to allow a maximum request size of approximately 50MB.

MaxRequestLength (HttpRuntimeSection.MaxRequestLength Property (System.Web.Configuration) | Microsoft Learn)
This setting 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 is set on the httpRuntime element within system.web.
Please note that the value is specified in kilobytes.

  <system.web>
    <!-- ... -->
    <httpRuntime ... maxRequestLength="51200" ... />
    <!-- ... -->
  </system.web>

Example - MaxAllowedContentLength

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

  <system.webServer>
    <!-- ... -->
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="52428800" />
      </requestFiltering>
    </security>
  </system.webServer>

PerfionWebClient - update config.json

Go to the C:\inetpub\Perfion\PerfionWebClient folder
Create a copy - in the same folder - of config.json.example and name the copy config.json
Open config.json with a text editor. The file looks like this:

{
    "ServicesBaseUrl" : "/PerfionClientApi/",
	"ImageServerUrl": "/PerfionAPIService/Perfion/Image.aspx",
	"FileServerUrl": "/PerfionAPIService/Perfion/File.aspx",
	"ReportServerUrl": "/PerfionAPIService/Perfion/Report.ashx"
    "customerDefinedLogo": ""
}

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:

"customerDefinedLogo": "/Perfion/filename.jpg"

Restart IIS website

Go back to IIS Manager
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.

Start your favorite browser
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)
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. Only instances installed using the installer can be upgraded.

Manual upgrade

Upgrading the Perfion Web Client requires the following steps:

Prepare upgrade

Download a new .zip installation file
Unpack all files
Stop the website in your IIS manager

Delete old files

Go to C:\inetpub\Perfion\PerfionWebClient
Delete all files - except config.json - in the folder C:\inetpub\Perfion\PerfionWebClient
Go up one level to C:\inetpub\Perfion\PerfionAPIService and delete the bin folder with all its content
Go to C:\inetpub\Perfion\PerfionClientAPI and delete the bin folder with all its content

Add new files

Go to folder PerfionWebClient in the unpacked files
Copy ALL files and subfolders
Go to C:\inetpub\Perfion\PerfionWebClient\ and paste all copied files
Go to folder PerfionAPIService in the unpacked files
Copy ALL files and subfolders
Go to C:\inetpub\Perfion\PerfionAPIService\ and paste all copied files
Go to folder PerfionClientAPI in the unpacked files
Copy ALL files and subfolders
Go to C:\inetpub\Perfion\PerfionClientAPI\ and paste all copied files
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 essential to verify whether the two web.config.example files and the config.json.example file contain updates compared to the currently installed configuration files.
3. If in doubt, create new config files by following the instructions in the Configuration chapter of this guide.

Start website

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

Your upgrade is complete.

NOTE: Ask all users to log out of the web client, reload the web client login page (CTRL+F5 in most browsers) and then log in again. This ensures that no old version is cached in their browser.

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” requires 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

In Azure, resources are fundamental components that encompass a wide array of entities. This guide will focus on the following resource types:

Resource group
App Service Plan
API App
Web App

Resource group

A resource group serves as a container for organizing related components. For instance, when setting up a Perfion Web Client, a dedicated resource group would encompass all the necessary app services required for its operation.

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: Choose the appropriate payment subscription
Resource group: Assign a clear and meaningful name
Region: Select the region where the resource group will be created. Ensuring that all related resources are in the same region minimizes latency and improves performance.

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

App Service Plan

The App Service Plan acts as the “hardware” of the setup, defining the SKU and size on which your app services will run.

Important: An App Service Plan is required for the app services running the APIs and website.

Creating an App Service Plan can be done by navigating to "Create a resource" and providing the necessary details:

Subscription: Select the payment subscription for cost allocation.
Resource Group: Choose where the App Service Plan should be stored.
Name: Assign a clear and meaningful name.
Operating System: For Perfion products, only Windows is supported.
Region: Select the same region for all related resources to minimize latency.
Pricing Tier: Choose the SKU and size, balancing performance and cost.

App Service (API app)

This resource type is designed for hosting APIs, such as the Perfion SOAP API or the Perfion Client API. To create one, simply search for “API App” and initiate the setup.

When creating an API App, the following information must be provided:

App Name: The unique name for the API, also used as its access URL
Subscription: Select the subscription for billing purposes
Resource Group: Specify where the App Service should be stored
App Service Plan: Choose the appropriate App Service Plan under which the API will run
CORS Policy: Configure cross-origin access settings

CORS policy

After creation, the CORS policy must be modified to ensure the API is accessible from the Perfion Web Client.

To do this:

Open the App Service in the Azure Portal
Scroll down the left menu and locate API / CORS
Add a wildcard (*)

Adding APIs to the App service

API data can be integrated into the App Service through various methods, with "Zip Deploy" being the most efficient and recommended approach. For further details, refer to the documentation. Deploy files to App Service - Azure App Service

Perfion Soap/Client API

Web.config file

The web.config file is required as usual and can be modified in two ways:

Before Upload: Add it to the .zip file before deployment.
After Upload: Edit it directly in Azure once the .zip deployment is complete. This can be done by clicking the small "pen" icon next to the web.config file in the Azure portal.

To update the web.config file, insert the following snippet 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, such as the Perfion Web Client. To create one, simply search for “Web AppTo create one, simply search for “Web App” and initiate the setup process.

When setting up the Web App, you will need to provide the following details:

Subscription: Choose the subscription that will be used for billing
Resource Group: Select the resource group where the App Service will be stored
App Name: Enter a name for the website, which will also serve as the URL to access it
Publish: Select “Code” as the deployment method
Runtime Stack: Choose “http://ASP.NET v4.7” for the runtime
Operating System: Select “Windows”
Region: Pick the region where the web app should be hosted. Ensure it aligns with the regions selected for the backend APIs to minimize latency
App Service Plan: Choose the appropriate App Service Plan under which the web app will run

Perfion Web Client

Once the Web app has been created in Azure you can begin uploading the Perfion web client files to the Web app’s FTP server .

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

From this page copy the FTPS endpoint url and the FTPS username & password. After obtaining these details, open a FTP file client and paste the information to connect to the file directory.

Once connected to the FTP file directory, navigate to the Perfion web client installation on the machine from which you will uploaded them:

Select upload on the web client folder which contains the following three sub-folders:

PerfionWebClient
PerfionClientAPI
PerfionAPIService.

NOTE: For convenience, it is recommended to edit all example files in the installation folder beforehand, but they can also be modified after uploading.

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

<?xml version="1.0"?>
<configuration>
  <system.webServer>
    <staticContent>
      <mimeMap fileExtension=".json" mimeType="application/json" />
    </staticContent>
  </system.webServer>
</configuration>

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

After completing these step, go back to the Azure Web app and continue configuring the application.

Azure virtual application configuration

In Azure, navigate to Settings > Configuration for the Web App you created, then go to “Path Mappings” within the configuration settings.

Start by creating a root directory for the uploaded web client, as shown in the screenshot. Follow the previous steps, which will be identical for your installation.

Next, create two additional application directories: one for PerfionClientAPI and one for PerfionAPIService. When pasting the physical path for the application, remember to:

Replace the forward slash (/) with a backslash ()
Uncheck the “Directory” button

Once the applications have been created, click “Save”. Then, return to the “Overview” page and click “Browse”. The web client will open in a new tab.

Config.json file

The config.json file is rquired as usual. It can be modified either before uploading by adding it to the .zip file or by editing it directly in Azure. To edit it in Azure, simply click the little “pen” icon next to the config.json file after the .zip deployment has finished.