NCR Counterpoint Installation Instructions

NCR Counterpoint runs on the subscriber's own server rather than in the cloud, so connecting it to iPaaS.com means installing two components alongside Counterpoint and then pointing the iPaaS.com subscription at them.

This article is the overview of that process. It states what has to be installed, in what order, and how the pieces reference each other, and links to the detailed article for each step. Read it first, then work through the linked articles in order.

What gets installed

A standard installation has two components, and both are required:

CPHive: a web service installed on the Counterpoint server and published at a URL that iPaaS.com can reach. iPaaS.com calls CPHive to read and write Counterpoint records.
CPWebhooks: a Windows service that watches the Counterpoint database and notifies iPaaS.com when records change. Without it, nothing that happens in Counterpoint reaches iPaaS.com automatically.

The two work in opposite directions and are not alternatives to each other. CPHive carries data into Counterpoint and answers requests from iPaaS.com; CPWebhooks tells iPaaS.com when something in Counterpoint has changed so that iPaaS.com knows to ask.

CP Extender is not part of a standard installation. It is a separate optional component covering capabilities such as gift cards, loyalty, pick tickets and image handling, and it is not required for the integration described here. Subscribers whose project includes it should follow CP Extender: Setup separately.

How the pieces connect

Three references have to line up, and most failed installations are one of these being wrong:

The subscription points at CPHive: the CPHive URL is entered into the NCR Counterpoint subscription in iPaaS.com, as CP Api Url.
CPWebhooks points at iPaaS.com: the CPWebhooks service configuration holds the iPaaS.com URL for the deployment the subscriber's company was created in.
CPWebhooks carries the subscription's API key: the API key generated on the iPaaS.com subscription is saved into the CPWebhooks service configuration. This is what identifies the notifications as belonging to that subscription.

Before You Begin

Gather the following before starting. Most of these come from the subscriber's IT team, and several have lead times:

A hostname for CPHive: a subdomain that resolves to the Counterpoint server from the internet.
An SSL certificate covering that subdomain. A wildcard certificate covering the subscriber's domain also works.
Firewall access: CPHive is published so that iPaaS.com can reach it, and inbound traffic to it should be restricted to the sources that need it. CPHive reads and writes the Counterpoint database directly, so the allowlist on that address is what keeps the rest of the internet away from it. The subscriber's IT team should allow inbound traffic to CPHive from:
- 52.184.255.108 (outbound.iPaaS.com — the iPaaS.com production environment)
- 69.61.66.128/27 (the iPaaS.com staging environment)
- any addresses the subscriber's IT team uses for troubleshooting
Counterpoint user credentials: a valid Counterpoint user id and workgroup. The user id is stamped onto every record CPHive writes, so it should be a real, identifiable Counterpoint user. The configuration also carries a password field; it is not currently used and ships empty.
Counterpoint database details: the SQL Server instance name, the database name, and a SQL user with access to it.
The Counterpoint top-level directory and company alias, both available from Counterpoint's own environment settings.
An iPaaS.com account with access to the subscriber's company.

Note which iPaaS.com deployment the company was created in — staging and production have different addresses, and CPWebhooks must be pointed at the right one.

Download the installation files

The installation files are published in the iPaaS.com install repository:

https://github.com/ipaas-com/CPHiveInstall

Take the current contents of the repository.

Versions. At the time this documentation was written, the current releases are CPHive v2 (build 23448) and CPWebhooks v2. Both are required for a standard installation.

CPHive v2 is required for NCR Counterpoint 8.6 and higher.
The integration is tested against NCR Counterpoint 8.6.1. Subscribers or their MiSP running a different Counterpoint release should validate the integration in a staging environment before relying on it in production.

If there is any doubt about which build applies to a particular Counterpoint release, confirm with iPaaS.com Support before installing.

Install CPHive

CPHive is an IIS-hosted web service. Follow CPHive Connections and Settings for the detailed steps — the server prerequisites, the IIS site and application pool, the certificate, and the configuration file. In outline:

Prepare the server: install the ASP.NET Core 6.0 Runtime Hosting Bundle and enable the IIS role, including the management tools. Confirm the runtime reports version 6.0 before continuing.
Deploy the files: extract CPHive into the website folder and convert it into an IIS application.
Create an application pool: CPHive runs in its own application pool with 32-bit applications enabled. Staging and production instances must not share a pool. The account running the pool needs access to both the CPHive cache folder and the Counterpoint top-level directory.
Bind the certificate: publish the site on the subdomain and bind the SSL certificate to it.
Configure the connection: enter the Counterpoint user, workgroup, top-level directory, company alias, the log severity, and the database connection details into the CPHive configuration file. The file is JSON, so any backslashes in a path must be escaped. The top-level directory must end with a trailing separator — CPHive appends the dictionary and company alias folder names directly onto it, so without one those paths are built joined together, and the connection test reports the directory as missing or inaccessible even though it exists.
Restart the site: settings are read when the site starts, so stop and start the website — or recycle its application pool — after any configuration change. This applies every time the configuration is edited, not just during installation.
Generate the data dictionary cache: CPHive builds a cached copy of the Counterpoint data dictionary on first use. Confirm the cache file is created; if it is not, the application pool account is missing permission to the cache folder.

Important: the cache is built from the Counterpoint data dictionary as it exists at the time. If custom fields are added to Counterpoint later, the cache must be regenerated, or mappings referencing those fields will fail.

Install the database objects

Both CPHive and CPWebhooks depend on supporting objects in the Counterpoint database — the change queue that CPWebhooks reads, the table that records which events are subscribed to, and the triggers that populate the queue when a record changes. These are installed by the database installer supplied in the CPHive and CPWebhooks Database Install Scripts folder of the install repository. The installer and its prerequisites are documented in CPHive Connections and Settings.

Run the installer against the Counterpoint database, supplying the database connection and the company alias folder, and verify both before installing. The installer also converts objects carrying the older naming used by earlier versions, so it is safe to run against a database that was previously connected to an earlier release.

This step is required. CPWebhooks cannot start without the change queue, and no trigger event reaches iPaaS.com until the triggers exist.

Install CPWebhooks

CPWebhooks is a Windows service installed against the Counterpoint database. Follow Install CP Webhooks for the detailed steps. In outline:

Deploy the files to an installation directory on the Counterpoint server.
Configure the service: enter the iPaaS.com URL for the correct deployment, the subscription's API key, and the Counterpoint database connection details. Replace the URL that ships in the configuration file. It is preset to a development address, and unlike the token beside it — which reads obviously as a placeholder — it looks like a working value. Left as delivered, the service starts and runs, but nothing it sends reaches the subscriber's environment and no error is raised anywhere.
Create the service by running the supplied installation batch file.
Confirm it is running: the service appears in the Windows services list in the running state.

One service per Counterpoint database. A server hosting several Counterpoint databases needs one CPWebhooks installation per database, each in its own directory and each with a distinct service name set before the service is created.

Connect the subscription in iPaaS.com

Once both components are installed:

Sign in to iPaaS.com and select the subscriber's company.
Open the NCR Counterpoint subscription from Subscription Management and select Edit.
Enter the CPHive address as CP Api Url, along with CP Api Username and CP Api Key. If CPHive is published on a port other than the default, include the port in the address.
Apply the settings and test the connection. A successful test returns the Counterpoint company name.

The remaining subscription settings, and what each one does, are covered in NCR Counterpoint Connections and Settings.

Additional Configuration

Optional features

Several features are not active after a standard installation and need a further step carried out against the Counterpoint database. A feature in this state produces no error — it simply never transfers automatically. If an optional feature appears to do nothing, this is the first thing to check.

There are two kinds, and it matters which one applies. At the time this documentation was written:

Shipped but switched off. Kits, location groups and category assignments are installed by the database installer already, with their trigger events recorded as not subscribed. Enabling one of these is a matter of switching its events on in the Counterpoint database — nothing needs to be created.
Not shipped. Barcode types, substitute items, users, messages and timecards are not installed by the database installer. Enabling one of these requires both its trigger events and its database trigger to be added.

Scripts for both cases are supplied per feature in the optional-scripts folder of the install repository. Only run the script for a feature that is actually in scope, and restart the CPWebhooks service afterwards.

