Purpose of the Application Server

The purpose of the Perfion Application Server is threefold:

1. It offloads the Web- and Windows-clients certain tasks.

2. It replaces the Perfion Scheduler.

3. It runs certain maintenance tasks.

Offloading jobs from the client

The primary purpose of the Application Server is to allow clients (both the Windows and the Web-client) to send it jobs for asynchronous execution, allowing the client (and its user) to continue working. Running a report or executing an Action are good examples of such jobs.

Before version 4.9 2021 R1 only the Web Client were able to send jobs to the Application Server, but from this version and on, the Windows Client can do it as well.

In this version, the Application Server allows both clients, to perform jobs doing the following:

1. Execute an action

2. Run a report or a publication

3. Do an Import

More Job Types will be added in later versions of Perfion.

Replacing the Scheduler

The Application Server replaces the Scheduler, meaning that it takes over its duty of running Scheduled Tasks.

This means that before installing the Application Server you must uninstall the scheduler, if you have it installed. These two tools will simply not co-exist on the same Perfion Database.

From version 4.9 there is no Scheduler, and an old 4.8 scheduler will refuse to start as soon as your Perfion database has been upgraded to 4.9.

Running Maintenance Tasks

In version 4.9 the Application Server do not have any built-in maintenance tasks. Such tasks will be added in a later version.

Licensing

Note that while running the Application Server does not require any special license, you still need a license to run tasks on the Scheduler (which now is a part of the Application Server).

Furthermore you also need a separate License in order to have access to Actions.

Installing the Application Server

The Application Server can be installed either as a Windows Service or as a Console App. This means, that the Application Server, as the name implies, is a “server process” and will run despite that all Perfion Clients in some installation are shut down. In other words the user can ask the Application Server to do some lengthy job, shut down his/her client and come back next morning to a job that has hopefully completed by then.

The console and service-versions work exactly the same. Perfion recommends installing it as a service, since a service will run on a server despite that no one is logged in.

Installing as a Console App

These are the steps to install the Application Server as a Console App

1. Uninstall the Scheduler, if you have it running. The Application Server will take over its tasks.

2. Find a suitable server for running the Application Server. It can be any Windows Computer having the .net 4.8-framework installed and being able to reach the Perfion Database.

3. Obtain the zip-file containing the Application Server from the Perfion Knowledge Base.

4. Unzip the contents of the zip-file to a folder on the chosen server.

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

   

6. Open the file named Perfion.ApplicationServer.ConsoleApp.exe.config (not Perfion.ApplicationServer.Service.exe.config) and edit the connection string so that it connects to the correct database.

7. Open a Command-prompt and go to the Installation-folder

8. Start the Perfion.ApplicationServer.ConsoleApp.exe (not Perfion.Scheduler.Service.exe) by simply typing Perfion.ApplicationServer.ConsoleApp.exe in the prompt and hitting return.

9. If you have multiple database on which you want to run the Application Server, you need to repeat all the above steps, paying attention to the following:

   1. Each Application Server needs its own installation folder (step 4)

   2. Only one Application Server may handle a Perfion database. Two Application Servers cannot coexist on the same database.

The final step 8 will launch the Application Server as a console app. It looks like shown in the figure below:

If you get an error message when launching it, please check your database connection string. If problem persists, please create a support ticket herein Zendesk.

The Console App can be stopped by pressing the “Return”-key in the window, after which it closes.

After restarting the Windows server, for whatever reason, you will need to restart each Application Server, when running as a Console App.

Installing as a Service

Below are the steps need to be performed to install the Application Server as a Windows Service.

Do steps 1 - 5 as when installing as a Console App.

1. Open the file named Perfion.ApplicationServer.Service.exe.config (not Perfion.Scheduler.ConsoleApp.exe.config) and change the connection, so that it connects to the correct database.

2. If you intend to run multiple Services (i.e. you have multiple databases) you must additionally change the InstallUtil.exe.config-file (a sample file is part of the package). In this file you must change the ServiceName, so that each set up service has a different name. This is needed since two Windows-services cannot have the same name. In order to distinguish each service in the Service-Window, it is a good idea to also change at least the DisplayName and maybe even the Description as well.

