Skip to content

Knowledge Base

Business Process Automation Platform

Sage 50 Accounts Connector v2.8

What is the Sage 50 Accounts Connector v2.8?

Introduction to the Sage 50 Connector

The Sage 50 Accounts Connector allows you to automate the management of your Sage 50 Accounts company data.

You can carry out tasks such as retrieving information from a company or executing an operation to automatically CREATE, UPDATE, or DELETE items such as invoices, sales orders, or business partners. Company objects and fields are mapped to BPA Platform data at runtime.

When combined with other tools of BPA Platform, the Sage 50 Connector allows you to synchronise data between two systems that do not naturally talk to each other; for example, your Sage 50 Accounts system and a web shop such as Magento.

The Sage 50 Connector uses XML as its input and output data format.

Sage 50 Integration – System Requirements

This tool requires BPA Platform (formerly “TaskCentre”) 2020 Update 1 (build 6466) or above.
The latest version of this tool is compatible with the following versions of Sage 50 Accounts:

  • Sage 50 Accounts 2013 (v19)
  • Sage 50 Accounts 2014 (v20)
  • Sage 50 Accounts v21 (2015)
  • Sage 50 Accounts v22 (2016)
  • Sage 50 Accounts v23 (2017)
  • Sage 50 Accounts v24 (2018)
  • Sage 50 Accounts v25 (2019)
  • Sage 50 Accounts v26 (2020)
  • Sage 50 Accounts v27 (2021) — Up to Service Pack 1
White Paper - Sage 50 Accounts Connector Tool 2.8

White Paper - Sage 50 Accounts Connector Tool 2.8

The Sage 50 Accounts Connector v2.8 Technical Overview describes the features available in the Connector. The Sage 50 Accounts Connector provides connectivity between BPA Platform and a Sage 50 Accounts company database.

The tool pack includes a separately installed Agent that acts as an intermediary to maintain the connection betwen BPA Platform and the Sage 50 Accounts API at runtime.

This Technical Overview introduces you to all available features of this release.

Download White Paper

Sage 50 Connector Architecture

The diagram below provides a high-level architectural view of Sage 50 integration using the Sage 50 Connector with BPA Platform, the Sage 50 Accounts Client, and Sage 50 Accounts database.

Sage 50 Accounts Connector v2.8

Working with Other Tools

The Sage 50 Connector can directly interact with the following BPA Platform tools:

Consuming XML from Other Tools

The Sage 50 Connector can consume output from the following tools:

IconTool NameTool Category
Import Flat File ToolImport Flat FileInput
Sage 50 Accounts Connector v2.8Import XML DocumentInput
Sage 50 Accounts Connector v2.8Convert Recordset to XMLFormat
Sage 50 Accounts Connector v2.8Transform DataFormat
Sage 50 Accounts Connector v2.8Call TaskExecute
Sage 50 Accounts Connector v2.8Sage 50 Accounts ConnectorData Connectors

Objects Consumed

The Sage 50 Accounts Connector consumes the following objects exposed by other steps:

  • XML — XML data from any BPA Platform tool capable of exposing such data (see above)

Exposing XML to Other Tools

The following tools can consume the XML outputted by the Sage 50 Accounts Connector:

IconTool NameTool Category
Convert XML to Recordset ToolConvert XML to RecordsetFormat
Run Microsoft Reporting Services ToolRun Microsoft Reporting ServicesFormat
Sage 50 Accounts Connector v2.8Transform DataFormat
Sage 50 Accounts Connector v2.8Save FileOutput
Sage 50 Accounts Connector v2.8Call TaskExecute
Sage 50 Accounts Connector v2.8Web Service ConnectorData Connectors
Sage 50 Accounts Connector v2.8Sage 50 Accounts ConnectorData Connectors

Objects Exposed

The Sage 50 Accounts Connector tool outputs the following objects which can be consumed by other tools:

Sage 50 Accounts Connector v2.8

  • InputData
    This document contains the XML received by the Sage 50 Connector tool. It is only available if a task step has been selected as the Data Source (see About the General Tab).
  • OutputData
    The OutputData object contains two sub-objects:

    • XmlString — This is the XML document produced by the tool, containing data returned from Sage 50 Accounts for all operations. Also included are the key fields for the mapped elements affected by the
      used operation — for example, if using a CREATE operation, the key fields for the top-level object instances that are created are returned — and a SupplementaryReference field for task auditing purposes.
      The mapped fields in the Mapping tab (see About the Mapping Tab) define the structure of this XML
      document.
    • XmlSchema — This contains the output schema in XSD format.
  • ErrorData
    The ErrorData object also contains two sub-objects:

    • XmlString — This contains any error data reported by Sage 50 Accounts
      <Error> — All errors are created as an <Error> node, with the following sub-nodes:
      <Object /> — The name of the requested object
      <CODE /> — The error code returned by Sage 50 Accounts
      <MESSAGE /> — The corresponding error message
      <EXTENDEDINFO /> — A string containing additional information about the error
      <INPUTDATA /> — The header input data (excluding child nodes) mapped for the object, plus all data contained in SupplementaryReference
      </Error>
    • XmlSchema — This contains the output schema in XSD format.
  • Step Properties
    Standard step properties are also available allowing you to use statistical data of the Sage 50 Accounts Connector step.

Where Can the XML Output be Used?

The incoming XML is translated into the XML format for the object and operation selected in the configuration. The data for the linked fields is brought across into the output XML — only those fields that are linked are brought across. The XML is passed to the Connector, which then:

  • Processes the data
  • Performs the operation requested
  • Recieves an XML document containing the response

Both the OutputData and ErrorData documents can be directly used by succeeding task steps that can consume XML data, as part of an application integration or synchronisation process. To use the documents in a non-XML consuming tool, use a Convert XML to Recordset step first to create a recordset copy of the XML data.

The XML documents are also available as consumable objects from the BPA Platform Browser (XmlString). When used in a task step, such as Format as Text or Save File, this exposes the actual XML string.

Error Handling

Errors are written to the BPA Platform Event Log (Tasks toolbar > Event Log). You define how errors are handled in the Options tab of the Sage 50 Accounts Connector tool.

Reasons for the errors could include:

  • Web service connection errors
  • User privilege errors
  • Errors from the Sage 50 Accounts API
  • Warnings and messages from the Sage 50 Accounts API

About the Sage 50 Integration Agent

To communicate with the Sage 50 Accounts company database, you must install the Sage 50 Accounts Connector Integration Agent on the same computer hosting the Sage 50 Accounts client. This acts as a “go-between”, updating and retrieving your Sage 50 Accounts data for the Sage 50 Accounts Connector installed on BPA Platform.

Connecting to Sage 50 Accounts

The global configuration for this tool is used to create a connection to the Sage 50 Accounts Integration Agent monitoring the company database. You open this interface from the resources tree — expand System > Tools > Data Connectors and double-click Sage 50 Accounts Connector in the items list.

Sage 50 Accounts Connector v2.8

From here, create a new connection (Add), or modify an existing connection (Edit).

Using Extended Logging

Enabling this option exposes the XML parsed between the Sage 50 Accounts Connector and Sage 50 Accounts.

Without extended logging, the Event Log only contains start and end of transaction messages, plus any error messages encountered at runtime.

You can view the extended log in the BPA Platform Event Log (Tasks toolbar > Event Log).

About the Connection Settings Tab

You configure the connection to the Sage 50 Accounts Connector Integration Agent here.

Sage 50 Accounts Connector v2.8

Configure a meaningful Connection Name for this Agent connection; this is the Connection name used when Sage 50 Connector task steps.

Specify the Server Name of the computer hosting the Sage 50 Accounts Integration Agent. You can use either the hostname or IP address.

By default, the connection to the server is over HTTP, on TCP port 4105. Use the Advanced button to either Set a Custom Port Number if 4105 is already in use by the server, or to Use HTTPS to communicate to the server.

Sage 50 Accounts Connector v2.8

Update Objects and Operations

