Table of Contents

Reckon Web Connector Overview

Overview

Reckon Web Connector lets users to connect their preferred cloud application with their desktop Reckon Accounts company file.

Installation is to the Windows desktop alongside the Reckon Accounts Desktop application, and minimises to the system tray. It is designed to run in the background, and initiates communication with a web application using scheduled events defined via a Schedule minutes value saved inside the Connection settings.


How to get started

  1. Read the Technical details to understand how Reckon Web Connector works.
  2. Add your App to our Development environment of Connected Apps list by emailing apisupport@reckon.com with the required details.
  3. Start developing your integration with Reckon Web Connector.
  4. Install Reckon Web Connector and start testing your integration. Make sure you update the config file to connect Reckon Web Connector with the Development environment.
  5. When your integration is completed, let us know by emailing apisupport@reckon.com and we will review your app.
  6. Once your app is approved, we will add your App to the Production environment of the Connected Apps list. You will need to change your config file back to the Production environment.
  7. Our mutual user can now connect their Reckon Accounts company (*.QBW) file with your app.


Technical details

Authorisation for 3rd-party applications

Currently, Reckon Web Connector supports Basic Authorisation only. It passes the username and password in base64 encoding to the provider in the request header. The 3rd-party app provider will then take the required steps to authorise access to the resources for the user.

In future versions, we are planning to implement oAuth2.0. The required details will be collected from the 3rd party app providers during the onboarding process.

Connection parameters

Connection parameters are set and stored in the Reckon Web Connector application on the Windows desktop via a user interface. Connection parameters include: 

Type

Required?

Value

Connection Name

Required

A name that you want to identify the connection with. Users will probably use the 3rd party app's name here.

Minutes value for scheduled connection initiation

Required

Define the schedule time when the sync process will run.

Connection Status (Active/Paused)

Required

If it's Active, the sync process will run in the scheduled period, otherwise, it will not.

Path to the Reckon Accounts company data (*.QBW) file.

Required

Choose the company file that the user wants to connect with. The user needs to verify the path first by clicking the Verify button.

Connected app name

Required

Selected from a list retrieved from the Reckon server during the connection setup. All connections must first approved by Reckon before they will appear here.

Username

Based on 3rd party app

Connected App's Username (i.e. the Username required to connect to the 3rd party app).

Password (for Basic Auth)

Based on 3rd party app

Connected App's Password (i.e. the Password required to connect to the 3rd party app).

Connection Id

Based on 3rd party app

Unique ID from the provider to identify the user’s connection between Reckon Web Connector and the 3rd party app.

Endpoint URL for GET “initiate communication”

Required

Hidden from the user and retrieved from the Reckon server during connection setup. This URI is supplied by the 3rd party provider for the user to connect their Reckon Accounts company file with their connected app.


Communication

For a web application to successfully integrate with Reckon Accounts desktop via the Reckon Web Connector client application, two REST methods must be implemented via a web service or similar. 

Method 1: GET

Key

Required?

Value

Content-type

Required

Application/JSON

Parameters

See below.

Connection id

Optional

Specific to web application

State

Optional

Value set from previous callback POST response object IF immediate connection repeat was signaled in response to callback POST request

  • The endpoint URL for this method is provided to Reckon along with the web application name for publishing by the 3rd party provider during onboarding. These details are downloaded by Reckon Web Connector from the Reckon server and the endpoint URL is automatically set when the user selects the relevant “Connected app” from the list in the add/edit connection dialog during setting up their connection.
  • Reckon Web Connector calls this method per the connection schedule and creates the URL as follows:
    endpoint url from provider + “?id=” + <connection id parameter> + “&state=” + <state parameter>
    Example URL:
    https://www.reckon.com/ConnectorService.svc/WCInitCommunication?id=12345&state=state_ref
  • The “state” parameter is specific to the web application and is optionally relevant where an immediate repeat communication event is requested by setting the “repeatCommunication” member value to “true” in the POST callback response to the next GET request sent by the RWC. Please note: this parameter will be blank in the case of a scheduled communication event.

Basic Auth header will be included by the Reckon Web Connector with ‘Username’ and ‘Password’ values as stored in the connection settings for the specific connection.

Expected JSON response object:

The expected response includes the following members:

Key

Type

Details

postURL

String

Fully qualified callback URL to post result to (includes method name)

qbXMLRequest

String

QBXML to process against Reckon Accounts data file specified in connection settings

tryAgainIn

Integer

If the host service is not ready at the time of the scheduled communication initiated from the Reckon Web Connector, the "tryAgainIn" value can be set to an integer value representing the number of minutes from receipt of the response that the retry should occur.

  1. A "tryAgainIn" value of 0 will be ignored.
  2. If the "tryAgainIn" value is set but a qbXMLRequest is provided in the response, the retry request will be ignored and the web connector client app will attempt to process the provided QBXML and send a response.
  3. If the "tryAgainIn" value received represents a time that is 60 seconds or less from the next scheduled communication attempt by the web connector client app, it will also be ignored.

Example:

{
    "postURL":"https://www.reckon.com/ConnectorService.svc/WCQBXMLResult", 
    "qbXMLRequest":"<?xml version=\"1.0\"?><?qbxml version=\"6.1\"?><QBXML><QBXMLMsgsRq onError=\"continueOnError\"><CompanyQueryRq /></QBXMLMsgsRq></QBXML>", 
    "tryAgainIn":0
}