A sample InstallUtil.exe.config -file is shown here.

<configuration>
    <startup useLegacyV2RuntimeActivationPolicy="true">
        <supportedRuntime version="v4.0.30319"/>
    </startup>
    <appSettings>
        <add key="ServiceName" value="My.Application.Server.Production"/>
        <add key="DisplayName" value="My Production Application Server"/>
        <add key="Description" value="My Perfion Application Server for Production"/>
    </appSettings>
</configuration>

1. Open a Command-prompt as an Administrator and navigate to the installation folder.

2. Type the command:

   Code Block
   language vb
   InstallUtil.exe "Perfion.ApplicationServer.Service.exe"

3. Assuming the above succeeds (check the output from the InstallUtil-tool), the Application Server is installed and only needs to be started.

4. Open the Services-Window (run services.msc) and find the Application Server-service which is (display-) named My Production Application Server, assuming you used the same naming as shown in the sample above. See screenshot below.

5. Double-click it to edit it and do the following:

   1. Set Startup Type to “Automatic” assuming you want the service to start with the server.

   2. Click the button “Start” to start it now.

6. If you want more Application Servers on the same machine, please run steps 4 – 10 again, making sure that:

   1. You create a new folder for each Application Server

   2. Each service gets its own name in its own InstallUtil.exe.config-file.

   3. Make sure that each service points to its own database. Two Application Servers cannot coexist on the same database.

When having done the steps 1 through 12 the Application Server-service go into status “running” as shown in the screenshot below:

Uninstalling the Application Server-service

This is done using the following steps

1. Open a command-prompt as an Administrator.

2. Go to the installation folder for the Application Server you want to uninstall.

3. It is here important that the InstallUtil.exe.config-file holds the unique service name of the Application Server-service to be uninstalled. It should do so, if it has not been modified since it was installed.

4. Run the following command in the prompt: InstallUtil.exe "Perfion.ApplicationServer.Service.exe" /uninstall

This will uninstall the Application Server with the name provided in the InstallUtil.exe.config-file.

Testing that the Application Server is running

When you have a running Application Server on some Perfion database, you can start the either the Windows or Web Client to check whether it runs as it should or not.

Windows Client

When Application Server is running the two icons with numbers in top right corner of the Windows Client will “light up” as shown here:

When Application Server is not running the two icons will be “greyed out” and look like this:

To learn more about these number, please go to Chapter Understanding the number-icons in main form.

Web Client

When Application Server is running the Application Server icon top right in the Web Client is blue. It looks like this:

When Application Server is not running the same icon is “greyed out” and looks like this:

Using the Application Server in the Windows Client

This chapter will very briefly describe how to use the functionality available on the Application Server when using the Windows Client.

The Windows Client requires an Administrator to pick which functionality for which the Application Server should be used. This is opposed to the Web Client, which cannot do any of the provided functionality, if there is no Application Server installed to do it.

Per default all functionality available on the Application Server will still run locally in the Windows Client, so to utilize the Application Server here, you should, as an administrator, go to “Administration”, pick “Settings” and switch to the “Application Server”-tab and enable the wanted functionality. This tab is shown here:

The topmost three buttons control whether a functionality is run locally or on the Application Server. A “blueish”-button is checked meaning that the client would use the Application Server. A grey button means that the client would run the functionality locally. So in the above example “Reports and Publications” as well as “Actions” are both handled by the Application Server, while “Import” is still to be run locally.

The settings here are global for the Perfion-database, meaning that all users using the Windows Client will be affected by the above.

Note further, that in case you do not use the Web Client, using the Application Server in your installation is optional. All functionality in Perfion is still available to be run local, despite that you choose not to install the Application Server. This may change in a future release of the Application Server.

Running a report or a publication

Running a report on the Application Server is done the exact same way, as when running it locally: Simply right-click an item in some grid and in the popup-menu that appears pick, under the Reports-menu, the one you want to run.

Doing it on the Application Server, however, will not block the client during its generation. Instead the client will send the Job to the Application server and show a “Job Created”-alert telling you, that the Job indeed has been created and that the Application Server soon will pick it up. The alert shows in bottom corner of the Main Form as seen in the screen shot below.

