Description

This document provides instructions for installing the ProCalV5 Agent software on a Windows operating system.



Prerequisites



Installation

Step 1: Download the Agent software mediator-agent-1.0.0.zip 

Step 2: Extract the archive to a folder, example: mediator-agent-1.0.0

Step 3: Set an environment variable called AGENT_HOME to point to where the Agent software is installed


How to Set AGENT_HOME:

Right click My Computer and select Properties.

On the Advanced tab, select Environment Variables, and then add AGENT_HOME to point to where the Agent software is located, for example, E:\mediator-agent-1.0.0


Step 4: Open a Command Prompt as an Administrator and use cd command to change directory to mediator-agent-1.0.0/bin,

Run the following command to configure Mediator public key and to generate Agent public & private keys

agent_installer.bat



Step 5: Login to your Organization's PCX account and navigate to the Agent area. Copy and paste the mediator public key from Agent Configuration into your command prompt.

See below screen shot of agent configuration with mediator public key displayed.



After mediator public key is pasted, press enter key.



Mediator public key is saved and script will generate Agent public and private keys as well. You will see the “Public Key” displayed in the resulting message.



Step 6Copy and paste the public key in the Organization's Agent Configuration page.



Click “Save Agent Key” button


Step 7: After agent keys are successfully generated, user is prompted to enter Agent ID



Login to your Organization's PCX account and navigate to the Agent area



Copy and paste Agent Id from Agent Configuration into your terminal, and press enter key. Agent ID is saved, and then user is prompted to enter Agent Queue name.



Copy and paste Agent Queue from Agent Configuration into your terminal, and press enter key.



Agent Queue name is saved.

 

Step 8: User is prompted to enter Agent Storage name

Copy and paste Agent Storage from Agent Configuration into your terminal, and press enter key.  User should see Agent Storage is successfully saved.



IMPORTANT: Ensure that the key information in mediator-agent-1.0.0/conf is kept secure to prevent issues or data tampering with your PCX service.


Step 9: Below is the ProCalV5 database configuration for Oracle. Skip this step, if SQL Server is used

Edit procal-agent.properties, add the below properties and configure ProCalV5 database connection details (host, port, database name, user name and password)


procal.host=[DB Host]
procal.port=[DB Port]
procal.driverClassName=oracle.jdbc.OracleDriver
procal.databaseName=[Database Name]
procal.username=[DB user name]
procal.password=[DB password]
  
spring.datasource.driver-class-name=${procal.driverClassName}
hibernate.dialect=dialect.CustomOracle10gDialect
#Below spring.datasource.url configuration should be all on one line
spring.datasource.url=jdbc:oracle:thin:${procal.username}/${procal.password}@${procal.host}:${procal.port}:${procal.databaseName}
 

After completing this step, procal-agent.properties configuration should be similar to as shown below

Step 10: Below is the ProCalV5 database configuration for SQL Server. Skip this step, if Oracle database is used

Edit procal-agent.properties, add the below properties and configure host, port, database name, database instance, user name and password details



procal.host=[DB Host]
procal.port=[DB Port]
procal.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
procal.databaseName=[Database Name]
procal.databaseInstance=[Database Instance Name]
procal.username=[DB user name]
procal.password=[DB password]
  
hibernate.dialect=org.hibernate.dialect.SQLServer2012Dialect
spring.datasource.driver-class-name=${procal.driverClassName}
#Below spring.datasource.url configuration should be all on one line
spring.datasource.url=jdbc:sqlserver://${procal.host}:${procal.port};databaseName=${procal.databaseName};instance=${procal.databaseInstance};user=${procal.username};password=${procal.password}



After completing this step, procal-agent.properties configuration should be similar to as shown below



Step 11: Configure Mobile File Transfer (if applicable)

ProCalV5 - "Export" which is creating/populating an Access MDB file. The default name for this file is PCMobile5.mdb but that can vary depending on user's use case.


In particular if there is a path, for example, 


    P:\Exports\PCMobile5.mdb 

which is really 


    \\SOME FILE SERVER\SOME SHARE\Exports\


a. To export mobile files, edit procal-agent.properties and configure mapped drive letter and its actual server share path

  • Configure mapped drive letter



                        mobile.export.local.mapped.drive= P:\

Note: Driver letter should end with colon and slash

                        

  • Configure server share path

           mobile.export.network.server.share=\\SOME FILE SERVER\SOMESHARE\


