How To Install The Rest API

The Collect! REST API allows you to connect to the core application and access functionality without needing the User Interface.

Depending on your configuration, you can install the API Server with or without Apache.

Apache is used to proxy multiple services and for SSL Certificates. If you are running the API server alone and internally, then you may not need Apache.

When you are ready to install, contact Comtech Systems support to obtain a copy of the files.

Unpack the files into the Collect\bin folder. The end result should be Collect\bin\companion.

Port Selection

These instructions will reference the default ports for each service. If you are only running the API server internally on your network, then the simplest solution is to open just the ports for the API Server and the Authorization Server.

If you plan to use the Dashboard, Client, or Consumer portals, then we recommend using Apache with ports 80 and 443 open in your firewall.

The default ports mentioned below will be:

Node.Js Installation

1. Go to https://nodejs.org.
2. In the Download for Windows (x64) section, download the latest LTS release.
3. Once downloaded, install NodeJS using the default settings.

SQL Server Port Configuration

The Collect! API requires SQL Server listening on a static port. Typically, this will have already been setup for Collect! to run on your network. If so, these instructions are informational as a double check.

1. Open SQL Server Configuration Manager.
2. In the left menu, toggle SQL Server Network Configuration and select Protocols for {Server Name}.

If you don't know which server you are running Collect! on, you can find out by opening the Collect\bin\sqlconfig.ini file. If the file contains just the server name, without an instance name, then your {Server Name} is MSSQLSERVER.

3. Right-click TCP/IP and select Properties.
4. In the Protocol tab, change Enabled to Yes
5. In the IP Addresses tab, scroll to the IPALL section at the bottom and change TCP Port to 1433.

If 1433 is already in use by another instance of SQL Server, then you can choose another port like 1434.

6. Click OK.
7. In the left menu, select SQL Server Services.
8. Right click SQL Server {Server Name} and select Restart.

WARNING: This will kick everyone out of Collect!. Only restart SQL Server when nobody is actively using the system.

SQL Server Login Setup

We recommend creating a dedicated account for the API server to access the database.

1. Open SQL Server Management Studio (SSMS).
2. Connect to your Instance used for Collect!.
3. In the left pane, navigate to Security, then Logins.
4. Create a new login.
5. The Login Name can be any value. For this exercise, we will use API.
6. Select the SQL Server Authentication radio option.
7. Enter a password and make note of it for configuration below.
8. Uncheck the Enforce Password Policy box.
9. In the left pane, go to Server Roles and select sysadmin.
10. Click OK to save the account.

Email Setup

This is optional. If you plan to use the Portals, you will need to setup email for Consumer registration or Client multi-factor authentication.

Please refer to the Help topics How To Setup Sending Email In Collect! and How To Setup A Local Email Server Using Hmailserver for more information.

The current email templates are located in the Collect\bin\companion\server\templates folder.

To change the email templates:

1. Navigate to the Collect\bin\companion\server\templates folder.
2. Open the folder for the applicable service.
3. Rename the template file that you want to use and remove the word "template" from the file name. For example: welcome.template.hbs would become welcome.hbs
4. Open the email file with a text editor.
5. Update the HTML file as needed and save.

To use database fields, you can use the following syntax {{ table.field }}
Examples: {{ debtor.de_number }} or {{ nx_user.us_name }}

Domain Configuration

This is only a requirement if you plan to access the API externally. This includes setting up the portals for Consumers, Clients, or the Dashboard.

Setting up external access requires either a static IP address from your Internet Service Provider, or for you to keep an eye on your external IP address and update it as needed.

Please refer to the Help document How to Install and Setup Apache for more information.

Apache Configuration

Apache is used to proxy the domain requests. This allows you to communicate on HTTPS for all requests, without having to open extra ports to the internet.

Please refer to the Help document How to Install and Setup Apache for the instructions to install Apache. This section will go over the vhost configuration for the Authorization Server.

C:\wamp64\bin\Apache\Apache2.4.#\conf\httpd.conf

Add defines for the domains.

C:\wamp64\bin\Apache\Apache2.4.#\conf\extras\httpd-vhosts.conf

Copy and paste the below into the bottom of the file.

C:\wamp64\bin\Apache\Apache2.4.#\conf\extras\httpd-ssl.conf

Copy and paste the below into the bottom of the file.

Final Steps

1. If Apache is already configured and running, then you need to comment out "Include conf/extra/httpd-ssl.conf" line in the httpd.conf file.
2. Restart the Apache service.
3. Setup SSL Certificates.
4. Uncomment "Include conf/extra/httpd-ssl.conf" in the httpd.conf file.
5. Restart Apache.

Collect! Config Folder

At present, the Collect! API needs to know which databases have been authorized for connections. This is done via the api-databases.txt file.

In the future, we will be replacing the text file with the ENV files in the CLI\config folder.

• Navigate to the Collect\config folder. Create an API folder, if one does not already exist.
• In the API folder, create a text file called: api-databases.txt
• Open the file api-databases.txt with a text editor and add the databases that should be available in the API.
cv_masterdb cvr_masterdb cvx_masterdb
• Save the file.

