Applications Platform Connector Tool

Introduction to the Applications Platform Connector Tool

What is the Applications Platform Connector Tool?

The Applications Platform Connector tool allows communication between Applications Platform and BPA Platform. All communication uses XML. You use the Connector to map BPA Platform data to Applications Platform objects and operations

The XML responses received back from Applications Platform 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, or the values of any automatically generated ID fields.

You can use the Applications Platform Connector to provide an indirect link from your Applications Platform installation to other systems that BPA Platform is connected to. For example, if you make use of the Web Portal in Applications Platform, and have your CRM system connected to BPA Platform, you can make CRM data available to the Web Portal via the Applications Platform Connector.

Features

The following features are available:

• Uses XML
• Allows for synchronisation between Applications Platform and a third party system
• Drag and drop facility for mapping BPA Platform data to your Applications Platform installation; only map what you require to be sent and retrieved by the operations
  • Visual links to easily identify the mappings between the incoming data of the XML source and the outgoing data to be sent to Applications Platform

White Paper - Applications Platform Connector Tool

This white paper introduces you to the Applications Platform Connector tool.

Download White Paper

System Requirements

The BPA Platform server that is running the Applications Platform Connector tool, must have an internet connection for it to function correctly. This is because the metadata used is hosted in the Applications Platform cloud.

Architecture

The diagram below provides a high-level system architectural overview of the Applications Platform Connector with BPA Platform and the Applications Platform tenant:

The Applications Platform Connector must be installed on the same machine hosting the BPA Platform client that runs the Applications Platform Connector tasks.

The Applications Platform Connector communicates with Applications Platform’s SOAP web service. It is through this that communication with the Applications Platform tenant is achieved.

Working with Other Tools

The other tools that an Applications Platform Connector step can interact directly with, either by exposing information to it or consuming information from it, are listed below:

Consuming XML from Other Tools

The Applications Platform Connector can consume objects outputted by the following tools:

Icon	Tool Name	Tool Category
	Import XML Document	Input
	Retrieve Text Message	Input
	Convert Recordset to XML	Format
	Transform Data	Format
	Call Task	Execute
	Web Service Connector	Data Connectors
	Applications Platform Connector	Data Connectors

Objects Consumed

The Applications Platform Connector consumes the following objects exposed by other steps:

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

Exposing XML to Other Tools

Objects exposed by the Applications Platform Connector can be directly consumed by the following tools:

Icon	Tool Name	Tool Category
	Retrieve Text Message	Format
	Convert XML to Recordset	Format
	Run Microsoft Reporting Services	Format
	Save File	Output
	Call Task	Execute
	Applications Platform Connector	Data Connectors
	Web Service Connector	Data Connectors

Objects Exposed

The Applications Platform Connector tool outputs the following objects which can be consumed by other tools:

• InputData
  This document contains the XML received by the Applications Platform Connector tool. It is only available if a task step has been selected as the Data Source.
• OutputData
  The OutputData object contains two sub-objects:
• XmlString — This is the XML document produced by the tool, containing data returned from Applications Platform 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 mappings fields in 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 — XmlString — This contains any error data reported by Applications Platform
  <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 Applications Platform
  <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 Applications Platform 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
• Receives 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 Task 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 tool.

Reasons for the errors could include:

• Web service connection errors
• User privilege errors
• Errors, messages, and warnings from the API
• Any reported task runtime errors, such as, loss of connection

Supported Objects

Due to the nature of Applications Platform, all objects are user-defined, and therefore differ from installation to installation. All available objects in your Applications Platform installation are exposed in the incoming XML to the Applications Platform Connector.

The following operations are available for mapping for all objects:

• Create — Add a record to a specific object
• Batch Create — Add several records to a specific object
• Read — Retrieve objects for a specific object using a key
• Search — Search for records for a specific object based on provided parameters
• Update — Update a specific record, using a key, for a nominated object
• Batch Update — Update several records for a nominated object
• Delete — Delete or remove a specific record from an object, using a key
• Batch Delete — Delete or remove several records from an object
• Set File — Allows a file to be uploaded to Applications Platform from a specified directory location
• Get File — Allows a file to be downloaded from Applications Platform and saved to a specified directory location
• Set Field – Allows for certain fields to be updated without impacting the last modified date of the entire record (note that the API will pass each field amendment separately so individual changes per record are recommended)

Global Configuration

The global configuration for the Applications Platform Connector is used to create connections to Applications Platform.

You access the Applications Platform Connector — Global Configuration interface from the resources tree — expand System > Tools > Data Connectors and double-click Applications Platform Connector in the items list.

When a connection is created, the available objects and fields of your Applications Platform installation are retrieved.
Click Add to create a connection to Applications Platform.

Using Extended Logging

Enabling this option exposes the XML parsed between the Applications Platform Connector and Applications Platform.

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 Applications Platform Connection Tab

You provide the authentication details for your Applications Platform tenant in the Applications Platform Connection tab.

Provide a unique Connection Name. If your Applications Platform installation makes use of a number of separate tenants or applications, it is recommended you add such details to the name. This is used later when creating task steps.

Provide the Username and Password for the Applications Platform Connector to use when connecting to Applications Platform.

Global Variable to Store Session ID

If you plan to run concurrent tasks which contain Applications Platform Connector steps for this specific connection, it is recommended you do the following:

1. Create a global variable of Type: Variant.
2. Do not provide a Value.
3. Enter the new variable to Variable Name in the Global Variable to Store Session ID panel.