b. To import mobile files, edit procal-agent.properties and configure import file path

  • Configure mobile file path

                        mobile.import.file.path=D:\mobile\import


Agent will import mobile files (.mdb files) under directory D:\mobile\import\<UserID>


c. To enable/disable mobile file transfer functionality for Agent, Edit procal-agent.properties and set the mobile.transfer.feature.enabled property to true/false respectively



  • To enable, set mobile.transfer.feature.enabled=true 
  • To disable, set  mobile.transfer.feature.enabled=false


Step 12: Run the SQL script mediator-agent-1.0.0/sql/Oracle_PCMedCreate.sql in the Oracle ProCalV5 database as your ProCalV5 schema owner. Skip this step if SQL Server database is used

Step 13: Run the SQL script mediator-agent-1.0.0/sql/MSSQL_PCMedCreatesql in the SQL Server ProCalV5 database as your ProCalV5 schema owner. Skip this step if Oracle database is used

Step 14: Run the following command to start the agent process

agent_installer.bat -start



Press the Windows+R keys to open the Run dialog, type services.msc, press Enter. Or Open the Control Panel, click/tap on the Administrative Tools, double click/tap on Services shortcut.

From the services list, you should see service "ProcalV5Agent" started in automatic mode as shown below



From the agent logs (Using a text editor, open <agent_install_dir>/bin/agent.log), user should see:

  • agent process starting
  • agent will start polling for the messages

To stop the agent, perform one of the two options.

  1. Run the following command

    • agent_installer.bat -stop
  2. Or press the Windows+R keys to open the Run dialog, type services.msc, press Enter. Or Open the Control Panel, click/tap on the Administrative Tools, double click/tap on Services shortcut, close Administrative Tools

    1. Double click/tap/right click on a service with a status of Started that you want to stop. (see screen shot below)

    2. Click/tap on the Stop button, wait until the service status shows as stopped


Troubleshoot

Phase
Issue
Root cause or Fix
Starting agent process using command "agent_installer.bat -start"
ProCalV5 Agent : Unexpected status SERVICE_STOPPED in response to START control.
Environment AGENT_HOME is not set. Set environment variable AGENT_HOME to point to where the Agent software is installed

Caused by: java.lang.IllegalArgumentException: Could not resolve placeholder 'procal.mediator.publicKey' in string value "${procal.mediator.publicKey}"
Run "agent_installer.bat" to configure keys

Oracle Connectivity Issues


java.sql.SQLException: Io exception: The Network Adapter could not establish the connection
        at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.java:112) ~[ojdbc-14.jar!/:Oracle JDBC Driver version - "10.2.0.3.0"]
Database host or port are incorrect.

java.sql.SQLException: Listener refused the connection with the following error:
ORA-12505, TNS:listener does not currently know of SID given in connect descriptor
The Connection descriptor used by the client was:
Database name is incorrect

java.sql.SQLException: ORA-01017: invalid username/password; logon denied
Database username or password is incorrect

SQL Server Connectivity issues


com.microsoft.sqlserver.jdbc.SQLServerException: The TCP/IP connection to the host aws-sql.c5qbrh47sccl.us-east-1.rds.amazonaws.com, port 1434 has failed. Error: "connec
t timed out. Verify the connection properties. Make sure that an instance of SQL Server is running on the host and accepting TCP/IP connections at the port. Make sure th
at TCP connections to the port are not blocked by a firewall.".
Database host or port is incorrect

Could not get Connection for extracting meta data; nested exception is org.springframework.jdbc.CannotGetJdbcCo
nnectionException: Could not get JDBC Connection; nested exception is com.microsoft.sqlserver.jdbc.SQLServerException: Cannot open database "test" requested by the
 login. The login failed. ClientConnectionId:68db5455-3c58-4ac3-875f-80903bcacf90
Database name is incorrect

com.microsoft.sqlserver.jdbc.SQLServerException: Login failed for user 'test123'. ClientConnectionId:52ad1663-4c89-44bf-9d26-8f0b68010a65
        at com.microsoft.sqlserver.jdbc.SQLServerException.makeFromDatabaseError(SQLServerException.java:216) ~[sqljdbc4-4.0.jar!/:na]
Database username or password is incorrect

Firewall issues

Starting agent process using command "agent_installer.bat -start"
Caused by: java.net.UnknownHostException: sqs.us-east-1.amazonaws.com
Open IP addresses in the firewall to allow outbound connections to AWS IP Address range for us-east-1 (North Virginia) region