Installing the Cloud Companion (Server Edition) agent

The Server Edition agent for Cloud Companion can be installed using the steps in this guide.

• About the agent
• Server Agent Setup
  • Installing the Agent
  • Service Account Requirements
  • Agent Configuration Options
  • Installation on multiple servers
• Upgrading the agent
• Removing the agent
• Managing which printers the agent can see
  • Run Printer Install Wizard as Another User
  • Show available printers
  • Setting printer defaults
• Troubleshooting the agent

About the agent

The Cloud Companion agent runs on an On-Premises Windows server to connect to locally shared printers.

For Business Central hosted by Microsoft or Fenwick, the service provides a path to print to local printers which are not directly accessible.

The agent doesn't require any port configuration, though must be able to contact the internet (at minimum TCP 443). If your network has restrictions on outbound connections, then exceptions must be configured to allow the agent to connect.

Server Agent Setup

You can install the agent on any networked server. We recommend avoiding installation on Domain Controllers. A dedicated machine is not necessary. You'll want to use a machine that meets the following requirements:

• Windows Server 2016+ or Windows 10+
• .NET Framework v4.7
• NiceLabel (if you're printing Labels via Label-It)
• Ghostscript (if you're printing Reports)
• Network or local access to the printers you wish to use

Installing the Agent

The agent installation will require administrative permissions and a service account.

1. Please raise a support request to receive your installation files, and for any assistance required with your installation.
2. Unzip the supplied package.
   • It should be unpacked into a permanent directory, not a temporary location.
3. If Fenwick has not provided a pre-configured version for you, open the file config.json and set CloudCompanionBrokerApi TenantId and ApiKey.
4. Open an elevated command prompt, navigate to the unzipped directory, and run
   Fenwick.CloudCompanion.ServerEdition.Service.exe install
5. You will be prompted for service account credentials. If you are using an account without a password, you may leave the password field empty in the authentication prompt. This will install a Windows service Fenwick Cloud Companion (Server Edition).
6. Run this command to start the service after installation
   Fenwick.CloudCompanion.ServerEdition.Service.exe start

Service Account Requirements

The account that runs the service must have read and write access to the directory containing Fenwick.CloudCompanion.ServerEdition.Service.exe, for logging and configuration management.

The account must also have network permissions to the printers available through Cloud Companion.

If you are using report printing functionality, the service account must be a local administrator.

The service account password should be set to not expire. If the password is changed, then the credential needs to be updated on the agent's Windows service configuration.

A managed service account (MSA or gMSA) can also be used. You can use the --networkservice flag for install, then set the account manually afterwards via services.msc.

Agent Configuration Options

The configuration file config.json contains the following options:

• PrinterCheckInterval sets how often the local printers will be re-checked for changes, and to be visible in Business Central.
• PrinterBlackList is a set of regular expressions that are used to exclude printers from being made available through Cloud Companion. By default, PDF, XPS and Fax printers are excluded.

After making configuration changes, the service will need to be restarted.

Installation on multiple servers

If you have multiple sites you may need to install the agent on multiple servers. The agent can be installed on multiple different networks (i.e. multiple sites).

Please raise a support request to get more information on this option.

Ghostscript for report printing

If you will use report printing via Cloud Companion the reports will be sent in PDF format and Ghostscript must be installed. Ghostscript can be downloaded here. Obtain the AGPL version.

NiceLabel for label printing

Only the Print feature is required when installing NiceLabel. The Automation and Designer are not required to work with Cloud Companion.

Older Editions of Windows Server

While not supported, older versions of Windows Server may still work if TLS1.2 support is enabled:

1. Enable TLS1.2 Client connections
2. Updated Cipher Suites for Server 2008 and Server 2012

You'll require these patches if you experience an error similar to the one below:

System.Net.WebException: The underlying connection was closed: An unexpected error occurred on a send. ---> System.IO.IOException: Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host. ---> System.Net.Sockets.SocketException: An existing connection was forcibly closed by the remote host

Upgrading the agent

To upgrade to the latest version of the Cloud Companion agent:

1. Stop the Fenwick Cloud Companion (Server Edition) Windows service.
2. Take a copy of the existing installation directory as a backup.
3. Unzip the new package into the existing installation directory, overwriting the files.
   • It is important that the AgentId.json file is kept. This file is created by the agent when it first runs and will not be overwritten when the new package is unzipped over the top of the existing files.
4. Start the Fenwick Cloud Companion (Server Edition) Windows service.
5. Perform a test print from Business Central.

Removing the agent

1. Stop the Windows Service.
2. At an elevated command prompt in the installation directory, run:
   Fenwick.CloudCompanion.ServerEdition.Service.exe uninstall.
3. You can delete the files from the directory once the service is removed.

Managing which printers the agent can see

The agent will only be able to see printers which are available and installed for the user account that's running the service.

If you need to add printers as a specific user, you can use one of the following methods:

Run Printer Install Wizard as Another User

1. Start a new command prompt, using Run As (Ctrl + Shift while right clicking)
2. Enter rundll32 printui.dll,PrintUIEntry /il and complete the wizard

Use Group Policy Printers via Computer Configuration

You can also use the Print Management to make managing printers in Group Policy simpler. We recommend deploying under the Computer configuration and not to a particular User.

1. Create a new GPO policy
2. Under Computer Configuration > Preferences > Control Panel Settings > Printers add the new printer.

Show available printers

If you run PowerShell as the service account (using psexec if you're using a Managed Service Account) the following command will show you a list of available printers:

get-WmiObject -class Win32_printer | ft name, systemName, shareName

Setting printer defaults

To change the printer driver defaults for all users and for network users connecting to a shared printer:

1. Start > Run > "control printers" > OK
2. Right click printer, select Properties.
3. Go to Advanced tab.
4. Click Printing Defaults button.
5. Change the settings.

Troubleshooting the agent

Check the logs and provide them to Fenwick. Logs are available in the log subdirectory of the folder which contains Fenwick.CloudCompanion.ServerEdition.Service.exe.

If no log files are present, ensure that the service account has permissions to create and modify files in this directory.

No print jobs are printing

• Ensure the Fenwick Cloud Companion (Server Edition) service is running
• If a Windows service does not start, then
  • Ensure there is a valid credential set up on the service. If your service account password has expired, then the new password must be entered.
  • Ensure that the agent files are still present in the installation directory. If you are unsure of the installation directory, it can be checked by opening the properties of the Fenwick Cloud Companion (Server Edition) service and examining the Path to executable property.
• If network errors are present in the log file, firewall rules may need to be created.
• If nothing is printed or logged when Business Central prints labels, there may be a printer registration issue:
  • In Business Central, review the Server Printers setup area. The Cloud ID field is important and must correspond to a valid and active printer.
  • If multiple of the same printer are visible in the Cloud ID lookup, please contact Fenwick to have these cleaned up. Duplicates can occur if the agent's Client ID has been mistakenly deleted or regenerated.

The Log File contains "This managed library is running under 64-bit process and requires 64-bit Ghostscript native library installation on this machine!"

Fenwick Cloud Companion is attempting to print PDF documents but Ghostscript has not been installed, or the wrong version has been installed (32-bit/64-bit). Review the installation steps.