When the Application Server is done carrying out the Report-job (or any Job, for that matter), a similar alert shows up telling you, that the Job has completed. If you are fast, you can click the text, which really is a link, and the produced output will show.

In case you choose not to click it, you can go to the so-called Job Viewer to see the list of jobs you currently have run or still is running. You open the Job Viewer, for example, by clicking any of the icons in the top right-corner of the Main Form. The Job Viewer looks like this when a single Report-job has completed:

Double clicking a job will show you the result of it (if it has a result). In this example, clicking a report job will bring up the usual Perfion Report-dialog (not shown).  

You can read more about the Job Viewer in Chapter The Job Viewer.

Doing an import

Similar to running a report, the Importer is invoked in the exact same manner, regardless of whether you use the local client to handle the import or you have configured the Application Server to do it. Open the “Feature Data Importer”, pick a feature and a file as usual and hit the “Start Import”-button. As for the report, an alert tells you that your job has been created.

Since there is no result of an import, except a confirmation that it ran OK (assuming it did). Double-clicking an Import-job in the Job Viewer will therefore take you to the View-Job dialog instead of opening some output.

The Job Viewer together with the View Job-dialog can be seen here:

The View Job-dialog simply tells you, for the import job, that it is indeed completed and for how long the job ran. Note that in case an error (exception) happened during import, it is clearly visible in this View-dialog as the job shown here:

The above dialog is a result of running some import using an import-file that containing an error. Notice the 2^nd tab now available in the dialog. This tab shows the exception message that caused the Application Server to quit running the Job. In this particular case, the error message directs you towards the Import log to find more information on the issue, but in most cases, the message will indicate what the problem is.

Importing binaries using the Application Server

As always, when importing binaries into Perfion, the imported file must contain an absolute path to these binaries. If you are using paths starting with a drive-letter (C:\My folder for example), these paths will be interpreted by the Application Server as local to it, meaning that it will look for the folder “My folder” on its own C-drive (assuming it has one). In other words, it is not pointing towards the C-drive on the client submitting the Job, as someone might have expected. Therefore it is usually better to use UNC-paths (\\[Some Server]\[Some folder]) pointing to servers that the Application Server has access to or to use urls.

Running an action

As with all Application Server functionality, Actions will run as always, that is locally, until Actions are enabled in the “Application Server”-tab in Setting. So in order to run Actions on the Application Server, you will need to enable it as described in Chapter Using the Application Server in the Windows Client.

Regarding Actions, this setting only affects Actions when they are run from the “Execute Actions”-menu as shown here:

The little question-mark on each “Execute Action”-icon indicates, that when executing the Action the user will be shown a dialog in which he must choose whether to execute it locally or on the Application Server (or cancel):

You can avoid the above dialog if you want to. You do that individually on all actions in the Actions-Section as shown in the screen shot below:

Notice the three Actions in the “04 Sync”-folder:  The newly introduced “Job Execution”-feature controls where an Action is designated to run. You simply select between either “Application Server” or “Local”. Leaving the value empty (or assigning it a 3^rd value, say “Show dialog”) will cause the “choose-dialog”, which we saw previously, to show.

With the “Job Execution”-settings in place, for example as shown above, we get the following “Execute Actions”-menu:

Notice that the small “extra icon” on each “Execute Action”-menu has changed to reflect your choice of “Job Execution”.

Even when indicating that some Action should be executed by the Application Server, it will, as previously noted, only do that when the Action is executed from the “Execute Actions”-menu. You can still run any Action locally, simply by right clicking it and go to the Actions-submenu. Doing this will, as previous Perfion versions did, show you the Action-dialog which only runs Actions locally.

As was the case for the Scheduler and now also for the import, the Application Server treats all file/directory paths in Actions using a drive-letter as if they are local references. If you create an action that includes a reference to, say, the C-drive, the Application Server will use the C-drive on the server where it is installed (if it exists, and it has access otherwise it fails). Best practice is therefore again to use UNC paths (\\[some server]\[some folder]) in actions. That way the paths work both locally and on the Application Server.