Method 2: POST (callback Method)

Key

Value

callback URL

Full URL specified in “postURL” member of JSON response to inital GET request).

Content-type

Application/JSON.

Must return an integer value.

Header

Basic Auth will be included in the Header by the Reckon Web Connector with ‘Username’ and ‘Password’ values as stored in the connection settings for the specific connection.

Accept

Application/JSON

Response

Example JSON object (QBXML abbreviated for brevity):

{
    "qbXMLResponse":"<?xml version=\"1.0\" ?><QBXML><QBXMLMsgsRs><CompanyQueryRs statusCode=\"0\" statusSeverity=\"Info\" statusMessage=\"Status OK\"><CompanyRet>...</CompanyRet></CompanyQueryRs></QBXMLMsgsRs></QBXML>",
    "connectorId":"12345",
    "errorCode":"",
    "errorMsg":""
}

Detail of the request object:

Key

Type

Details

qbXMLResponse

String

Will contain the QBXML response to the QBXML request provided by the prior GET initiate communication call.

connectorId

String

Will contain the connector id corresponding to the connection settings that initiated the communication.

errorCode

String

Populated with the Windows exception code if an error occurs during the attempt to process the QBXML provided in response to the prior GET request.

errorMsg

String

Populated with a string representation of an error that has occurred during the attempt to process the QBXML provided in response to the prior GET request. In this instance it is likely that the "qbXMLResponse" value will be empty. Examples of errors that may occur are "Could not access Reckon Accounts" and "BeginSession timeout"


Reckon Web Connector expects a JSON Response object to this callback POST request including two properties:

  1. repeatCommunication: A value of “true” returned for “repeatCommunication” will signal the Reckon WebConnector to immediately initiate communication again with a new “initiate communication” GET request. Otherwise a value of “false” should be returned to signal the end of this communication cycle.
  2. state (string): In the case that an immediate repeat of the communication cycle is requested, (i.e. “repeatCommunication” value is “true”), the “state” property may be set to a value relevant to the web application. This value will be sent as a parameter with the next “initiate communication” GET request. This value is NOT sent when a scheduled (usual) communication cycle event occurs.

Example JSON callback response object:

{
    "repeatCommunication":true,
    "state":""
}

The integrated web application can use the “repeatCommunication” property if they want to connect again immediately to process additional QBXML instead of waiting for the next scheduled communication event. For example, if after synchronising the Customer list, the integrated web application now requires a list of recent Invoices relating to new Customers. Please note that a value of “true” will be ignored if the response is received 60 seconds or less before a scheduled communication cycle is set to occur.


If you need to keep track of matching requests/responses, the QBXML has an inbuilt facility to do this via requestID which can be set in the request and will be returned with the response...

For example:

If you send a request with the below requestID:

<CustomerQueryRq requestID="223334">

The response will be something like:

<CustomerQueryRs requestID="223334" statusCode="0" statusSeverity="Info" statusMessage="Status OK">

The requestID allows you to link a QBXML response to the request that generated it.


Support for QBXML Iterators

QBXML provides an Iterator feature which facilitates a query being split into multiple result sets. Each part of the entire result set is then retrieved individually, so the data transfer for each part is much smaller and faster. Iterators are only available for the duration of a RA SDK session (or until the “IteratorRemainingCount” reaches '0'). In version 1.0.0.0 of the Reckon Web Connector (RWC), each communication cycle involved a new SDK session, and as a result, QBXML iterators were not functionally available as the iterator would become undefined after each request. Changes were made in version 1.0.1.0 of the RWC to support QBXML iterators with some caveats:

The SDK session (and by extension a QBXML Iterator) remains available IF:

  1. The QBXML is received in response to a GET “initiate communication” request which is the result of a POST callback response where “repeatCommunication” is set to true and;
  2. If the repeat communication is for the same Connection as that associated with the last QBXML processed and;
  3. If the QBXML is received within 30 seconds of the completion of processing of the last QBXML received and;
  4. If the QBW company data file specified is the same as that specified for the previous request

The above conditions exist due to the fact that a RA SDK session can only process requests for a single QBW company file and must be closed and reopened to process QBXML for another QBW company file; that the RWC allows and manages multiple connections for different QBW data files on different schedules; and it is undesirable for the health of the system to leave an SDK session open for an extended period.

Whilst a single Connection or a small number of Connections with sufficiently varied schedules should not experience issues with use of QBXML Iterators, due to the above considerations, support for Iterators should be managed (i.e. code structured accordingly) to recover as necessary in the event that a QBXML Iterator becomes undefined if a request sequence is impacted by another Connection schedule. An undefined Iterator could also occur if the Reckon Accounts application itself encounters an unexpected error during processing and as such, making allowance for the possibility of an undefined Iterator is recommended practice in RA SDK programming.


Reckon Web Connector Workflow


If you have any questions, please send an email to apisupport@reckon.com.

How did we do?

Add your app to the Connected Apps

Related Articles

Settings overview - Reckon Payroll (Web)
Installing and configuring Reckon Web Connector for Reckon Accounts Desktop
Installing and Configuring Reckon Web Connector for API Products
Powered by HelpDocs (opens in a new tab)

Powered by HelpDocs (opens in a new tab)