AGRIS 21.1.0 Installation Instructions

Change Log

For Agris 21.1.0 please note: It may be best to use the Edge or Internet Explorer browser as the Chrome browser may block the links.

Introduction

Purpose

The Installation Instructions assist you in performing new software installations of the AGRIS System Version 21.1.0 software. Also use these instructions to upgrade AGRIS versions 10.0.0 and higher to this new version.
For information regarding running AGRIS on Microsoft SQL Server, please refer to the documentation here: AGRIS on Microsoft SQL Server

Summary of Major System Requirements - Added and Removed

The following table summarizes the major hardware (HW) and software (SW) requirements changes relating to the maintenance and support of AGRIS 21.1.0 (compared to the previous release of AGRIS).

*The installation utility checks for at least 512MB of RAM and quits if this amount is not met.

Upgrading From Previous Versions of AGRIS

Important Note:  Dataset conversions from version 9.6.x or earlier are not supported in this upgrade.  If you are upgrading from AGRIS version 9.6.x or earlier, you will first need to upgrade to version 20.3.0 with the instructions HERE.  Be sure to convert all of your datasets to version 20.3.0.  Then return to this page to continue the upgrade to version 21.1.0.

New as of V9.6.0.0: Retained Settings During Upgrade

The upgrade process in AGRIS retains certain settings from the previous version of AGRIS (such as the settings in the Agris.ini, the Installation Type, the Distribution Folder path, and the COM+ user credentials). During an upgrade installation, the installation process will skip the windows in the Installation Wizard for the retained settings since it already has that information.
If you do not want to retain your settings from the previous version of AGRIS, you can manually uninstall the previous version of AGRIS in Add/Remove Programs or the Program Manager prior to starting the AGRIS installation.

New as of V9.6.0.0: Relocation of the AGRIS startup executable

The following message will appear when upgrading from a version previous to 9.6.0.0. Please read the message carefully. Click the No button to exit the installation process. Click the Yes button to proceed with the installation process.

Removing the prior version of AGRIS

When performing upgrades, the following messages may appear. Click Yes to remove the older version of AGRIS during the upgrade.

The Remove AGRIS Message

The Remove AGRIS Client? Message

The Remove AGRIS Server Components Message

The Remove Previous Version Window
Note: The following screen may appear when removing the previous AGRIS Server components. Click Yes to remove the existing COM+ applications.

The Remove AGRIS Specific MTS Packages Message

RetailWise Customers

RetailWise customers cannot upgrade directly to AGRIS 21.1.0 and must coordinate their upgrade to Store Manager ES and AGRIS 21.1.0 with the Sales Team (800-393-0075). The AGRIS Integration Platform (AIP) for RetailWise, which is translates data between RetailWise and AGRIS, is not supported in AGRIS 9.5.0.7 and higher. Note that customers already running Store Manager ES are not impacted by this and are able to upgrade to AGRIS 21.1.0.

Tips for Minimizing Downtime During the Installation

Multiple client installations can run simultaneously.

1. 1. From a client machine, browse out to the UNC path of the Agrisdist folder
   2. Please refer to Appendix A for help on determining your Agrisdist UNC path.
   3. Perform at least the first dataset conversions on the server.
      
      

Known Installation Issues

1. When uninstalling AGRIS, a message may appear indicating "An error occurred while trying to uninstall AGRIS. It may have already been uninstalled. Would you like to remove AGRIS from the Program and Features list?"

Resolution: Click the No button on this message to proceed with the uninstall.

Pervasive SQL Database File Format Conversion

Upgrading from Previous PSQL Versions

AGRIS requires you to pre-install Pervasive® PSQL™ to manage dataset operations. Please follow the instructions at  
https://culturana.force.com/s/article/ka036000000oLocAAE/AGRIS-Installing-Actian-PSQL-v12-SP1-and-Update-3?r=1

System Requirements

Please:

• • Consult the System Requirements document before continuing to install AGRIS.
  • Verify that all computers meet or exceed the minimum system requirements.
  • Where this document refers to "Pervasive® PSQL™", be sure that you are using a supported version of Pervasive® PSQL™ for this version of AGRIS.

Technical Support

Greenstone provides support to all subscribing users of the AGRIS System Version 21.1.0. You can contact our Technical Assistance Center in the following ways:
Email:  Mysupport@culturatech.com
Phone:  (800) 366-2474
Mail:  3820 Mansell Road, Suite 375. Alpharetta, GA 30022
Website:  http://www.greenstonesystems.com/
Knowledge Base https://culturana.force.com/s/login

AGRIS Auto-Update

