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 feature by doing the following:
Open Control Panel
Go to Programs and Features
Click on Turn Windows features on or off in the left side of the window
Make sure these highlighted items are checked:
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
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. 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
Open IIS Manager.
Right-click on Sites in the Connections panel and select Add Website.
Use the following settings:
Set the Site name to PerfionWebClient
Set the Physical path to where you placed the folder PerfionWebClient, it could be C:\inetpub\Perfion\PerfionWebClient
Set IP address, Port, and Hostname to relevant local settings
Click OK to create the website.
Add PerfionAPIService to the site
Expand Sites and right-click PerfionWebClient and chose to Add Application.
Set the Physical path to where you placed PerfionAPIService, it could be C:\inetpub\Perfion\PerfionAPIService
Click OK
Add PerfionClientAPI to the site
Expand Sites and right-click PerfionWebClient and chose to Add Application.
Set the Physical path to where you placed PerfionClientAPI, it could be C:\inetpub\Perfion\PerfionClientAPI
Click OK
The Perfion Web Client has now been installed and the result looks like this:
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 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
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 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).
Perfion strongly recommends 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. 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
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:
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
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:
Local installation: Go to http://localhost:port (use the port which you have set up in IIS)
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. 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
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
Don’t worry – your existing config files will be saved as only example-config files are included in the installation package.
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.
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 an old version is not 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” 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.