Sage CRM Connector 1.3

What is the Sage CRM Connector Tool?

The Sage CRM Connector tool allows communication between BPA Platform and a Sage CRM database. All communication uses XML. You use the Connector to map BPA Platform data to Sage CRM objects and operations. Operations such as, ADD, UPDATE, QUERY, and DELETE, are supported for a variety of business objects, such as, Person, Order, and Company — for a detailed list, see Supported Objects.

User-defined fields and objects created in Sage CRM are also supported. For example, you can use the Sage CRM Connector to provide an indirect link between systems that do not typically synchronise data with each other, such as synchronising sales orders from an eCommerce platform to the Sage CRM database, or even to provide reports containing data from both systems.

The XML responses received back from the Sage CRM API can be saved to file, or passed to another BPA Platform tool for further processing. The responses can include details of the object requested, any errors from the provider, or the values of any automatically generated ID fields.

White Paper - Sage CRM Connector 1.3

The Sage CRM Connector tool allows communication between TaskCentre and a Sage CRM database. All communication uses XML. You use the Connector to map TaskCentre data to Sage CRM objects and operations. Operations such as, ADD, UPDATE, QUERY, and DELETE, are supported for a variety of business objects, such as, Person, Order, and Company. User-defined fields and objects created in Sage CRM are also supported.

The Sage CRM Connector white paper describes how to use the tool.

Download Brochure

The Sage CRM Connector Tool Pack

The tool pack consists of:

• Sage CRM Connector Agent — The Agent communicates with Sage CRM via the Sage API. It runs as a service on the installed machine, passing requests between BPA Platform and the API. The API also makes the Agent aware of any user-defined fields and objects in Sage CRM so these can be passed back to the Connector tool and made available for use in BPA Platform.
• Sage CRM Connector — The Connector is a BPA Platform tool, used to communicate with the Sage CRM Connector Agent. It must be installed on the BPA Platform machine, and on any BPA Platform client machines. It is this that provides the translation between BPA Platform data and Sage CRM object and operation.

System Requirements

The Sage CRM integration tool requires BPA Platform (formerly TaskCentre) 4.7 or above. This tool is compatible with the following versions of Sage CRM:

• Sage CRM 7.3
• Sage CRM 2017 R1 and R2
• Sage CRM 2018 R1 to R3 inclusive
• 2019 R1 and R2
• 2020 R1 and R2
• 2021 R1 and R2

Sage CRM Integration Architecture

The diagram below provides a high-level system architecture overview of the Sage CRM Connector tool pack, with BPA Platform and the Sage CRM server:

Depending on your organisational needs, you can choose to have the Sage CRM Connector Agent located on the same machine hosting the Sage CRM server, or on a separate independent machine.

About the Sage CRM Connector Agent

In order to communicate with the Sage CRM server, you must install the Sage CRM Connector Agent. This acts as a “go-between” between the Sage CRM server and Sage CRM Connector tool, and runs as a service on the installed machine. Note that it is not necessary to install the Agent on the same machine hosting the Sage CRM server, you can choose to locate the Agent on a separate machine.

About the Sage CRM Connector Tool

Global Configuration

The global configuration for this tool is used to create connections to the Sage CRM Connector Agent, and the Sage CRM instance. You access the Global Configuration dialog box via System > Tools > Data Connectors > Sage CRM Connector.

When a connection is created, the available objects and fields of Sage CRM are retrieved.

Click Add to create a connection to Sage CRM.

Using Extended Logging

Enabling this option exposes the XML parsed between the Sage CRM Connector and SageCRM.

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 (Manage > Event Log).

About the Agent Connection Tab

You configure the connection to the Sage CRM Connector Agent here.

Configure a meaningful Connection Name for this agent connection; this is the name displayed when adding task steps for Sage CRM.

Within Connector Agent Server, specify the address of the machine hosting the Sage CRM Agent. You can use either the hostname or the IP address.

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

About the Sage CRM Connection Tab

You configure the connection to the Sage CRM server here. These details are passed to the Sage CRM Connector Agent to allow it to communicate with the Sage CRM server.

Within Server address, specify the address of the machine hosting the Sage CRM server. You can use either the hostname or the IP address.

Specify the Web service instance created on the Sage CRM server to allow the Connector tool to manipulate data.

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

About the Authentication Tab

You configure the Sage CRM credentials here that allow access to web service instance specified in the Sage CRM Connection tab.

About the Sage CRM SQL Database Connection Tab

If required, you can configure the connection to the SQL Server for Sage CRM itself.

The configuration for this tab is optional, and only required if the address_type and person_type objects are needed. Where an address is added to a Company or Person record, you can specify an address type of:

• Billing
• Shipping
• Business (for Company Address records only)

Note that a combination of types can be allocated to one address.

Similarly, when adding a Person record, the following types can be allocated:

• Admin
• Finance
• Operations
• Sales
• Support

Specify Server Address as either the hostname or IP address of the server hosting the Sage CRM SQL Server database.

Specify the Sage CRM’s Database Name.

Configure the SQL Server database credentials (SQL Server Login and Password) that allow access to the Sage CRM database.

Clicking Enable Link Objects instructs the Agent to make a call to the Sage CRM database to enable the link objects, and to query the link objects as supported objects.

Update Objects and Operations

Enabling this option allows the Sage CRM schema within BPA Platform to be refreshed every time an update is made in Sage CRM itself.

Should you also upgrade Sage CRM to a newer, compatible version, all related schemas within BPA Platform will be refreshed.

Test Connection

The Test Connection button is visible on every tab. Using this feature allows you to test the connection to the Sage CRM Connector Agent, and from there to the Sage CRM instance.

Step Configuration

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

About the General Tab

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 objects’ fields. These can then be mapped to operational fields.
  For example, you can extract various bits of information from an email and store them in BPA Platform variables. Then, having mapped them to Sage CRM objects and operations, these can be stored in the Sage CRM 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. These may be another Sage CRM Connector step, or a tool, such as Convert Recordset to XML.
• 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 will be used as the input data source for this step. The Sage CRM 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.

  

  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 specify the Sage CRM Connection this step must use.

All connections created in Global Configuration are presented here.

Alternatively, you can use a BPA Platform variable 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 CRM. This defines how, at runtime, the incoming XML is to be translated into the XML required for the relevant object and operation.

The Object drop-down shows the available Sage CRM objects. User-defined objects, if exposed, are also made available for selection here. The Operations drop-down shows the operations available for the selected Object. For more information about which operation is available for an 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.

Create links by clicking and dragging a data source field (left) onto its corresponding Sage CRM 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, SupplementaryReference, 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 SupplementaryReference to assist with checking where the data originated from or at what time the data transfer occurred, for example.

The Sage CRM 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.

About the Options Tab

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

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). Allowing the task to continue allows you to use the error XML received back in a Save File step for investigation purposes, for example.

Working with Other Tools

The Sage CRM Connector can directly interact with the following tools:

Consuming XML from Other Tools

Icon	Tool Name	Tool Category
	Import Flat File	Input
	Import XML Document	Input
	Convert Recordset to XML	Format
	Transform Data	Format
	Call Task	Execute
	Web Service Connector	Data Connectors
	Sage CRM Connector	Data Connectors

Exposing XML to Other Tools

Icon	Tool Name	Tool Category
	Convert XML to Recordset	Format
	Run Microsoft Reporting Services	Format
	Transform Data	Format
	Save File	Output
	Call Task	Execute
	Web Service Connector	Data Connectors
	Sage CRM Connector	Data Connectors

Supported Objects

Provision of supported objects and operations are handled independently to the tool pack. This means subsequent changes to the API’s metadata can be made available to instances of the Sage CRM Connector tool without the need to reinstall or upgrade.

At the time of writing, the following objects are supported:

Tool Output

The Sage CRM Connector tool outputs two documents:

• OutputData
• ErrorData

All outputs can be:

• Used directly by subsequent tool steps which consume XML data inputs
• If required, use the Convert XML to Recordset tool to convert the XML to a BPA Platform recordset first
• Accessed using the output or error objects for response data (XmlString), or the output or error schema (XmlSchema) present in the Task Browser; for example, saving to file or for inclusion within an email.

About the OutputData XML Document

The OutputData document contains:

• Data returned from Sage CRM for a Query operation
• The key fields for the entity instances affected by the used operation
  For example, if using an ADD operation, the key fields for the top-level object instances that are created are returned.
• SupplementaryReference

About the ErrorData XML Document

The ErrorData document is structured as follows:

• <Error> — All errors are created as an <Error> node, with the following sub-nodes:
• <Object /> — The name of the requested object, such as, PurchaseOrder.OrderHeader_main
• <CODE /> — The error code returned by Sage CRM
• <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 the SupplementaryReference field
• </Error>

Runtime

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 were linked are brought across. The XML is passed to the connector tool, which then:

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

The XML can then be used by other BPA Platform steps.

Error Handling

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

Reasons for the errors could include:

• Web service connection errors
• User privilege errors
• Errors from the SageCRM API
• Warnings and messages from the SageCRMAPI

SageCRM Accounts Security

The SageCRM API is the only method used to connect to a database, and perform read / write tasks — all security present in the API is used.