1 ATIPXpress Collaboration Deployment Introduction
The purpose of this document is to provide instructions for deploying Collaboration within your ATIPXpress environment.
The ATIPXpress Collaboration facilitates document reviews with users outside of your ATIPXpress environment. With Collaboration, AX users can send document requests to outside users, and responsive documentation provided in response can be added to your AX Document Management and in subsequent request responses.
1.1 Important Notes for v11.8.0 Upgrades
We’ve made significant changes to the deployment process for Collaboration v11.8.0. These changes apply to new and upgrading customers.
The inputs.json file used for previous installations CANNOT be used to upgrade to v11.8.0. There is a new file for this deployment included in the installation package. You must use this new file for the upgrade, however you can copy data over from a previously used file to the new one as needed.
If your organization is using the new Document Management features, a few additional configuration steps are required. You’ll need to manually create and configure the PNG cache location (Administration > System Administration > System Settings), and add all the required system jobs to the scheduler (Administration > System Administration > Scheduler Configuration).
1.2 About This Document
This manual is intended to guide system administrators through the required steps to deploy ATIPXpress Collaboration within their organization, including both new installations and upgrades.
1.3 ATIPXpress Collaboration Installation Package
The ATIPXpress installation package is a zip file containing all the files needed to install ATIPXpress Collaboration. Your customized installation is driven by the values set in the Inputs.Json file located at the root of directory where the zip file is extracted.
Contact Casepoint support at support@Casepointtech.com for your installation package.
1.4 Deployment Procedure
Deploying ATIPXpress Collaboration follows the procedure outlined below. Each step is covered in the subsections in this manual.
Download and verify the installation package, then extract the files.
Update the Inputs.json file with your deployment details.
Run Install.ps1
2 Collaboration Installation Prerequisites
2.1 Deployment Requirements
While the ATIPXpress deployment package (and this manual) are designed to be usable by anyone, we recommend that installation be completed by an experienced system administrator, as knowledge about your organization’s architecture are necessary to execute this deployment. It is important to check the person doing the installation has the level of access and the accounts specified in the Inputs.json have the access level needed for upgrading or installing the application, databases and services specified.
The installation package must be deployed from the application server, which must meet the requirements outlined below:
Requirement | Description |
|---|---|
Location | Deployment scripts can be executed from Application server. The script must be executed from application server if the Application or Scheduler are installed. |
User Permissions | The logged-in user should have the local administrator permissions. |
Operating System Requirements | Windows 2016/2019/2022 |
Microsoft .NET Framework 4.8 Runtime | Microsoft .NET Framework 4.8 Runtime must be downloaded and installed. It can be downloaded and installed from the following location: https://dotnet.microsoft.com/en-us/download/dotnetframework/net48 |
SqlPackage | The SqlServer module must be downloaded and installed on the application server. See the Install SQL Server Module section for steps. |
Requirement | Description |
|---|---|
SqlServer | SqlServer must be downloaded and installed. It can be downloaded from the following location: https://www.powershellgallery.com/packages/Sqlserver/21.1.18256 |
PowerShell Version | PowerShell 5.1.22621.963 must be installed for deployment using auto deployment. https://www.microsoft.com/en-us/download/details.aspx?id=54616 |
Microsoft Visual C++ Redistributable | The Microsoft Visual C++ Redistributable must be downloaded and installed on the application server for all new FX installs. (!!) Note: Both executables below must be downloaded and installed. https://download.microsoft.com/download/1/6/5/165255E7-1014- 4D0A-B094-B6A430A6BFFC/vcredist_x86.exe https://download.microsoft.com/download/1/6/B/16B06F603B20-4FF2-B699-5E9B7962F9AE/VSU_4/vcredist_x86.exe |
2.2 Install SQL Server Module
Follow the steps below to install the SQL Server Module on the application server:
Navigate to the following link: https://www.powershellgallery.com/packages/Sqlserver/21.1.18256
Under Installation Options, select Manual Download:
Click Download the raw nupk file. The SQLserver .nupkg file downloads.
Locate the downloaded "SQLserver” file, then right click it and select Properties.
On the General tab, select Unblock, then click Apply.
Next, edit the “SQLserver” file extension from .nupkg to .zip.
Extract the .zip package in the downloaded location. After the folder is extracted, remove “sqlserver.” from the folder name:
Navigate to C:\ProgramFiles\WindowsPowerShell\Modules and create a folder called SqlServer.
Copy the renamed .zip folder from the downloaded location to the SqlServer folder created in the previous step (C:\ProgramFiles\WindowsPowerShell\Modules\SqlServer)
2.3 Account Permissions
Ensure the following accounts are granted full permissions as outlined below:
Account | Description |
|---|---|
Application App Pool Account | This is the account used for app pool of the application in IIS. |
Scheduler Service Account | This is the account used as the service account for Scheduler Windows service. |
The above accounts must have full access to the file share path configured as the file repository location. The following folders will be created by the deployment tool under this file repository location (for on-prem deployments only). For AWS and Azure, the following folders should be manually created in the file repository location before running the deployment tool.
The following table summarizes the permissions required on the subfolders in the file repository location.
Location | Access Type | Comments |
|---|---|---|
\AFXWDOCS | Modify, Read & Execute, List Folder Contents, Read, Write | All ATIPXpress original are stored in this location. |
\AFXWCORL | Modify, Read & Execute, List Folder Contents, Read, Write | All ATIPXpress correspondence documents are stored in this location. |
\AFXWDOFL | Modify, Read & Execute, List Folder Contents, Read, Write | All ATIPXpress web download documents are stored in this location. |
\AFXWERR | Modify, Read & Execute, List Folder Contents, Read, Write | All ATIPXpress electronic reading room documents are stored in this location. |
3 Download the Installation Package
The Collaboration installation package contains the files needed to install ATIPXpress and its associated components. Contact Casepoint support at support@Casepointtech.com for your installation package.
After downloading the package, follow the steps below to unzip the file:
Locate the downloaded .zip file, then right click it and select Properties.
On the General tab, select Unblock, then click Apply.
Next, unzip the contents of the folder. The contents of the package appear as shown in the following example:
3.1 Verify the Integrity of the Installation Package
Steps to verify the integrity of the installation package.
Open Windows Powershell ISE.
Use the command below to verify the integrity of installation package:
Test-FileCatalog -CatalogFilePath "<<catalog file path(with extension of .cat) from downloaded artifact>>" -Path "<< folder that should be validated against the catalog file >>"
It will show as valid, as shown in the following example:
3.2 About the Installation Package
There are two primary files you’ll interact with during installation:
Inputs.json: Drives the installation of the Collaboration components. The file is in a standard json format and needs to remain a valid json file for successful installation.
Install.ps1: The executable file you will run to deploy the installation package with the parameters configured in the Inputs.json file.
4 Inputs.json Settings for Installation
4.1 About the Inputs.json File
The Inputs.json file located in the root directory of the extracted deployment package zip file drives the installation of the different components of the ATIPXpress Collaboration. The file is in a standard json format and needs to remain a valid json file post updates prior to the installation.
The settings are grouped into sections, each addressing settings which may or may not require configuration, depending on your specific installation. The following subsections in this chapter describe each section of the Inputs.Json file.
The parent node is the ‘inputs’ section. This section appears as follows:
Each section has parameters you can adjust to configure your installation. An example section is shown below, with an explanation for how it works:
Each (1) Section (“InstallType” in this example) includes various (2) Settings (“New” in this example) to configure.
For each (A) Setting (“Upgrade” here), you can edit the (B) text in quotations (“N” here to indicate “No”) to configure the settings for your installation. This might include adding a file path, user name, password, or simply a “Y” or “N” depending on the field you are configuring.
The first section under the parent node is the Install Type. See the following section for details on configuring your install type, with the remaining sections following in the order they appear in the Inputs file.
4.2 Install Type
Use the “InstallType” section to determine if this is a new installation, or an upgrade for an existing system:
Setting | Description |
|---|---|
New | Determine whether this is a new installation. For new installations this should be a “Y” value |
Upgrade | Determine whether this is an upgrade for an existing application. For new installations this should be a “N” value |
4.3 Install Components
The “Components” section allows you to determine which components to include with this installation. To include a component with your installation, be sure to assign the component a “Y” value on the corresponding line.:
Setting | Description |
|---|---|
APP | Include ATIPXpress Collaboration in this installation procedure. This should be a “Y” value for new installations and upgrades if the applications needs to be installed or upgraded respectively. |
SCHEDULER | Include ATIPXpress Collaboration Scheduler in this installation procedure. This should be a “Y” value for new installations and upgrades if the scheduler needs to be newly installed or upgraded respectively. |
DB | Include the ATIPXpress Collaboration Database in this installation procedure. This should be a “Y” value for new installations and upgrades if the database needs to be newly installed or upgraded respectively |
4.4 Application and Scheduler
The “APPANDSCHEDULER” section has settings related to the Collaboration application and scheduler installations. A value must be set for all values in this section to successfully install the application:
Note: Any file paths specified must have two backslashes where a path in windows explorer requires a single backslash.
Setting | Description |
|---|---|
InstallLocation | Specify a path for the Collaboration installation. Note this must be a file path for the .json file the execute. |
BackupLocation | Specify a path for the Collaboration backup location. Note this must be a file path for the .json file the execute |
SSLCert | The following lines contain the SSL Certificate information. No data is required on this line. This is the grouping for SSL Certification settings to be used for the installation. |
SSLPort | The network port designated for your application’s secure communications using SSL. |
CertPath | Specify a path where the .pfx certificate file is located. Note this must a file path for the .json file to execute |
CertPassword | Enter the password associated with the certificate linked in the “CertPath” field |
DNSName | Enter the Domain Name System (DNS) name for the domain associated with the application. |
AppPool | Enter the name of the application pool associated with your ATIPXpress Collaboration, |
4.5 Database Settings
The “DB” section contains the settings for installing or upgrading your Collaboration database.
In case of a new installation, an agent account will be created.
Setting | Description |
|---|---|
DBServer | Name assigned to the server responsible for storing, retrieving, and managing Collaboration data |
DBName | Name given to the specific database used for ATIPXpress Collaboration |
CreaterDBUserID | Database User ID to be used for this installation. The CreaterDBUserId should have admin rights with the ability to create a new database or database object on the specified Database server |
CreaterDBUserPassword | Password associated with the account used in the “CreaterDBUserID” field |
IntegratedSecurity | The Integrated Security property instructs the SQL Client to connect to SQL Server using Windows Authentication through the Security Support Provider Interface (SSPI). Use “Y” or “N” to determine if you are using Integrated Security in this installation. |
AgentAccount | The SQL server login account to be created in case of a new database install or the login already setup for the database being upgraded |
Setting | Description |
|---|---|
AgentAccountPassword | The SQL server Agent Account password specified in the AgentAcount setting |
AgentAccountIntegratedSecurity | Whether integrated security should be used when connecting to the database, default is “N” |
4.6 File Repository Settings
The “FileRepository” section contains the setting for different file paths used by Collaboration to store files.
Setting | Description |
|---|---|
Documents | Enter the file path location for the Documents repository. |
Correspondence | Enter the file path location for the Correspondence repository |
4.7 Authentication Settings
The “Authentication” section contains settings needed for ATIPXpress to authenticate using FORMS authentication after the application is installed:
Setting | Description |
|---|---|
Type | Enter the type of authentication used. Options include FORMS, SSO, and EAUTHENTICATION. |
Type Comment | Lists the authentication Types that can be entered in the field above (FORMS, SSO, and EAUTHENTICATION). |
Forms | The Forms authentication fields are listed in this subsection. These only need to be filled in if using FORMS authentication. |
MembershipProvider | Enter the membership provider type. Options include DATABASE or LDAP. |
MembershipProvider Comments | Lists the membership provider types that can be entered in the field above (DATABASE or LDAP). |
LdapAccountUsername | Username associated with the LDAP account used for authentication. |
Setting | Description |
|---|---|
LdapAccountPassword | Password associated with the LDAP account username used in the field above. |
LdapUrl | URL associated with the LDAP server |
LdapSynchronizeAdUsersUserName | LDAP User Name |
LdapSynchronizeAdUsersPassword | LDAP Password |
LdapSynchronizeAdUsersUrl | LDAP URL |
eAuthentication | eAuthentication details are included in this subsection (if eAuthentication is the selected authentication type). |
eAuthenticationLogoutUrl | Redirect URL for users when logged out using eAuthentication. |
4.8 SMTP Server Settings
The “SMTPServer” section contains setting for the application’s mail server:
Setting | Description |
|---|---|
Address | Address of the server responsible for sending email messages from the ATIPXpress application. |
Setting | Description |
|---|---|
PortNo | Port number associated with the SMTP server entered in the “Address” setting |
4.9 Configuration
The “Configuration” section contains settings for initial install configuration, setting up the basic details required to log in and get started in Collaboration. This account is the primary administrator account for the application:
Setting | Description |
|---|---|
AdminUser | This subsection allows you to configure the basic details and sign in information for the initial Admin user account you’d like to create in the system. |
Setting | Description |
|---|---|
Login | Enter the username you’d like to assign for the first Admin application user. |
Password | Enter a password for the Admin account associated with the username you entered above. |
FirstName | Enter the first name you’d like to associate with this Admin account |
LastName | Enter the last name you’d like to associate with this Admin account |
Enter an email address for this Admin account. | |
Organization | Use this subsection to provide your basic organization details. |
Name | Enter a name for your organization, as it should appear in the system. |
OfficeName | Provide an initial office name for an organization office. You’ll be able to add more offices in the application configuration. |
OfficeCode | Enter a system code assigned to this office, to assist with request identification and assignment. |
FiscalYear | Use this subsection to configure the fiscal year details for your application |
CurrentFY | Enter the current fiscal year used in your application in “YYYY” format (e.g., “2023”) |
Starts | Provide a start date for your fiscal year in MM/DD/YYYY format (e.g., “01/01/2023”) |
Setting | Description |
|---|---|
Ends | Provide an end date for your fiscal year in MM/DD/YYYY format (e.g., “12/31/2023”) |
ActType | This field is not applicable for ATIPXpress. Do not edit or remove this field. |
ATIAPA | This field is not applicable for ATIPXpress. Do not edit or remove this field. |
FOIP | This field is not applicable for ATIPXpress. Do not edit or remove this field. |
FIPPA | This field is not applicable for ATIPXpress. Do not edit or remove this field. |
5 Inputs.json Settings for Upgrade
This section discusses the inputs.json settings used when upgrading an existing AX
Collaboration. For information on using the inputs.json file, see the About the Inputs.json File section of this manual.
Note: Some fields that would be required for a new installation should be left as-is for an upgrade. It is important to not edit or remove these fields as this could compromise the integrity of the inputs.json file. These are described where appropriate in the following sections.
5.1 Install Type
Use the “InstallType” section to determine if this is a new installation, or an upgrade for an existing system:
Setting | Description |
|---|---|
New | Determine whether this is a new installation. For upgrades this should be a “N” value |
Upgrade | Determine whether this is an upgrade for an existing application. For upgrades this should be a “Y” value |
5.2 Components
The “Components” section allows you to determine which components to include with this upgrade. If you included a component in your previous installation, be sure to assign the component a “Y” value on the corresponding line:
Setting | Description |
|---|---|
APP | Include the Collaboration application in this upgrade procedure. This should be a “Y” value for upgrades. |
SCHEDULER | Include the Scheduler in this upgrade procedure. This should be a “Y” value for upgrades if the scheduler needs to be upgraded. |
DB | Include the Database in this upgrade procedure. This should be a “Y” value for upgrades. |
5.3 Application and Scheduler
The “APPANDSCHEDULER” section only requires input in the InstallLocation and BackupLocation fields.
(!!) Note: All fields not listed above can remain as-is during an upgrade.
Setting | Description |
|---|---|
InstallLocation | Specify a path for the application installation. Note this must be a file path for the .json file the execute. |
Setting | Description |
|---|---|
BackupLocation | Specify a path for the application backup location. Note this must be a file path for the .json file the execute. (!!) Note: The BackupLocation must exist in the specified file path |
5.4 Database Settings
The “DB” section contains the settings for installing or upgrading your Collaboration database.
Note: You do not need to edit the AgentAccount fields during an upgrade, these can remain as-is.
Setting | Description |
|---|---|
DBServer | Name assigned to the server responsible for storing, retrieving, and managing Collaboration data |
DBName | Name given to the specific database used for Collaboration. |
CreaterDBUserID | Database User ID to be used for this installation. The CreaterDBUserId should have admin rights with the ability to create a new database or database object on the specified Database server |
Setting | Description |
|---|---|
CreaterDBUserPassword | Password associated with the account used in the “CreaterDBUserID” field |
IntegratedSecurity | Use “Y” or “N” to determine if you are using integrated security in this installation |
5.5 File Repository Settings
The “FileRepository” section contains the setting for different file paths used by the ATIPXpress application to store files.
Note: These fields can remain as-is during the upgrade.
5.6 Authentication Settings
The “Authentication” section contains settings needed for ATIPXpress to authenticate using FORMS authentication after the application is installed. These fields can remain as-is during the upgrade.
Note: These fields can remain as-is during the upgrade.
5.7 SMTP Server Settings
The “SMTPServer” section contains setting for the application’s mail server. These fields can remain as-is during the upgrade.
Note: These fields can remain as-is during the upgrade.
5.8 Configuration
The “Configuration” section contains settings for initial install application configuration, setting up the basic details required to log in and get started in the application. This account is the primary administrator account for the application.
Note: These fields can remain as-is during the upgrade.
6. Install Collaboration
Before you are ready to run the Install.ps1 file, review the steps below to verify you’ve completed all the steps to this point:
Ensure your system meets the minimum requirements.
Make sure you have connectivity to the servers where the software is being installed.
Download, verify, and extract the Collaboration Installation package.
Configure the Inputs.json file for your installation.
Once the above prerequisites are complete, follow the steps below to deploy the Collaboration Installation package.
Open Windows Powershell ISE
Use PowerShell to navigate to the location where you extracted the installation package:
Type .\install.ps1 for either install or upgrade
If the inputs.json file is in same location as the extracted installation files, simply click enter to execute the installation. Alternatively, if you have file in different location provide this file location, then execute the script.
The installation procedure executes. See the following section for post-installation procedures to verify the application deployed successfully.
7. Post-Deployment Configuration
After deploying Collaboration either via new installation or an upgrade of an existing environment, please review the following sections to ensure the post-deployment configuration actions are completed.
7.1 Set HTTPS-enabled URL
From v11.3.0 onward, the Collaboration URL requires an HTTPS endpoint.
Note: Use a fully qualified domain name while configuring the HTTPS endpoint in the Collaboration Room URL.Follow the steps below to update the endpoint to HTTPS:
Access your ATIPXpress application as an Administrator.
Click the Administration option from the top toolbar.
Under Administration, select the Collaboration Room option to open the Collaboration Configuration screen.
Locate the Collaboration Room URL field, and update the URL to your HTTPS-enabled URL:
Click Save to save the changes.
7.2 Add DNS Binding
For non-public Collaboration environments, you are also required to add a DNS binding to allow Collaboration to function correctly.
Post-Deployment Configuration
7.2.1 Add Binding (Single Server)
If your Collaboration resides on the same server as your ATIPXpress application, you must add a DNS binding to the “hosts” file. Follow the steps below to add this binding.
On the application server, locate and open the “hosts” file (C:\Windows\system32\drivers\etc\).
In the “hosts” file, add the text shown below, replacing the highlighted portion with your qualified DNS name for the Collaboration site:
Save and close the “hosts” file.
7.2.2 Add Binding (Separate Collaboration and Application Servers)
If your Collaboration and application reside on separate servers as your ATIPXpress application, you must add a DNS binding to the “hosts” file as described below:
On the ATIPXpress application server, locate and open the “hosts” file (C:\Windows\system32\drivers\etc\).
In the “hosts” file, add the text shown below, replacing the part (A) with your
Collaboration site’s local IP address, and part (B) with your qualified DNS name for the Collaboration site:
Save and close the “hosts” file.
33