As a result of many requests for improving the software update process, AGRIS includes a utility for updating AGRIS client computers. This feature, called the AGRIS Auto-Update, assumes the AGRIS users/clients are running AGRIS V9.5.0.27 or greater, any updates made to the Component Server are automatically detected by the system.

Requirements

• • You must install the AGRIS System on a separate machine usually referred to as the component server. This type of configuration is usually referred to as a Network Configuration.
  • You must install the AGRIS Auto-Update utility via a UNC (Universal Naming Convention) path:

Example: \\servername\sharename\path

• • All users must have Administrator privileges for their local computers.
  • This feature is not supported on Terminal or Citrix Servers.
  • This feature is not supported on Standalone installations.

Description

When you launch AGRIS from a client machine, AGRIS compares its local version to the Component Server version. If an update is detected, it automatically prepares the update application and prompts you to decide whether or not to update the system:

The AGRIS System Update Window

1. 1. 1. Launch AGRIS from your Desktop. The installation wizard automatically launches the appropriate update from a network share.
      2. When the update is complete, you can launch AGRIS without further interruption.

Note: Depending on the state of the system, you may need to restart your workstation following the update.

Procedure

Note: AGRIS requires that you specify network locations using UNC paths.

1. 1. 1. Create a network share (Example: \\servername\apps\AGRISDIST). All users need Read permissions to this share.
      2. The network administrator should save all the installation files to this share.
      3. If an update is available (update.exe), it should be copied to the same folder that contains the setup.exe, which was created in the previous step.
      4. Install AGRIS Version 21.1.0 or later on all AGRIS servers, for example, component servers, database servers, etc. Also, apply updates, if they exist, for example, update.exe.
      5. Install AGRIS Version 21.1.0 or later on all your AGRIS workstations. The AGRIS clients are now ready to detect updates from your servers. When you receive an update from AGRIS, you only have to update your Component Server(s) and application server(s). If you have not specifically set up a Component Server(s), then we assume the database server is the Component Server.

AGRIS 21.1.0 Network Installation

Installation Checklist

Print this checklist to assist you in installing AGRIS 21.1.0.

Verify System Requirements

Please consult the AGRIS Version 21.1.0 System Requirements document before proceeding with the install. Please verify that all computers meet or exceed the minimum system requirements.
Note: The AGRIS installation will fail if minimum system requirements are not met.

Active Directory-Integrated Domain Name Service (DNS)

Active Directory-Integrated DNS is a critical piece of the infrastructure, required for the successful operation of AGRIS. The steps below are provided as a reference for installing and configuring DNS correctly:

1. 1. Install and configure DNS on the local Domain Controller (Active Directory is required on this server).
   2. Setup forwarders within DNS (if configuring for internet access).
   3. Configure the AGRIS database server, as well as all client computers, to use the local DNS server(s).

To set up DNS forwarders on the server:

1. 1. Click on Start >> Programs >> Administrative Tools >> DNS.
   2. Right-click the server and select Properties.
   3. Click the Forwarders tab.
   4. Click the Enable Forwarders option to enable the field allow the IP addresses to be entered.
   5. Enter the primary DNS server (provided by the internet service provider) and click Add.
   6. Enter the secondary DNS server (provided by the internet service provider) and click Add.
   7. Click Apply >> OK.
   8. Close the DNS window.

Setting up the padmin User Account

You must set up a local user account on the Pervasive database server.

Note: The padmin username and password are hard coded in the AGRIS application. As of the release of AGRIS V9.4.1, users can alter the padmin username and password.

The default username and password for the Pervasive Administrator account is not documented for security reasons. Please contact our Technical Assistance Center (800-366-2474) for this information. Once AGRIS is open:

1. Click Customize Menu.
2. Click Database Security Configuration to display the message: New User and Password must exist on database server and the user must be a member of the local Administrators Group.
3. Contact our Technical Assistance Center (800-366-2474) for an access code to enter in the Database Security Configuration window.
4. Type the access code in the Access Code field.
5. Press Enter or Click OK to display the User Name and Password window.
6. Enter the username and password for the Pervasive Administrator account.
7. Click Save.
8. Exit AGRIS.

When starting AGRIS for the first time, you may encounter some errors, caused by the system not knowing the padmin username and password you have set up. If this occurs:

1. Go to Start >> Settings >> Control Panel.
2. Open Administrative Tools.
3. Open Computer Management.
4. Browse to Local Users and Groups and expand.
5. Click Users.
6. Click Action >> New User or right-click Users and select New User.
7. Type a username (Typically padmin). The Full name and Description are optional.
8. Type a password.
9. Check the following options:
   • User cannot change password
   • Password never expires