Enabling Update Objects and Operations allows the Sage 50 Accounts schema in BPA Platform to be refreshed every time an update is made in Sage 50 itself.

Should you also upgrade Sage 50 Accounts to a newer, compatible version, all related schemas within BPA Platform must be refreshed. To do this, select this option and save the changes. You must repeat this for each existing connection you have defined.

About the Company Tab

You must specify the Company database which the Sage 50 Accounts Integration Agent connects to.

Sage 50 Accounts Connector v2.8

Choose the relevant Database Version from the drop-down.

About the Authentication Tab

You configure the Sage 50 Accounts credentials here that allow access to the company database the Sage 50 Accounts Integration Agent is monitoring.

Sage 50 Accounts Connector v2.8

Step Configuration

When creating new tasks, the Sage 50 Accounts Connector is located under Data Connectors of the Task Browser.

To add a new Sage 50 Accounts Connector step to an existing task, do the following:

From the relevant task, either:

  • Click and drag the Sage 50 Accounts Connector icon from the Task Browser to the task Design area.
  • From the task’s Design tab, right-click on empty space and select New > Data Connectors > Sage 50 Accounts Connector.

For a detailed description of how to create new tasks, refer to the product help.

About the General Tab

Use the General tab to choose the BPA Platform data source to be mapped to the Sage 50 Accounts objects. The data source must be in XML form. To map BPA Platform recordsets, configure a Convert Recordset to XML or Transform Data step in the task before the Sage 50 Accounts Connector step, then select this as Task step (see below).

Sage 50 Accounts Connector v2.8

Provide a meaningful Name and Description for this step.

Data source can either be:

  • No data source — If you don’t make use of a dedicated XML input source, select this option to use BPA Platform variables in place of the XML or recordset objects’ fields.
    For example, you can extract various bits of information from an email and store them in BPA Platform variables. The variables are mapped to Sage 50 Accounts operational objects and fields to store in the database for later use
  • Task step — The data source can be set to an available BPA Platform XML data source.
    Only those steps that are capable of natively exposing an XML document at runtime are listed. This may be another Sage 50 Accounts Connector step, or a tool such as Convert Recordset to XML or Transform Data.
  • Custom schema — An XML schema defines the structure of the parsed XML: what tags are present, and the nesting of the tags. You Define the schema of the XML that is used as the input data source for this step. The Sage 50 Accounts Connector tool uses the industry standard XSD format. Any XML processed by this step must conform to this schema else an error will be reported.
    If the XSD schema is available, either import it into the Custom Schema Configuration (use the Import XSD/XML File button), or copy and paste it into the configuration box.
    Sage 50 Accounts Connector v2.8
    If the XSD schema is not available, you can import an example of the runtime XML (Import XSD/XML File), or copy and paste it into the configuration box. Use the Parse button to create the schema.

    • Input source variable — As well as defining the schema, specify the BPA Platform variable that contains the XML data at runtime.

About the Connection Tab

You must specify the Sage 50 Accounts Connection this step must use.

Sage 50 Accounts Connector v2.8

All connections created in the global configuration window are presented here.
Alternatively, you can use a BPA Platform variable or formula to create a dynamic connection, where the connection used is determined by runtime circumstances. At runtime, the contents of the variable must match the name of one of the Global Configuration connections — this is case-sensitive.

About the Mapping Tab

Here you define links between the incoming XML and the outgoing data that is sent to Sage 50 Accounts. This defines how, at runtime, the incoming XML is to be translated into the XML required for the relevant object and operation.

Sage 50 Accounts Connector v2.8

The Object drop-down shows the Sage 50 Accounts objects. The Operations drop-down shows the operations available for the selected Object.

Further down, the left-hand XML tree structure shows those data source fields available for mapping. The right-hand XML tree structure displays those input fields for the selected Object and Operation.

Creating Mappings

Create links by dragging and dropping a data source field (left) onto its corresponding Sage 50 Accounts Connector input field (right). Only linked fields are used in the output XML.