Important: do not use the scripts published in older feature documentation for kits, location groups or category assignments. Those were written before the feature shipped with the installer, and re-running them against a current installation duplicates the trigger event records and fails, because the database trigger already exists.

Important: the scripts for features that are not shipped create database triggers on live Counterpoint tables. A mistake in a trigger can prevent records from being saved in Counterpoint. Apply them to a staging database and validate the feature end to end before running them against production.

Note that some of these features' trigger events are not offered for selection in Inbound Data Flows even once enabled in the database. Subscribers or their MiSP should validate any optional feature end to end in a staging environment before relying on it in production.

Image Mover

Image synchronisation is handled by Image Mover, which is part of CP Extender — the optional component described under What gets installed above. It is not part of a standard installation, and it cannot be configured without CP Extender already installed on the Counterpoint server.

Subscribers whose project includes image synchronisation should install CP Extender first, following CP Extender: Setup, and then configure the image service following Configure Image Mover. Otherwise, skip this step.

Post-Installation Verification

Confirm the installation end to end before handing over:

CPHive responds: browse to the CPHive address from the Counterpoint server and confirm the service answers. The page is an interactive API reference, so use a current browser — it will not render in a legacy one.
Run the built-in check: browse to the CPHive address with /HelloWorld on the end. This returns a single diagnostic summary covering the database connection, the Counterpoint top-level directory, the company alias folder, the data dictionary, and whether the application pool is correctly running 32-bit. It is the fastest way to find a configuration problem, and it checks more than the steps below. Resolve anything it reports before continuing.
The connection test passes in iPaaS.com and returns the expected Counterpoint company name.
The data dictionary cache exists in the CPHive cache folder.
The database installer completed without errors, and the change queue exists in the Counterpoint database.
The CPWebhooks service is running in the Windows services list.
A record transfers: run a Manual Sync for a small collection, such as locations or shipping methods, and confirm the records arrive in iPaaS.com.

These checks confirm the plumbing works. To populate reference data for the first time, use Initialization rather than repeated Manual Syncs — see NCR Counterpoint Connections and Settings for the entities that support it. - A change is detected: edit a record in Counterpoint that has its trigger events enabled, and confirm the change reaches iPaaS.com without a Manual Sync. This is the only check that proves CPWebhooks is working; every earlier check passes without it.

Support and Troubleshooting

Transfer errors surface at Dashboard / Integration Monitoring / Error Logs.

Common installation problems:

The connection test cannot reach the service: confirm the address is correct — including its port, if CPHive is published on a non-standard one — that the site is running, that the certificate is valid for the subdomain, and that the firewall allows iPaaS.com.
The CPHive site will not load on the server itself: the ASP.NET Core 6.0 Runtime Hosting Bundle is missing or is the wrong version.
The site loads but returns an HTTP 500.30 error: check the Windows event logs on the Counterpoint server, which carry the reason the site failed to start.
A configuration change appears to have no effect: the site was not restarted. Stop and start the website, or recycle its application pool, and try again.
The configuration file will not load: it is JSON — confirm any backslashes in a path are escaped.
The connection test reaches CPHive but cannot read Counterpoint: the database connection details in the CPHive configuration are wrong, or the account running the application pool lacks access to the Counterpoint top-level directory.
The CPWebhooks service will not start: confirm the database connection details in its configuration, and that the database installer ran successfully and created the change queue.
Records transfer on Manual Sync but changes are never picked up: CPWebhooks is not running, is pointed at the wrong iPaaS.com deployment, or is carrying the wrong API key.
An optional feature never transfers: its trigger events have not been enabled in the Counterpoint database, or — for a feature the database installer does not ship — its script has not been applied.

Turn logging down before go-live. Both components ship configured for detailed logging, which records the full content of every message and is intended for commissioning rather than normal running. Leaving it on degrades performance and can cause transfers to time out. Set the log severity to E (errors only) or W (warnings and errors) in each component's configuration file once the installation is working, and restart the component afterwards. CPWebhooks additionally ships with debug mode switched on; turn that off at the same time.

For further assistance, contact iPaaS.com Support.