When concurrent Applications Platform Connector tasks are run, the task “sessions” are pooled and all use the same ID. When that session completes, a new ID is generated.

Clear Metadata Cache

The Applications Platform Connector caches the Applications Platform metadata for faster retrieval. From time-totime, you may have the need to reset the cache; use Clear Metadata Cache for such scenarios.

Update Objects and Operations

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

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

The schemas are refreshed when this selection and change has been saved. You must repeat this for each existing connection you have defined.

About the Server Tab

Use the Server tab to specify which Applications Platform tenant this connection is for.

From the Server drop-down, select either:

• Applications Platform to connect to the Applications Platform tenant the username and password (Applications Platform Connection tab) belong to. Note that each username and password combination is unique, and typically includes the tenant name as part of the username.
• Applications Platform Dev to connect to the sandbox environment of the Applications Platform tenant.

If required, use Custom time out to determine how long the Connector waits for the Applications Platform tenant to complete processing a request. In the majority of installations, the default time-out is sufficient so this parameter can be ignored.

Test Connection

Use Test Connection to ensure the Applications Platform Connector can communicate successfully with Applications Platform.

About the Options Tab

The Options tab allows you to set the formats used by your Applications Platform tenant.

Call Handling formats impact how the Applications Platform API is interacted with:

• Batch Enabled Operations — If required, you can force the Applications Platform Connector to carry out CREATE, UPDATE, or DELETE operations in batches. Rather than processing each individual XML record consumed from the data source (General tab), all records are processed at once. If required, add a comma-separated list of operations to run in batch mode.

Data Handling determines the data formats the Applications Platform Connector uses when communicating with the Applications Platform API:

• Send Empty Values to Server — By default, the Applications Platform Connector leaves out XML elements that have empty values. Change this to True to include such elements in the communication.
• User Language — At the time of writing, only English is supported. This is a read-only field.
• User Date Format — From the drop-down list, select the relevant date format used by your Applications Platform tenant. These must match.
• User Collation — When fetching data from the Applications Platform database, you can choose to use casesensitive queries. For such scenarios, the Applications Platform Connector uses the database collation specified here. If your installation of Applications Platform has a customised database, enter the database collation, else leave this as the default value.
• String Cast Type — If a mapped field in Applications Platform is a blob data type, use this option to specify the string-type data type (20 characters maximum) Applications Platform Connector must use instead.

Step Configuration

To add a new Applications Platform Connector step to an existing task, you either:

• Click and drag the Applications Platform 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 > Applications Platform 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 name the BPA Platform data source to be mapped to the Applications Platform objects. The data source must be in XML form. To map BPA Platform recordsets, configure a Convert Recordset to XML step in the task before the Applications Platform Connector step, then select this as Task step (see below).

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 Applications Platform 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 Applications Platform 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 is used as the input data source for this step. The Applications Platform 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 Applications Platform Connection this step must use.

All connections created in the 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 data source XML (see About the General Tab) and that required by Applications Platform. 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 Applications Platform 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 Applications Platform 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.

Additionally, reference fields are available which are suffixed with _id, _name, or _code, which reference lookup fields or pick-list items in the Infinite Blue Platform tenant. These can be mapped as required.

The Applications Platform 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.

Refreshing the Applications Platform’s Schema

If new fields and objects have been added to your Applications Platform tenant after this task step was originally created, use Schema Refresh to make the latest API objects and fields available for use.

Using Filters with Objects

When using SEARCH operations, you can make use of filters to limit the data involved. At runtime, these fields are treated as “where clauses”.
By default, all mapped fields are treated as “equal to” filters. To set a filter condition, right-click the required field and select Set Filter Condition. Change the filter condition as required.

Available filter conditions are:

The following filter conditions are also available, but require options in the global configuration’s Option tab to be set:

• =(CS) — Use this filter for case-sensitive queries. This filter uses the database collation specified for the User Collation parameter.
• =(CS-CAST) — If the mapped-to input field is a blob data type, use this filter to instruct the Applications Platform Connector to use the data type specified in the String Cast Type parameter instead.

The presence of multiple filter fields implies that all conditions must be met. Nominated fields must be mapped to be included in the output XML.

Nominated fields must be mapped to be included in the output XML. You add filter conditions by right-clicking the output XML field, and selecting Set as Filter. By default, all filters are set to “equal to”. To change the filter condition, right-click the field again, and select Set Filter Condition. Change the filter condition as required.

A Note About the Comment Field in Applications Platform

The comment field in an Applications Platform object is only available for CREATE and UPDATE operations. However, it should be noted that an UPDATE operation only appends new text to the field rather than overwriting.

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

The Missing/NULL processing panel allows you to define how missing elements in the XML are handled:

• Ignore NULL fields in the input — This is default behaviour. If a mapped element is missing from the InputData XML (Mapping tab), it is not sent to Applications Platform and the data there remains the same.
• Set NULL fields as empty strings in the destination — If a mapped element is missing from the InputData XML, the Applications Platform Connector still includes it in the XML passed to Applications Platform but with a blank value. This effectively updates the database column in Applications Platform to a NULL value for the record.

The References return mode panel allows you to define how reference fields and other related information are returned by the Applications Platform API:

• Only ID — For the returned records, include the IDs of the lookup field or pick-list item
• Only Name / Code — For the returned records, include the names of the lookup field item, or the code of the pick-list item
• Both — Return both the ID, and the name or code where available