10. Click Create, and then Close.
11. Right-click the user created in step 7 and click Properties
12. Click the Member Of Tab and click Add... and type Administrators then click Check Names followed by OK
13. Click OK again
14. Close Computer Management, Administrative Tools and Control Panel.

Assigning Log on Rights

If the AGRIS server is also a Domain Controller, then the padmin user account must be a domain user instead of a local user and made a member of the Builtin Administrators group. 

Creating a COM+ Services User Account

This user account is used to start the COM+ services. This account needs administrative permissions to the server that the COM+ components are running on.

1. Go to Start >> Settings >> Control Panel.
2. Open Administrative Tools.
3. Open Active Directory Users and Computers.
4. Click Users.
5. Click Action >> New User or right-click Users and select New User.
6. Type a username. (Typically services) The Full name and Description are optional.
7. Type a password.
8. Check the following options:
   • User cannot change password
   • Password never expires
9. Click Create, and then Close.
10. Click the new user account.
11. Choose Action >> Properties or right-click the user and select Properties.
12. Click the Member Of tab.
13. Click Add.
14. Browse to and select Administrators.
15. Click Add.
16. Click OK to add this user to the group.
17. Click OK to finish working with this user account.
18. Close Active Directory Users and Computers.

Setting up Network COM+ Access

Windows Server 2016, Windows Server 2019

There are no steps needed for Windows Server 2016 and Windows Server 2019. The AGRIS installation enables this feature programmatically by setting the following registry entry.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\COM3
Name:  RemoteAccessEnabled
Type:  REG_DWORD
Data: 0x00000001 (1)

Windows Server 2012 R2

1. On the Component Server, typically the database server, click Start and type "Server Manager", then click on the Server Manager.
2. Click on the Local Server in the selection tree.
3. Scroll down to the ROLES AND FEATURES section
4. In the TASKS dropdown, select Add Roles and Features
5. On the Before you begin step, click Next
6. On the Select installation type step, select Role-based or feature-based installation and click Next
7. On the Select destination server step, ensure your server is selected and click Next
8. On the Server Roles step, expand the Application Server option, checkmark COM+ Network Access, and click Next
9. On the Features step, click Next
10. On the Confirmation step, click Install
11. Once the installation is complete, click Close to close the Add Roles and Features Wizard.

Granting Access to Component Services

Windows Server 2012 R2, Windows Server 2016, Windows Server 2019

1. On the Component Server, typically the database server, click Start and type "Server Manager", then click on the Server Manager.
2. From the Tools menu, select Component Services
3. Double-click Component Services >> Computers.
4. Right-click My Computer >> Properties.
5. Click the Com Security tab.
6. Click Edit Limits for the Launch and Activation Permissions.
7. Click the Everyone group.
8. Check the Remote Launch and Remote Activation options.
9. Click OK >> OK.
10. Close Component Services.

Creating the Installation and Distribution Folders

Prior to installing AGRIS on the database server, you must create the following folders:

If choosing folder names other than those specified above, be aware that the name of the directory where the software is installed (typically the AGRIS folder) cannot exceed eight characters.
Review Section 2.11 , below, for detailed information on setting up these folders.

Setting up the Recommended Directory Structure

To set up the installation and distribution folders in accordance with AGRIS standards, please perform the following steps:
Create the Apps folder:

1. 1. Double-click My Computer.
   2. Double-click the drive where the AGRIS data will reside (typically C: unless another, larger partition exists on the server).
   3. Click File >> New >> Folder.
   4. Type Apps as the name of the new folder and press [Enter].
   5. Double-click the Apps folder to open it.

Create the AGRIS folder:

1. 1. Click File >> New >> Folder
   2. Type AGRIS as the name of the new folder and press [Enter].

Create the Agrisdist folder:

1. 1. Click File >> New >> Folder
   2. Type Agrisdist as the name of the new folder and press [Enter].

Assigning Permissions for File Access

There are two levels of security involved with running AGRIS:

• • Windows Network Security.
  • AGRIS System Security (optional).

This section deals with Windows Network Security. For information on AGRIS System Security, launch AGRIS >> Help >> System Manager Help and search for SYSTEM SECURITY.
Active Directory networks are configured to allow Domain Users to access the AGRIS files:
Note: These are basic instructions for creating a shared folder in Windows. Consult with your system administrator to determine if you should create this share through the Server Manager application.