BPA Platform formulas and variables can be included in the source data even when using a Task step or Custom schema — drag them from the BPA Platform Browser to the data source’s XML; these can then be linked to the relevant input fields. BPA Platform recordsets must first be converted to XML using either the Convert Recordset to XML or Transform Data tool before they can be used here.

Each operation has an additional field, Supplementary Ref, which allows for traceability when transferring data from one place to another. When mapped, the data resides locally at runtime. It is added to the output, and creates a record for reference purposes only — you can choose to map any field to Supplementary Ref to assist with checking where the data originated from or at what time the data transfer occurred, for example.

The Sage 50 Accounts Connector tool uses eXtensible Stylesheet Language Transformations (XSLT) to translate the received XML. The Advanced Translations (XSLT) tab shows the XSLT generated for the links created for the object and operation. Use Enable Free Type Mode to directly edit the XSLT — this is particularly useful when translating a non-standard requirement.

Supported Objects

The following Sage 50 Accounts objects and operations are supported. Data elements in bold are keys.

ObjectOperations
 CREATEREADSEARCHUPDATEDELETENotes
Currency DataNo mandatory fields  
CustomerAccount RefAccount RefNo mandatory fields, although Account Ref is still the key.Account RefAccount RefNOTE: Due to an anomaly in the Sage API, all RECEIPTS* fields are actually PAYMENTS* fields, and PAYMENTS* fields are RECEIPT* fields when viewing in the Sage 50 client and in the XML passed back to the Sage 50 Connector.
InvoiceInvoice Number Limited to 4 digitsNo mandatory fields.Invoice Number Limited to 7 digitsAdditional supported operations:
POST:

  • Account Reference
  • InvoiceItem (child object)
    • Stock Code

SEARCH (including Lines)

  • No mandatory fields
Invoice LineSingle supported operations:
UPDATE LINE:

  • Invoice Number Limited to 4 digits
Purchase LineSingle supported operations:
UPDATE LINE:

  • Stock Code
Purchase OrderOrder NumberNo mandatory fields.Order NumberOrder NumberAdditional supported operations:
POST:

  • Account Reference
  • Invoice Number
  • Order Date
  • Order Number
  • Order Type Code
  • POPItem (child object)
    • Stock Code

SEARCH (including Lines)

  • No mandatory fields
Sales LineSingle supported operations:
UPDATE LINE:

  • Stock Code
Sales OrderOrder NumberNo mandatory fields.Order NumberOrder NumberAdditional supported operations:
POST:

  • Account Reference
  • Order Date
  • Order Type Code
  • SOPItem (child object)
    • Stock Code

SEARCH (including Lines)

  • No mandatory fields
StockStock CodeStock CodeNo mandatory fields.Stock CodeStock Code
Stock Transaction PostSingle supported operation:
POST TRANSACTION

  • Stock Code
  • Quantity
  • Transaction Type
Transaction PostSingle supported operation:
POST TRANSACTION

  • Sales/Purchase/Bank Account Reference
  • Transaction Type
  • SplitData (child object)
    • Net Amount
    • Nominal Code

About the Options Tab

The Options tab allows you to define how errors in this step are handled at task runtime.

Sage 50 Accounts Connector v2.8

If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Step).

If the step is aborted, you can choose to Continue processing onto the next step in the task, or terminate the whole task immediately (Abort Task). By allowing the task to Continue, you can use the error XML received back in a Save File step for investigation purposes, for example.

If a connection errors occurs (to the Sage 50 Accounts Integration Agent or the Sage 50 Accounts company database during task runtime), you can decide whether to Continue processing onto the next step in the task, or terminate the whole task immediately (Abort Task).

White Paper - Sage 50 Accounts Connector Tool 2.8

White Paper - Sage 50 Accounts Connector Tool 2.8

The Sage 50 Accounts Connector v2.8 Technical Overview describes the features available in the Connector. The Sage 50 Accounts Connector provides connectivity between BPA Platform and a Sage 50 Accounts company database.

The tool pack includes a separately installed Agent that acts as an intermediary to maintain the connection betwen BPA Platform and the Sage 50 Accounts API at runtime.

This Technical Overview introduces you to all available features of this release.