Kofax PSIsafe API & 64-bit Server Installation / Upgrade Guide

Kofax PSIsafe version 12.2.x

API version 1.0.x

  Download Pending

 

 Note

This article is intended for On-Premises installations only. This article is not applicable to PSIsafe Cloud customers.

 Audience

This article is intended for PSIsafe Administrators.

Overview

The PSIGEN Affinity API and Server work together to allow a variety of PSIGEN products, as well as custom applications, to communicate with your PSIsafe 32-bit installation via the Azure API Management Service. This not only allows 64-bit applications to work with your PSIsafe installation, but also allows programmers to create custom programs that can send and receive data as it suits your unique business application needs. Below is a breakdown of the PSIGEN Affinity API and Server deployment process.

 

You may be installing the PSIsafe API in a new environment (fresh) or upgrading an existing API installation. Either way, follow the steps below to ensure your PSIsafe API is fully functional.

 

Prerequisites:

  • Internet Information Services and IIS Manager. Required to host Affinity API in IIS on your server. See detailed requirements for specific Server Roles required below (referred to as Windows Features in Windows 10).

WEB SERVER IIS (Server Roles):

Common HTTP Features:

  • Default Document
  • Static Content

Health and Diagnostics:

  • HTTP Logging
  • Request Monitor

Performance Features:

  • Static Content Compression

Security:

  • Request Filtering
  • Windows Authentication

Application Development:

  • .NET Extensibility 4.7
  • ASP.NET  4.7
  • ISAPI Extensions
  • ISAPI Filters

Management Tools:

  • IIS 6 Management Console

  • Management Service

  • PSIsafe 32-Bit Server version 12.2 or later

  • PSIsafe Desktop Client and Manager version 12.2 or later
    Note: The Affinity API and Server runs independently of the PSIsafe Desktop Client and 32-Bit Server. However they are required when setting up a PSIsafe database and to run PSIsafe Management for registration and management.

  • ASP.Net  Core 3.1.6 or later Hosting Bundle: "https://dotnet.microsoft.com/download/dotnet-core/3.1 "


Items.png

Note: If you are developing an application utilizing the Affinity API you need to install the .Net Core 3.1.6 or later framework.

Important: Make sure that you install IIS BEFORE the Hosting Bundle. If not you will get a 500.19 Internal Server error when you try to run the API web site. To fix this perform a repair (re-install) of the Hosting Bundle.

Install ASP.Net Hosting Bundle

Download ASP.NET Core Runtime 3.1.6 or later Hosting Bundle from:
https://dotnet.microsoft.com/download/dotnet-core/3.1

  1. After downloading, right click the downloaded EXE file and select Properties.
  2. Check the “Unblock” checkbox and then Select OK.
  3. Right-click the EXE file again and select Run as Administrator.
  4. Proceed through installation process.

 

Deployment Packages

If you are NOT a member of the PSIGEN Engineering team please use deployment package provided by PSIGEN. If you need assistance downloading a deployment package, Contact PSIGEN Support.

Otherwise, links to packages containing the API files will be provided to authorized personnel. 

 

PSIsafe API Server/Service Deployment

  1. Create folder C:\Program Files\PSIGEN\PSIsafeAPIServer

  2. Copy the contents of the folder named “server” from your downloaded API files to the
    folder just created above

  3. If you have already registered an installation of PSIsafe on this server:

  4. Copy CNGDBList.XML from
    C:\Program Files (x86)\CNG\CNGServer to
    C:\Program Files\PSIGEN\PSIsafeAPIServer
    This step ensures that PSIsafe API can connect to the database

  5. Copy CNGServer.XML from
    C:\Program Files (x86)\CNG\CNGServer to
    C:\Program Files\PSIGEN\PSIsafeAPIServer
    This file holds various configuration settings that are set using PSIsafe Management, such as Login Policy, Email Settings and more.
    NOTE: If you change any of these settings in PSIsafe Management, you will need to copy the CNGServer.XML file again.

  6. From Start Menu, launch an administrative Command Prompt by typing “cmd”, then right-click and select "Run as Administrator"
    6.a. From Command Prompt, enter:
    /databases?customercode=default"cd C:\Program Files\PSIGEN\PSIsafeAPIServer\scripts" and press Enter.
    6.b. Enter install.bat and press Enter.
    6.c. From Start Menu, launch Windows Services by typing services.msc and press Enter

    services.png

    6.d. From Windows Services list, scroll and locate "PSIGEN PSIsafe API Server"
      - Verify service is running
      - Verify Startup Type is set to Automatic.

Note: If you need to remove a service you can:

  1. Use Powershell 7 or later with the command below:
    Remove-Service -Name "PSIGEN.PSIsafe.Service"
  2. If you have Powershell V5:
    * Open Windows PowerShell ISE
    * Paste the following two lines:
    * $service = Get-WmiObject -Class Win32_Service -Filter "Name='PSIGEN.PSIsafe.Service'"
    * $service.delete()
    * Run the script with F5 or pressing the play button
    
  3. Use command prompt (with Administrator privileges) with the command below:
    sc delete "PSIGEN.PSIsafe.Service"

 

PSIsafe API Deployment

  1. Extract the contents of api.zip to a folder path such as C:\Program Files\PSIsafe\PSIsafeAPI
  2. Copy the contents of the folder named “api” from your downloaded installation files to
    the folder just created above, e.g. C:\Program Files\PSIGEN\PSIsafeAPIServer\
  3. From the Start Menu, launch Internet Information Services by typing IIS and press Enter.
  4. Expand the server name on the left.
  5. Right-click Application Pools.
  6. Select Add Application Pool…
  7. Name Application Pool "PSIsafe"
  8. Right-click Default Web Site.
  9. Select Add Application…
  10. Assign the Application Pool created above to the Application.