1. 1. Right-click Apps >> Sharing and Security…
   2. Click "Share this folder".
   3. Click Permissions>>Add.
   4. Type Domain Users and click Check Names (Domain Users should now be underlined indicating that this group was successfully located).
   5. Click OK.
   6. With Domain Users selected, put a check for Change in the Allow column.
   7. Click Apply >> OK.
   8. Click the Security tab >> Add.
   9. Type Domain Users and click Check Names (Domain Users should now be underlined indicating that this group was successfully located).
   10. Click OK.
   11. With Domain Users selected, check the Full Control option in the Allow column.
   12. Click Apply >> OK.

In environments where access to the data is more tightly controlled, use the following information to restrict access to AGRIS:

Disabling Offline File Synchronization

Offline File Synchronization, a feature of Windows which enables users to synchronize files between their local workstations and the network, can cause severe problems with database applications. Disable the Offline File Synchronization in the Apps folder to prevent any file synchronization from occurring.

Windows Server 2012 R2, Windows Server 2016, Windows Server 2019

1. Double-click My Computer > C: (or the drive where the Apps folder resides).
2. Right-click the Apps folder >> Properties
3. Click on the Sharing tab
4. Click Advanced Sharing… button.
5. Click Caching button.
6. Click No files or programs from the shared folder are available offline
7. Click OK >> OK >> Close

Backing up AGRIS Data

Backing Up Open Database Files

Occasionally, if users fail to completely exit from AGRIS prior to running the backup routine, the backup software fails to completely back up the AGRIS datasets. Due to the file relationships that AGRIS maintains, the resulting, partially backed up datasets are often not useable if you need to restore the entire dataset.
To minimize this problem, an open file agent, such as Pervasive Backup Agent™, is recommended. Backup Agent increases the chances of a successful backup if files are held open while the backup is running and is compatible with most backup solutions. For additional information about the Pervasive Backup Agent, please contact the Technical Assistance Center (800-366-2474).

Automated Blender Setup

Starting with AGRIS V9.5.0.9, the Automated Blender Setup procedure now requires the assignment of an AGRIS dataset user, which allows the Auto Blender service to log on to and load session information relative to the dataset.

1. Stop the Auto Blender services.
2. If you have not already done so, convert your first dataset to AGRIS 21.1.0.
3. From the AGRIS Main Menu, select AGY >> General Setup >> Automated Controls to display the Automated Blender Setup window.
   

   
   The Automated Blender Setup Window

4. For each Auto Blender:
   1. Click the button to the right of the Auto Blender field to select an automated blender from the list.
   2. Click the button to the right of the AGRIS User field to select a user from the list. Be sure to select an AGRIS user with password permissions set to Never Expire.
   3. Click Apply to apply the changes.
5. When you finish assigning users, click OK to close the Automated Blender Setup window.
6. Restart the Auto Blender services.

Downloading the AGRIS 21.1.0 Installation Program

1. From the console of the server or standalone unit, click Start >> Run…
2. Type  https://culturana.force.com/  >> click OK.  (NOTE: It may be best to use the Edge or Internet Explorer browser as the Chrome browser may block the links).
3. Log on to the website
   1. If you are not already signed up for a user account, you can click the "Register" link to sign up. Account applications are reviewed and approved within 8 business hours.
4. Click search for the AGRIS 21.1.0 is Available Article and the Download setup.exe link for AGRIS 21.1.0.
5. Click Save when the "Do you want to run or save this file?" message displays.
6. On the left side of the window, click Desktop, and then click Save on the bottom, right side to download the update (which may take a few minutes).
7. WARNING: Due to enhanced security features in Windows, please ensure that the installer is unblocked prior to installation using the following steps:
   1. Right-click on the downloaded installation file and click Properties
   2. At the bottom of the General tab, look for a button that says "Unblock"
      1. If the button exists, click Unblock and then click OK
      2. If the button does not exist, click Cancel
8. If necessary, you can request an AGRIS 21.1.0 CD from the Technical Assistance Center (800-366-2474) or by emailing Mysupport@culturatech.com.

Configuring Anti-Virus Software

AGRIS is compatible with a variety of anti-virus solutions, but additional configuration reduces the negative performance impact that the real-time anti-virus scanning may cause. Modify your real-time file scanning to exclude the entire AGRIS directory and sub-directories. Failure to configure the anti-virus properly may cause intermittent errors within AGRIS.
Real-time scanning also increases the time needed to install, or update to, AGRIS and PSQL, and may even prevent PSQL from installing. To alleviate both issues, temporarily disable real-time file scanning during the installation.
Please consult the anti-virus documentation for instructions on how to exclude files and folders from the real-time scan and to temporarily disable the real-time file scanning.

