Remote Connector for QuickBooks
Remote Connector for QuickBooks

Remote Connector for QuickBooks

Remote Connector for QuickBooks is a simple application that facilitates local and remote connections to company files from your application. This is done using an embedded Web server that runs on the machine where QuickBooks is installed and which enables one or more users to connect securely.

The first time you connect to QuickBooks, you must authorize your application. Complementing QuickBooks' per-application authentication, Remote Connector has per-user authentication. Before connecting to QuickBooks for the first time, configure at least one Remote Connector user.

You can configure users through the UI on the Users tab. You can then follow the procedure in "Getting Started" to connect an application to QuickBooks using Remote Connector. After connecting, you can monitor QuickBooks connections on the Status tab.

It is recommended to configure Remote Connector in the UI, but you can also run Remote Connector from the command line. This can simplify deploying Remote Connector in scenarios where normally there is not a user logged in, such as running a Web server. See the Advanced page to configure Remote Connector when you are not using the UI.

Remote Connector automatically manages the connection to QuickBooks, but you can configure almost every aspect of how users connect to QuickBooks through Remote Connector. The following pages outline the capabilities of Remote Connector and how to get started.

Remote Connector for QuickBooks

Getting Started

Remote Connector makes it easy to connect to local and remote QuickBooks instances. It is also used to connect your application to QuickBooks in situations where direct COM access to QuickBooks is not available (e.g., ASP.NET, Java, or QuickBooks on a remote machine). Follow the procedure below to connect to QuickBooks for the first time through Remote Connector.

  1. Install Remote Connector on the machine where QuickBooks is installed.
  2. Open the company file you want to connect to in QuickBooks using an administrator account in single-user mode.
  3. Open Remote Connector from the system tray and add a user on the Users tab. Enter a User and Password and select the level of access in the Data Access menu. By default QuickBooks connects to the currently open company file. If you want to access QuickBooks when QuickBooks is not running, specify a path to the company file you want to access.

    Note: Remote Connector does not use the User and Password properties to access QuickBooks; the User and Password properties authenticate the user to Remote Connector. Authentication to QuickBooks is handled based on the Application Name property.

  4. When you first connect, a dialog will appear in QuickBooks prompting you to authorize the application.

How do I connect to QuickBooks over SSL?

You can enable SSL on the Advanced tab.

Remote Connector for QuickBooks

Users

The Users tab provides an interface to add, edit, and delete users. At least one user must be added before communicating with QuickBooks.

This tab displays a list of existing users along with information about the user's configuration.

When adding or editing a user, the following options are available:

  • User: Sets the username. This is required.
  • Password: Sets the password for the user. This is required when using Basic authentication (default).
  • Company File: Specifies the company file with which the application will communicate. By default this is the company file that is currently open in QuickBooks. This can also be set to the absolute path to a company file (.qbw file). A company file location must be specified in order to access the company file when QuickBooks is closed.
  • Authentication: Specifies the type of authentication to perform when the user connects. Remote Connector supports the following authentication methods:

    Basic Authentication (default): Authenticates the user with a username and password.
    Windows Authentication: Authenticates the user as a Windows user. In this case the Password field is not applicable. When Remote Connector receives a connection request, it will authenticate the user to Windows using the credentials supplied in the request.

  • Application Name: Optionally sets the name of the application as seen by QuickBooks. Authentication to QuickBooks is handled based on the provided application name.
  • Data Access: specifies the allowed access for the user.

    Full: Allows read and write access for the user.
    Read-only: Restricts the user to read-only operations. QuickBooks data cannot be modified.

The Test Connection button provides a quick way to verify the application can connect with QuickBooks.

When a user is added Remote Connector will prompt you to authorize the application with QuickBooks if necessary.

Remote Connector for QuickBooks

Status

The Status tab provides a log of the activity happening with Remote Connector. Logs can be cleared or copied by right-clicking in the Recent Activity window.