Understanding the number-icons in main form

The number icons shown in the main form tells the user whether or not there is an Application Server active, as we saw in Section Testing that the Application Server is running. The numbers and icons indicate more than that.

If we look at the above screenshot, the first number after the “play symbol” (here a “2”) tells the user (“Administrator” in this case), that he/she has 2 jobs currently running on the Application Server. The second number after the “checkmark” (here “4”) tells the user, that he has 4 jobs that has completed. The fact that the checkmark-icon next to it is green tells you, that they all 4 jobs have completed successfully, i.e. without any errors. If one or more of the completed jobs has failed, the check mark would have been orange instead, as shown here:

Regardless of whether the icons are “greyed out” or not, or whether any job has failed or not, clicking any of them will bring up the Job Viewer. This viewer is described in Chapter The Job Viewer.

The Job Viewer

Clicking any of the “number-icons” in the top right-corner of the main form takes you to the Job Viewer. Here each Perfion User has his own list of Jobs. That includes both jobs that are currently running and jobs that has completed running (successfully or not). The following screen shot shows the Job Viewer with 3 completed jobs:

As can be seen a completed job shows different icons. If a Job has a file result, it will use the icon associated with the file type (i.e. a pdf-file will show you whatever icon your pdf-viewer has). A report job run from the Windows Client will show the Report-viewer icon telling you, that you get the built-in report-viewer double clicking that. A green check mark indicates a successfully completed job, which does not provide any output. That would be an action or an import. If a job for any reason has failed to execute a red X will be shown as shown here:

The 2nd Job is an Action that failed to run.

Double-clicking any job will open its result (if any). If no result or if Job failed to run, it will take you to the View Job-dialog to show you more on the Job and, in case it failed, the error that happened.

You can also right click a job, and see what (other) options you have, as shown here:

Image Removed

Image Added

View… takes you to a “Job View”-dialog. This simply shows the current status of the job. Mostly used when a job is failed to see its exception (with Stack Trace).

Open… is only available for jobs producing a result. This will open the result in the appropriate tool. A report will open the built-in Report-viewer while a publication (a pdf file) will open in the default pdf-viewer installed on your machine.

Open folder… is only available for jobs producing a result. It will open Windows Explorer and navigate to the local folder in which the Windows Client stores all files generated by some Job is available after they are downloaded. In some cases these files are readily usable by “outside applications”. An example would be a pdf-file generated by “Publishing”, which can be opened in any tool handling pdf-files. In other cases, these files are “Perfion internal”. An example would be the result of running a report. The result is a binary-file in Perfions internal report-format. A format not really usable outside Perfion.

Save as… will allow you to save the files output by a Job elsewhere by showing a “Save as…”-dialog.

Download / Redownload are only available for jobs producing a result. The Application Server stores the result of a job in the Perfion database (or in the cloud if enabled). This result can be downloaded when picked.

Depending on your settings, the client will automatically download the output of a job as soon as it is completed. In case this feature is not enabled or the client was not running at the time the job was completed by the Application Server, the result of a job will not be downloaded automatically. See more about which settings you have in Section The Settings-dialog.

Stop is only available during Job-execution. Picking this signals to the Application Server, that you want to stop the execution of a particular job. Depending on the Job, it may take a while before the job actually stops. When it does it will be marked as failed. Note that some jobs may never stop but complete regardless of picking this.

Delete willdelete the job together with any downloaded output from it.

Rerun will create a new Job as an exact copy of the picked job and run this new job. Useful if you have a job that failed and you simply want to try it again.  

Refresh will simply refresh the list, while Show descriptions will show any descriptions associated with the job in the grid.

The Ribbon-menu

The topmost button Download all completed will take all jobs that are completed, which does not already have their result downloaded to the current client, and download them.

The Clear completed will delete all completed jobs, regardless whether they failed or not, together with any files they have downloaded.

Finally unchecking the Condensed view-button will switch to “Expanded view” (Being bluish indicates “Condensed View”). The expanded view mode adds a few more columns to the grid and reveals a few more buttons in the Ribbon-menu. The “Expanded” Job Viewer is shown below:

