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.

1. In a web browser, login to your domain or hosting provider that manages your DNS settings.
2. Go to your DNS Zone editor for your domain.

WARNING: Different providers have different requirements. These instructions are based on the most common DNS Zone Editors in the market.

3. Create an A Record for api.yourdomain.com.
   • Host: api
   • IP Address: Your external IP address.
   • Time to Live (TTL): Select the lowest option.

If you already have an domain pointed to your External IP, such as for your Client Portal, or if you are an existing Collect! Cloud-Hosted customer, then create a CNAME Record.

4. If applicable, create an CNAME Record for client.yourdomain.com.
   • Host: client
   • Points To: api.yourdomain.com
   • Time to Live (TTL): Select the lowest option.
5. If applicable, create an CNAME Record for consumer.yourdomain.com.
   • Host: consumer
   • Points To: api.yourdomain.com
   • Time to Live (TTL): Select the lowest option.
6. If applicable, create an CNAME Record for dashboard.yourdomain.com.
   • Host: dashboard
   • Points To: api.yourdomain.com
   • Time to Live (TTL): Select the lowest option.

The domains names above are suggestions. You can pick your own domain names and update Apache as needed.

WARNING: If your network has its own DNS Server, you may have to update it too.

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.

1. In your Firewall, open ports 80 and 443 to all traffic.
2. If applicable, setup port forwarding for ports 80 and 443 on your external gateway to the Collect! server.
3. If not already done, install Apache as per How to Setup Apache with Web Host.

The remainder of this document assumes that DOMAIN_NAME is setup for the client portal. If you do not plan to use the Collect! Web Host, then in the httpd.conf file, set DOMAIN_NAME to be api.yourdomain,com and in the httpd-ssl.conf file, replace the Proxy Balancer code with the Proxy Pass code. See below for examples.

The Help topic How to Setup Apache with Web Host has a section called Multiple Domains. This section will expand on that.

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

Add defines for the domains.

DOMAIN_NAME may have been setup when you configured Apache. It is here for reference.

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

Copy and paste the below into the bottom of the file and update the DOMAIN_NAME variables for each domain that you setup.

If you configured DOMAIN_NAME to be api.yourdomain.com, then you can skip this as it was set during the installation and configuration of Apache.

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

Copy and paste the existing virtual host listening on 443 to the bottom of the file and update the DOMAIN_NAME variables.

At this point, you can remove any line that starts with a comment (#) to clean it up.

If this virtual host is not connecting to load balancer, you can update to connect to a single port. Below is the example for the Collect! API server.

If you configured DOMAIN_NAME to be api.yourdomain.com, then you can skip this as it was set during the installation and configuration of Apache where the Proxy Balancer code was replace with the below Proxy Pass code.

Final Steps

1. Repeat creating the virtual hosts in httpd-vhosts.conf and httpd-ssl for each DOMAIN_NAME. In the httpd-ssl.conf vhosts, update the port numbers for the applicable portals.
2. Start or Restart the Apache service.
3. Setup SSL Certificates as per the Help topic How To Setup Security Certificates.

Scroll down to the Let's Encrypt section to automated security certificates.

4. 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}

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

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

Generic Configuration File

1. Navigate to the CLI folder.
cd {Collect}\bin\companion\cli
2. Run the Setup Script.
./setup.ps1
3. Create the Generic Configuration file.
node ./main.js config new
4. 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.
5. 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.
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.

Troubleshooting

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