IMPORTANT NOTE: For production systems, ensure the PSIsafe API Web Site is utilizing an HTTPS type binding with a production certificate. Additionally, if the Administrator does not have access to an SSL Certificate, one may need to be purchased. For a system running locally for testing and development, http (port 80) without certificate is acceptable.

 

Test API Deployment Functionality

1: In IIS Manager. Right select your PSIGEN PSIsafe API Web Site (Production) or PSIsafe API Application under Default Web Site.
2: Select Browse on the right side in IIS Manager:

iis1.png

3: Append /API to the URL in the browser
For example https://localhost:443/api  (with certificate) or http://localhost/affinityapi/api  (without certificate).
4: Verify that the API name and version is returned on the page.

 

Test Database API Functionality


Test that the API can connect to your PSIsafe Database by appending the following to the URL: /databases?customercode=default
This should display a screen similar to the following (a list of PSIsafe databases visible to the PSIsafe API):

check2.png

If this step fails. Double check that you performed the step above:
Copy CNGDBList.XML from C:\Program Files (x86)\CNG\CNGServer to C:\Program Files\PSIGEN\PSIsafeAPIServer


Add Write Permissions to applogs folder in API

This is required so that PSIsafe App Pool can write to the logs.

In IIS Manager:
1: Find the applog folder for the PSIsafe API.
2: Right click and select Edit Permissions

iis2.png

3: Open Security Tab.
4: Select Edit.
5: Click Add..
6: Key in "iis apppool\psisafeapi" (where affinityapi is the name of the app pool used for PSIsafe API.)
7: Click Check Names. And then OK.

Double Check - Test that API and Affinity Server are deployed and configured properly

To test do the following in IIS Manager:
1: Select your PSIsafe API Web Site (or application under Default Web Site).
2: Select Browse in the Actions Panel in IIS Manager.
Note: Your configuration may be different based on where you deployed the PSIsafe API and if you have a certificate configured.
3: Add /API to the URL in the web browser. For example:
4: Append the following to the URL: /databases?customercode=default
This will connect to the PSIsafe SQL DB and return one or more database names (as configured in PSIsafe Management)

check4.png

Upgrading Existing API Installation


The following instructions are for upgrading an existing installation of the PSIsafe API. These instructions
assume the API resides on the same server as the PSIsafe database.

 

Download updated PSIsafe API files

a. Right-click downloaded Zip file and select Properties
b. Check the box on the Properties dialog that says “Unblock”
c. Select Ok

 

Update Database

NOTE: This step is only required if updating to PSIsafe API version 1.0.18 from PSIsafe API version 1.0.15.x or prior. If current PSIsafe API version is 1.0.18 or greater, database update is not required. Skip ahead to
step 3 to proceed with PSIsafe API update.

  1. Log into server where PSIsafe Database resides (or any system where SSMS can connect
    to database server)
  2. From Start Menu, launch SQL Server Management Studio (SSMS)
  3. Log into SQL Server instance containing database
  4. From SSMS File Menu, select Open > File…
  5. Browse to the location containing updated PSIsafe API files
  6. From the db folder, select PSIsafeAPIDatabaseUpdates.1.0.18.sql
  7. Once query has been loaded in SSMS, select Execute from ribbon menu
  8. After query completes, verify the following additions to database
    1. New table created: dbo.SearchQuery
    2. New Column added to table dbo.DocumentNotes: IsAlert

Stop Services and IIS

  1. From Start Menu, launch Services.msc
  2. Select PSIGEN PSIsafe API Server and right-click
  3. Select Stop from context menu
  4. From Start Menu, launch Internet Information Services (IIS)
  5. Expand server name on left
  6. Expand Sites
  7. Select Default Web Site
  8. From Actions panel on right, select Stop

 

Update Server folder

  1. In Windows Explorer, navigate to
    C:\Program Files\PSIGEN
  2. Create a copy of the current PSIsafeAPIServer (for backup purposes)
    Name copy “PSIsafeAPIServer - <current version>”
  3. Open current PSIsafeAPIServer folder
  4. Delete all files and folders except for “config” folder from:
    C:\Program Files\PSIGEN\PSIsafeAPIServer
  5. Copy all files and folders except for “config” folder from the new folder
  6. Paste all copied files and folders into
    C:\Program Files\PSIGEN\PSIsafeAPIServer

 

Update API folder

  1. In Windows Explorer, navigate to
    C:\Program Files\PSIGEN
  2. Create a copy of the current PSIsafeAPI (for backup purposes)
    Name copy “PSIsafeAPI - <current version>”
  3. Open current PSIsafeAPI
  4. Delete all files and folders except for “Web.config” file from
    C:\Program Files\PSIGEN\PSIsafeAPI
  5. Copy all files and folders except for “Web.config” file from the new API folder
  6. Paste all copied files and folders into
    C:\Program Files\PSIGEN\PSIsafeAPI

 

Start IIS and Services

  1. From Start Menu, launch Internet Information Services (IIS)
  2. Expand server on left
  3. Expand Sites
  4. Select Default Web Site
  5. From Actions panel on right, select Start
  6. From Start Menu, launch Services.msc
  7. Select PSIGEN PSISafe API Server and right-click
  8. Select Start from context menu

 

Verify API upgrade successful

  1. From Start Menu, launch browser
  2. In address bar, enter
    http://localhost/PSIsafe/api
  3. Verify version displayed reflects version just installed

 

Congratulations! You have now successfully deployed / upgraded the PSIsafe Server and API.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.