The newly added buttons has the following functionality: Refresh will simply refresh the grid from the database. Checking Auto refresh (shown blueish when checked) will periodically refresh the list. Checking Log will reveal the log grid (not shown). Finally clicking Settings will take you to a dialog where you can control your personal settings for how you want your client to work with the Application Server. See more on this in Section The Settings-dialog.

The Settings-dialog

The Settings-dialog can be invoked from the Job Viewer when not in “Condensed View”. This dialog contains your personal settings, that is, settings associated with the logged in Perfion User.

The dialog contains two tabs with settings:

Windows Client-tab

Here you can control the following. First of all there are which alerts to show. There are 3 options:

• Never show any: No alerts (regarding Jobs in Application Server) are shown.

• Show only created and completed (default): An alert is shown whenever a job is created and another when it is completed. If a Job has a result AND the “automatically download job results” is checked (see below), a job is first completed (in this respect), when it is downloaded otherwise it is completed when there is nothing more for the Application Server to do.

• Show all alerts: An alert is shown for every “status change” a job undergoes. You are notified when a Job is created, when it starts uploading binary data to storage (if any, for example a file to an import), when the server starts working, when the server completes and when the client is done downloading its result (if any).

Next setting allows you to control for how many seconds an alert is displayed (default is 3 secs).

Regarding Job Results you can control whether or not a running client should automatically start downloading the result of a job. This setting is enabled per default. Note that the client will only do this, if it is running at the moment the Application Server completes the job. If a job completes when the client is not running, the user will need to manually download it.

You can still open a Job with a result, even if its result has not been downloaded. Clicking Open… on such a Job will simply start downloading the result and Open it as soon as it is downloaded.

Finally the Time between refreshes of Jobs from database controls how often the client checks the users Jobs in the database (for status-updates etc.) Default is 5 secs.

Job Viewer-tab

In this tab, you control how the Job Viewer behaves:

All three settings here control how the Job Viewer should appear the first time it is opened after the Perfion client has been restarted. This means, that simply closing and opening the Job Viewer will not apply these settings.

You can choose whether the Job Viewer should be shown in either Condensed or Expanded mode. Default is condensed. Furthermore you can choose to enable or disable Auto refresh and finally you can choose to Show log when opening job viewer. Default is here to not do that. The latter works only, if Job Viewer is opened in expanded mode. Condensed mode does not allow you to see the log.

Security considerations

If a connection string uses a SQL Server login, the security profile of the SQL Server process account is used. A login using SQL Server authentication cannot be authenticated outside of the Database Engine. Therefore, when certain SQL commands are issued by a login using SQL Server authentication, the connection to the data is made using the security context of the SQL Server process account (the account used by the SQL Server Database Engine service).
To successfully read the source data you must grant the account used by the SQL Server Database Engine access to the source data. This is known as NTFS security and is defined in the Security tab when you access the properties of the containing directory. In contrast, if a SQL Server user logs on by using Windows Authentication, the user can read only those files that can be accessed by the user account, regardless of the security profile of the SQL Server process.
For example, consider a user who logged in to an instance of SQL Server by using Windows Authentication. For the user to be able to use (e.g.) BULK INSERT or OPENROWSET to import data from a data file into a SQL Server table, the user account requires read access to the data file. With access to the data file, the user can import data from the file into a table even if the SQL Server process does not have permission to access the file. The user does not have to grant file-access permission to the SQL Server process in this way.

Troubleshooting

Can’t get the Application Server to run

If you have problems getting the Application Server to run, please check the connection string in either the Perfion.ApplicationServer.Console.exe.config-fileor Perfion.ApplicationServer.Service.exe.config-file depending on which version you installed.

If you run the Application Server as a service, and you cannot figure out what the problem is, you can copy the content of the service config-file to the “corresponding” console config-file and try to run it as a console app. The console app makes it easier to see any error messages.

Please contact Perfion Support if problem persists.

Application Server shuts down

If you are having trouble keeping the Application Server up, you should contact Perfion Support. In the meantime consider switching to local execution of some or all the functionality or to restart the Application Server periodically.