Remember to include the Report and Import databases.

This file already exists for new Collect! installations. It it not included in a patch to avoid overwriting an existing configuration.

Collect! API Application

The cvapi.exe application is only available in the latest release of Collect!. As the API is a live development project, it is recommended to stay up-to-date with patches.

The best option for running the API is via the Windows Scheduler.

1. Create a Windows Batch file in the Collect\bin folder called shutdowncollect.bat.
2. Edit the file with a text editor.
3. Add the following code:
taskkill.exe /f /im cv13.exe taskkill.exe /f /im cvapi.exe
4. Save and close the Batch file.
5. In Collect! create a new Operator with the highest privileges. Select the Password does not expire box.
6. Open the Windows Task Scheduler.
7. Create a new Task for the Shutdown.
   • Schedule the task that works best for you based on your environment and backups.
   • For the action, select the shutdowncollect.bat file.
   • Save the Task.
8. Create a new Task for the API server.
   • Schedule the task that works best for you based on your environment and backups.
   • For the action, select cvapi.exe.
   • In the Add Arguments box, put in: /m /S4001 /dbmasterdb /i{ID} /p{password} /min
   • Save the Task.

ID and Password are from the Collect! Operator that you created.

We use port 4001, but you can use any port as long as you configure it properly below.

Powershell Setup

The remaining steps are to be done in PowerShell. Open PowerShell as an Administrator.

If needed, run the below to set the Execution Policy.

Any references below to {Collect} are to be replaced with your actual Collect! directory. For example: C:\Collect.

If you are running Collect! on another drive, you will need to enter that drive first, then push enter. For example: D:{enter}

Cli Configuration

The CLI folder stores the database connection configuration. Each file has a ENV extension.

The config.env file contains generic configuration information.

Each database needs to have its own ENV file. For example: cv_masterdb.env

You will need to contact us to obtain the latest installation package.

Generic Configuration File

1. Unpack the installation package into the {Collect}\bin\companion\ folder. This should result in {Collect}\bin\companion\cli and {Collect}\bin\companion\server.
2. Navigate to the CLI folder in Powershell Admin mode.
cd {Collect}\bin\companion\cli
3. Run the Setup Script.
./setup.ps1
4. Create the Generic Configuration file.
node ./main.js config new
5. Enter the Collect! API host server. Typically, it's the same computer that Collect! is installed on. You can enter 127.0.0.1, localhost, or your server's name.
6. Enter the Collect! API Port. Typically, it's 4001, but use the value that you configured for the Windows Scheduler above.

Database Configuration File

1. Create the Database Configuration file.
node ./main.js config new:database
2. Enter the Database Name. Default databases, like cv_masterdb will be selectable. Other ones will need to be typed in.
3. Enter the SQL Server Login Name that you created above.
4. Enter the SQL Server Login Password.
5. Enter the Collect! SQL Server host. Typically, it's the same computer that Collect! is installed on. You can enter 127.0.0.1, localhost, or your server's name. If you use a different database server, enter the server's IP address or name.
6. Enter the Collect! SQL Server Port. Typically, it's 1433, but use the value that you configured in the SQL Configuration Manager above.
7. Select the Encryption option that is applicable to your environment. Typically, if you are running the Collect! application and database on the same server, encryption is not needed.
8. Select (Y)es to test the connection.
9. Enter the amount of time for inactive sessions before having to log back in. Default is 30 minutes.
10. Enter the amount of time before having to the refresh the tokens. Default is 1 hour.

Multiple Databases

If you plan to run multiple databases with access to the API, then you will need to specify a default database. If you do not specify a default database, cv_masterdb will be assumed.

1. Open the Collect\bin\companion\cli\config\config.env file with a text editor.
2. Add the following to the bottom of the file:
DEFAULT_DATABASE = {database_name}
3. Repeat the steps above under "Database Configuration File" for each database.

Use the same SQL Server credentials for all databases for simplicity.

Collect! Authorization Server

The Authorization Server is the gateway for the API. All incoming requests go there, then they are routed to the Collect! API Server. This allows you to setup a proxy load balancer, if you wanted.

The Authorization Server also manages authentication. When you connect with your Collect! credentials, the server returns a token that you will use with all future requests for the session.

1. Navigate to the Server folder in Powershell Admin mode.
cd {Collect}\bin\companion\server
2. Run the Setup Script.
./setup.ps1

The Authorization Server currently only allows access to Collect! User Levels that are set as Function Manager, Client, or Collect. Sign in to Collect! and set your User Levels appropriately.

Minio Storage

This is optional and may not be in the companion server package, if you don't need it. It provides storage capabilities by connecting to Amazon Web Services S3 storage services.

1. Navigate to the MinIO folder.
cd {Collect}\bin\companion\minio
2. Run the Setup Script.
./setup.ps1

Troubleshooting

If you restart your server, the PM2 services may not be running. Run the resurrect code in PowerShell.