You can adjust the detail of the logs to include information useful when troubleshooting: Select the granularity in the Log Mode menu on the Advanced tab. On the Advanced tab, you can also configure Remote Connector to write logs to a file and select the log rotation interval.

Remote Connector for QuickBooks

Advanced

The Advanced tab allows granular control over Remote Connector's server. Remote Connector contains an embedded Web server that runs as a Windows service and listens for HTTP requests. Each request contains the XML data to be communicated to QuickBooks as well as configuration settings specifying how the connection is to be opened. Remote Connector then communicates with QuickBooks via COM, and returns the QuickBooks response (or an error message) in the HTTP reply.

This chapter details how to control each of these aspects of connecting to QuickBooks through the UI, command-line interface, and the registry. The following sections detail the options available on the Advanced tab.

Logging Options

  • Write Logs to a Folder: Enables or disables writing log files to the specified folder in addition to writing logs to the Status tab.
  • Folder: Specifies the folder where log files are written.
  • Log Rotation: Determines how logs are organized on disk. Creates one file for each day, week, or month, depending on the following value:

    Daily (default): Uses a new log file every day. Files are written with the format "yyyy_MM_dd.txt". For example, "2013_09_23.txt".
    Weekly: Uses a new log file every week. Files are written with the format "yyyy_ww.txt". For example, "2013_34.txt", where 34 means this is the 34th week of 2013.
    Monthly: Uses a new log file every month. Files are written with the format "yyyy_mm.txt". For example, "2013_09.txt".

  • Log Mode: Sets the verbosity of the log output. In most situations, Info (the default) is sufficient. The Verbose option is helpful for debugging purposes.

IP Options

  • Port: The port on which the server listens.
  • Allowed Clients: A comma-separated list of host names or IP addresses which can access the server. The wildcard character '*' is supported. If unspecified (default) any client can connect.

Enabling Persistent Connections

All communications to QuickBooks company files must first go through QuickBooks. If QuickBooks is closed, this means that for each attempt to connect to the company file, QuickBooks needs to be launched and then closed again. By default the Remote Connector queues requests for data and performs the necessary authentication for each request. The following options can be used to override this behavior and keep the connection to the company file alive after the query finishes executing, so further requests will respond more quickly.

Warning: If a user attempts to manually open QuickBooks while a persistent connection is opened, QuickBooks will throw an error stating that the company file is already in use.

  • Enable Persistent Connection: This is disabled by default: Normally your code controls when the connection to QuickBooks is opened and closed by calling the Open and Close methods; however, when this setting is enabled, Remote Connector establishes a persistent connection to QuickBooks even when Open and Close are not used. This allows multiple applications to share the connection and simultaneously access Remote Connector.
  • Idle Timeout: Sets the idle timeout for the persistent connection in seconds. This is only applicable to the persistent connection. If there is no activity within this time window Remote Connector closes the connection.

Enabling SSL

Enabling SSL encrypts communication between your application and Remote Connector. SSL uses digital certificates to protect the confidentiality, integrity, and authenticity of your data: You can generate these certificates on the Advanced tab. Once you have enabled SSL, you will need to send your public key certificate to any connecting applications.

The following options are used to configure SSL:

  • Enable SSL: Enables or disables SSL communication.
  • Select Certificate: Loads an existing certificate.
  • Generate Certificate: Creates a new certificate.
Loading a certificate displays information about the certificate; the properties of the certificate cannot be set directly. Note: Enabling SSL disables plaintext connections.

Remote Connector for QuickBooks

Command-Line Interface

In addition to the UI, Remote Connector has a command-line interface that makes it easy to deploy on machines where a user is not always logged in, for example, a Web server. To facilitate deployment to these environments, Remote Connector contains two executables:

RemoteConnector.exe Provides the user interface and allows configuration of the application.
RemoteConnectorService.exe Processes requests and performs all interaction with QuickBooks.

The syntax for managing the Remote Connector Windows service from the command line is as follows:

RemoteConnectorService.exe -Service <Command>