Server Installation

AGRIS Server Installation Checklist

Install components in the following order:

AGRIS 21.1.0 Server Installation

This section describes how to install the AGRIS System Version 21.1.0 software in the supported configurations listed in the AGRIS System Requirements document. It assumes that all hardware and supporting software requirements are in place and operational.
The following prerequisites must be satisfied:

Note:The software installation folder name cannot be longer than eight characters.

If this installation is performing a software upgrade from a previous version of the AGRIS Business System, the following prerequisites must also be satisfied:

Note: The existing version of the AGRIS System must be version 10.1.0 or higher. No earlier versions of the software can be directly upgraded to Version 21.1.0.

• • Ensure that you have a complete backup of your current version's software and data.
  • Purge any unnecessary data files to enhance dataset conversion performance.

Server Installation Procedure

• Installing the .NET Framework:

  • For Windows Server 2012 R2 and Windows Server 2016 and Windows Server 2019, part of the .NET Framework must be installed through the Server Manager:

    • Click Start and type "Server Manager", then click on the Server Manager.

    • Click on the Local Server in the selection tree.

    • Scroll down to the ROLES AND FEATURES section

    • In the TASKS dropdown, select Add Roles and Features

    • On the Before you begin step, click Next

    • On the Select installation type step, select Role-based or feature-based installation and click Next

    • On the Select destination server step, ensure your server is selected and click Next

    • On the Server Roles step:

      • For Windows Server 2012 R2: checkmark Application Server, click Next

      • For Windows Server 2016: click Next

    • On the Features step, checkmark the .NET Framework 3.5 Features option. Checking this will automatically check the .NET Framework 3.5 (includes .NET 2.0 and 3.0) option. For AGRIS, you do not need to checkmark the options for HTTP Activation. Click Next until you are on the Confirmation step.

    • On the Confirmation step, click Install

    • Once the installation is complete, click Close to close the Add Roles and Features Wizard.

    • Close the Server Manager.

    • Proceed with the next step in the AGRIS installation

  • For all other supported Server operating systems, there are no extra steps for the .NET Framework.

• Open the Agrisdist network share created in section 2.10
• Open the Setup.exe:
  • Right-click the Setup.exe and choose Run as Administrator. If there is a User Account Control message, click Allow.
• If the computer does not have version 4.7.2 of the .NET Framework installed, the installation process will prompt to install it. Click Install to start the installation. This process can take several minutes to complete.  You will be prompted to reboot after this. You can choose to reboot now or later, however rebooting after the .NET Framework installation is mandatory before proceeding with the remainder of the AGRIS installation. Reboot and then log back in as the same user, and the AGRIS installation will automatically continue.

The .NET Framework Installation Window

• The Installation Wizard will appear.

The Installation Wizard

• The AGRIS Setup window will appear.

The AGRIS Setup Window

• Click Server to display the Choose Distribution Folder window.

The Choose Distribution Folder Window

• Click Browse to display the Choose Folder window.
• Navigate to the UNC path of the Agrisdist folder defined previously in Section 2.11 (i.e. \\servername\Apps\Agrisdist).
• Click OK to close the Choose Folder window and return to the Choose Distribution Folder window.
• Click Next to display the Welcome window.

The Welcome Window

• Click Next to display the Choose Destination Location window.

The Choose Destination Location Window

• Click Browse to re-display the Choose Folder window.

The Choose Folder Window

• Navigate to the AGRIS folder defined previously in Section 2.11 (i.e. C:\Apps\AGRIS). This path must be a path that begins with a local drive letter; a UNC path is not allowed.
• Click OK to accept your changes.
• Click Next to display the COM+ User Identity window.

The COM+ User Identity Window

• Type your user name in the Username field. Ensure you prefix your domain to the username, as in DOMAIN\USERNAME
• Type your password in the Password field.
• Retype your password in the Verify field to verify it is correct.
• Click Next to continue. If the two password entries do not match, a message appears:

The Password Mismatch Message

• Click OK to return to the password fields and correct the mismatch.
• Click Next to continue.
• The AGRIS Setup process will proceed.
• The installation proceeds automatically until the Installation Complete window appears. This process may take several minutes to complete.

The Installation Complete Window

• AGRIS requires that you restart your computer following installation to allow the installed components to run properly.
  • Select the Yes, I want to restart my computer now option.
  • Click Finish.

• The Optimization Settings window will appear. See Section 14.9 for more information about the Optimization Settings. Click Yes to apply the recommended settings, otherwise click No to proceed.