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 "
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
- After downloading, right click the downloaded EXE file and select Properties.
- Check the “Unblock” checkbox and then Select OK.
- Right-click the EXE file again and select Run as Administrator.
- 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
-
Create folder
C:\Program Files\PSIGEN\PSIsafeAPIServer
-
Copy the contents of the folder named “server” from your downloaded API files to the
folder just created above -
If you have already registered an installation of PSIsafe on this server:
-
Copy CNGDBList.XML from
C:\Program Files (x86)\CNG\CNGServer
toC:\Program Files\PSIGEN\PSIsafeAPIServer
This step ensures that PSIsafe API can connect to the database -
Copy CNGServer.XML from
C:\Program Files (x86)\CNG\CNGServer
toC:\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. -
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. Enterinstall.bat
and press Enter.
6.c. From Start Menu, launch Windows Services by typingservices.msc
and press Enter
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:
- Use Powershell 7 or later with the command below:
Remove-Service -Name "PSIGEN.PSIsafe.Service"
- 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
- Use command prompt (with Administrator privileges) with the command below:
sc delete "PSIGEN.PSIsafe.Service"
PSIsafe API Deployment
- Extract the contents of api.zip to a folder path such as C:\Program Files\PSIsafe\PSIsafeAPI
- 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\
- From the Start Menu, launch Internet Information Services by typing IIS and press Enter.
- Expand the server name on the left.
- Right-click Application Pools.
- Select Add Application Pool…
- Name Application Pool "PSIsafe"
- Right-click Default Web Site.
- Select Add Application…
- 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:
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):
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
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)
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.
- Log into server where PSIsafe Database resides (or any system where SSMS can connect
to database server) - From Start Menu, launch SQL Server Management Studio (SSMS)
- Log into SQL Server instance containing database
- From SSMS File Menu, select Open > File…
- Browse to the location containing updated PSIsafe API files
- From the db folder, select PSIsafeAPIDatabaseUpdates.1.0.18.sql
- Once query has been loaded in SSMS, select Execute from ribbon menu
- After query completes, verify the following additions to database
- New table created: dbo.SearchQuery
- New Column added to table dbo.DocumentNotes: IsAlert
Stop Services and IIS
- From Start Menu, launch Services.msc
- Select PSIGEN PSIsafe API Server and right-click
- Select Stop from context menu
- From Start Menu, launch Internet Information Services (IIS)
- Expand server name on left
- Expand Sites
- Select Default Web Site
- From Actions panel on right, select Stop
Update Server folder
- In Windows Explorer, navigate to
C:\Program Files\PSIGEN - Create a copy of the current PSIsafeAPIServer (for backup purposes)
Name copy “PSIsafeAPIServer - <current version>” - Open current PSIsafeAPIServer folder
- Delete all files and folders except for “config” folder from:
C:\Program Files\PSIGEN\PSIsafeAPIServer - Copy all files and folders except for “config” folder from the new folder
- Paste all copied files and folders into
C:\Program Files\PSIGEN\PSIsafeAPIServer
Update API folder
- In Windows Explorer, navigate to
C:\Program Files\PSIGEN - Create a copy of the current PSIsafeAPI (for backup purposes)
Name copy “PSIsafeAPI - <current version>” - Open current PSIsafeAPI
- Delete all files and folders except for “Web.config” file from
C:\Program Files\PSIGEN\PSIsafeAPI - Copy all files and folders except for “Web.config” file from the new API folder
- Paste all copied files and folders into
C:\Program Files\PSIGEN\PSIsafeAPI
Start IIS and Services
- From Start Menu, launch Internet Information Services (IIS)
- Expand server on left
- Expand Sites
- Select Default Web Site
- From Actions panel on right, select Start
- From Start Menu, launch Services.msc
- Select PSIGEN PSISafe API Server and right-click
- Select Start from context menu
Verify API upgrade successful
- From Start Menu, launch browser
- In address bar, enter
http://localhost/PSIsafe/api - Verify version displayed reflects version just installed
Comments
Please sign in to leave a comment.