The following commands are available:

InstallInstalls the Windows service.
DeleteDeletes the Windows service.
StartStarts the Windows service.
StopStops the Windows service.
StateReports the current state of the Windows service (started or stopped).
AutoChanges the Windows service startup type to Automatic.
ManualChanges the Windows service startup type to Manual.
DisabledChanges the Windows service startup type to Disabled.

Remote Connector for QuickBooks

Registry Keys

All configuration data is read from the registry at "HKEY_LOCAL_MACHINE\SOFTWARE\RemoteConnector". Each user will have a separate subkey with user-specific settings. For instance "HKEY_LOCAL_MACHINE\SOFTWARE\RemoteConnector\User1".

Application-Level Settings

NameTypeDescription
AdminAuthStringA randomly generate administrator password that is used for authorization between the user interface and the Windows service. This is only used when authorizing a user configured for Windows authentication to QuickBooks from the user interface. This may be removed or changed if desired.
AllowedClientsStringA comma-separated list of host names or IP addresses that can access the server. The wildcard character '*' is supported. If unspecified (default) any client can connect.
AuthFlagsDWORDSpecifies the versions of QuickBooks to which the application can connect. The value is a binary OR of the values below, represented in hex. The default value is "0xF" (all editions are supported).
  • "" or 0 (Do not send any auth flags)
  • 0x01 (Simple Start)
  • 0x02 (Pro)
  • 0x04 (Premier)
  • 0x08 (Enterprise)
CloseAndRetryConnectDWORDSpecifies whether connection retry logic is enabled. When set to 1 (True), if an error is encountered while opening a connection to QuickBooks the application will attempt to stop the QuickBooks process and reconnect. The CloseAndRetryTimeout, CloseAndRetryCount, and CloseAndRetryErrorList settings are applicable when this setting is 1 (True).
CloseAndRetryTimeoutDWORDSets he time in seconds that the application will wait for the connection to QuickBooks to be established. The default value is 30 (seconds). If the timeout is reached, the QuickBooks process will be closed and the connection will be retried. Note that this setting should be adjusted with caution. If the timeout is set too low the QuickBooks process may not have time to open normally before reaching the timeout. This setting is only applicable when CloseAndRetryConnect is True.
CloseAndRetryCountDWORDSets the number of times to retry the connection. If an error is encountered while opening a connection to QuickBooks, the application will stop the QuickBooks process and retry until this limit is reached. The default value is 3. This setting is only applicable when CloseAndRetryConnect is True.
CloseAndRetryErrorListStringSpecifies a comma-separated list of QuickBooks error codes on which to retry a connection. If QuickBooks returns an error code listed in this property, the QuickBooks process will be stopped and the connection will be retried. If the error is not in this list the application will return the error as normal. The default value is "0x80040402,0x80040408". Specify the value "*" to indicate all errors. This setting is only applicable when CloseAndRetryConnect is True.
QBInstanceFileString

Specifies the full path to the QBINSTANCEFINDER file in the QuickBooks installation. For instance: "C:\ProgramData\Intuit\QuickBooks\QBINSTANCEFINDER17.INI". This setting is only applicable when CloseAndRetryConnect is set to True.

If the connection retry logic stops the QuickBooks process the specified QBINSTANCEFINDER file will be cleared of any previous entries. QuickBooks uses the QBINSTANCEFINDER file to keep track of open instances, however, in some situations it may not be properly reset after stopping the process. When specified this setting allows the application to properly reset the file after stopping the process.

LocalHostStringSets the host name or user-assigned IP interface through which connections are initiated or accepted. In most cases this does not need to be set, as the application will use the default interface on the machine. If you have multiple interfaces, you can specify the interface to use here. For instance, "192.168.1.102".
LogEnabledDWORDEnables or disables logging to a file. Logs are always written to the console. The default is 0 (False).
LogDirStringSets the path to a folder on disk where log files will be written. This is only applicable if LogEnabled is set to True.
LogFormatDWORDSets how often new log files are created. Possible values are the following:
  • 0 (Daily - default)
  • 1 (Weekly)
  • 2 (Monthly)
LogLevelDWORDSets the logging level. Possible values are the following:
  • 0 (Off)
  • 1 (Error)
  • 2 (Warning
  • 3 (Info - default)
  • 4 (Verbose)
LogPortDWORDSets a separate port for logging. Log messages are sent over UDP from RemoteConnectorService.exe to the UI. By default this is the same value as the port defined in the Port option. Set this option to avoid using the same port as another UDP service running on the same machine.
PortDWORDSets the port where the server listens for incoming connections. The default value is 8166.
PersistentEnabled DWORDEnables or disables persistent connections to QuickBooks. The default is 0 (False), meaning that your code controls when the connection to QuickBooks is opened and closed by calling the Open and Close methods. However, when this setting is enabled, a persistent connection to QuickBooks is established by Remote Connector even when Open and Close are not used. This is helpful in situations when multiple applications may be simultaneously accessing Remote Connector, because it allows them to share the connection.
PersistentIdleTimeoutDWORDSets the idle timeout for the persistent connection in seconds. If there is no activity within this time window, the connection to QuickBooks will be closed. This is only applicable when PersistentEnabled is True.
PromptForRegPermissionsDWORDSpecifies whether to prompt to modify registry permissions when access is not allowed. This is only applicable when saving settings from the UI.
RunAsServiceDWORDRun the application as a service or with the standard run-time permissions. The default value is 1 (True).
SSLCertPasswordStringSets the password of the SSL certificate.
SSLCertStoreStringSets the location of the SSL certificate. This may be a path to a file or the name of a Windows certificate store: "MY", "ROOT", "CA", or "SPC".
SSLCertSubjectStringSets the subject of the SSL certificate.
SSLCertTypeStringSets the type of SSL certificate to use. A certificate must be specified when SSL is enabled. The PFX option signifies a .pfx file on disk. The User option signifies the user's Windows certificate store. The Machine option signifies the Windows certificate store of the machine.
SSLEnabledDWORDSets whether SSL connections are allowed. The default value is 0 (False). Enabling SSL disables plaintext connections.
TimeoutDWORDSets the operational timeout for connected clients. The default value is 60.
UseInteractiveLogonDWORDSets whether interactive or network logon will authorize users when AuthMode is set to 1 (Windows). In most cases this does not need to be set. This should be set to 1 (True) if your domain controller is Samba. The default value is 0 (False).

User-Level Settings

AppNameStringSets the name of the application that will be used to provide authentication to QuickBooks when a connection is made. If this value is not set, Remote Connector uses the value provided by the client.
CompanyFileStringSets the path to a QuickBooks company file (.qbw). If this is not set, the currently open company file is used. When QuickBooks is not running, this option must be set.
PasswordStringSets the password of the user. This is required when AuthMode is set to 0 (Basic Authentication). The Remote Connector application will always store the SHA-256 hash of the password for security. However, this may also be manually set to a plaintext password to allow backward compatibility.
AuthModeDWORDSets the type of authentication to perform when the user connects. From the client side the process of connecting is exactly the same no matter which option you choose. Possible values are the following:
  • 0 (Basic Authentication - default)
  • 1 (Windows Authentication)
AuthorizedDWORDSpecifies whether the AppName has been authorized for the CompanyFile. If 1 (True) the AppName has been authorized with the CompanyFile. This is an indicator used by the application when changing settings in the UI.
ConnectionModeStringSets the connection mode for the user. The default is DontCare. In most cases you do not need to set this value. If this is not set, the application will connect in whatever mode QuickBooks is already open in. Possible values are the following:
  • DontCare (default)
  • Single
  • Multi
ReadOnlyDWORDSpecifies whether the user has read-only (1) or full access (0).

Copyright (c) 2016 CData Software, Inc. - All rights reserved.
Build 6.0.5975.0