Applications Platform Private Cloud Connector v1.4

Introduction to the Applications Platform Private Cloud Connector

What is the Applications Platform Private Cloud Connector?

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

The XML responses received back from Applications Platform Private Cloud can be saved to file, or passed to another BPA Platform instance 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 Private Cloud Connector to provide an indirect link from your Applications Platform Private Cloud tenant to other systems that BPA Platform is connected to, such as a CRM system.

Features

The following features are available:

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

White Paper - Applications Platform Private Cloud Connector 1.4

The Applications Platform Private Cloud Connector v1.4 Technical Overview introduces you to the tool. Installed as an add-on to BPA Platform, this tool provides direct communication between BPA Platform and your Applications Platform Private Cloud tenant.

Download White Paper

System Requirements

The Applications Platform Private Cloud Connector requires BPA Platform version 2020 or above.

It also requires Microsoft .NET Framework 4.6 or higher.

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

Architecture

This is a high-level system architectural overview of the Applications Platform Private Cloud Connector with BPA Platform and the Applications Platform Private Cloud tenant:

The Applications Platform Private Cloud Connector communicates with Applications Platform Private Cloud’s SOAP web service. It is through this that communication with the Applications Platform Private Cloud tenant is achieved. It must be installed on all BPA Platform client computers that run Applications Platform Private Cloud Connector tasks, as well as the BPA Platform server.

Technical Summary

The other tools that a Applications Platform Private Cloud 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 Private Cloud Connector can consume XML from the following tools:

Icon	Tool Name	Tool Category
	Import XML Document	Input
	Convert recordset to XML	Format
	Transform Data	Format
	Call Task	Execute
	Applications Platform Connector	Data Connectors
	Applications Platform Private Cloud Connector	Data Connectors

Objects Consumed

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

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

Exposing XML to Other Tools

The following tools can consume XML outputted by the Applications Platform Private Cloud Connector:

Icon	Tool Name	Tool Category
	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
	Applications Platform Private Cloud Connector	Data Connectors

Objects Exposed

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

• InputData This document contains the XML received by the Applications Platform Private Cloud 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 the Applications Platform Private Cloud tenant 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 made 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 Private Cloud 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 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 (Manage > 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 from the API
• Warnings and messages from the API

Applications Platform Private Cloud Accounts Security

The Applications Platform Private Cloud API is the only method used to connect to a tenant’s database and perform read / write tasks — all security present in the API is used.

Supported Objects

Due to the nature of Applications Platform Private Cloud, most objects are user-defined, and therefore differ from installation to installation. However, the following objects are exposed for all tenants:

• $SETTINGS — The available fields may vary depending on what the tenant administrators have added or edited
• COMMLOG
• USER — The available fields may vary depending on what the tenant administrators have added or edited

All available objects in your Applications Platform Private Cloud tenant installation are exposed in the incoming XML to the Applications Platform Private Cloud 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 Private Cloud from a specified directory location
• Get File — Allows a file to be downloaded from Applications Platform Private Cloud 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)
  NOTE: At the time of writing, external objects, even those registered to your Applications Platform Private Cloud installation, are not supported.

  Connecting to an Applications Platform Private Cloud Tenant

  The global configuration for this tool is used to create a connection to the Applications Platform Private Cloud tenant. You open this interface from the resources tree — expand System > Tools > Data Connectors and double-click Applications Platform Private Cloud Connector in the items list.

  

  When a connection is created, the available objects and fields of your Applications Platform Private Cloud tenant are retrieved.

  Click Add to create a connection to Applications Platform Private Cloud.

  Using Extended Logging

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

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

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

  

  Provide a unique Connection Name. If your Applications Platform Private Cloud 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 Private Cloud Connector to use when connecting to Applications Platform Private Cloud.

  TIP: The Applications Platform Private Cloud Connector uses a Applications Platform Private Cloud user to access the Applications Platform Private Cloud tenant. It is recommended you create user credentials (username and password) specifically for the Applications Platform Private Cloud Connector to use when connecting. If you have multiple tenants or applications that require connections to BPA Platform, ensure you create unique credentials for all connections.
  NOTE: If the Connector and a tenant user share the same credentials, one is logged out when the other attempts authentication.

  Global Variable to Store Session ID

  If you plan to run concurrent tasks which contain Applications Platform Private Cloud 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 Private Cloud 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 Private Cloud Connector caches the Applications Platform Private Cloud metadata for faster retrieval. From time-to-time, 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 Private Cloud schema in BPA Platform to be refreshed every time an update is made in Applications Platform Private Cloud itself, such as when an object or operation is added to, modified, or removed from the metadata.

  Should you also upgrade Applications Platform Private Cloud 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.

  NOTE: After enabling Update Objects and Operations, you must re-select the connection in all Applications Platform Private Cloud Connector task steps, then re-select the mapped operation.

  About the Server Tab

  

  Use Server Address to specify the Applications Platform Private Cloud tenant the username and password (Applications Platform Private Cloud Connector Connection tab) belong to. Note that each username and password combination is unique, and typically includes the tenant name as part of the username.

  As you type the server address, the Applications Platform Private Cloud Connector fills in the protocol prefix and router suffix options with default values:

  • Protocol — HTTPS
  • Router — /webapi/services/rpcrouter

  The server address URL should look like: https://myserver.address.com/webapi/services/rpcrouter.
  If required, you can change the protocol, router, and communication port number. Use the Advanced button.

  

  If HTTP communication is required, clear the selection for Use HTTPS.

  By default, HTTPS communication is over port 443, HTTP over port 80. To change this, enable Set Custom Port Number and enter the number in the box below.

  If your Applications Platform Private Cloud tenant uses a different router in its server URL, enable Set Custom Router and enter it in the box below.

  Test Connection

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

  TIP: If the test fails, ensure the machine hosting the Applications Platform Private Cloud Connector is fully updated with Windows updates, and TLS 1.2 has been enabled.

  About the Options Tab

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

  

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

  • Batch Enabled Operations — If required, you can force the Applications Platform Private Cloud 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.

  NOTE: Be aware that some objects can invoke other triggers on related objects. This may cause a run-time trigger limitation to be exceeded. For more information, contact your Applications Platform Private Cloud partner.
  TIP: Processing time for an Applications Platform Private Cloud Connector “batched” step impacts when succeeding steps in the task can start. It may be necessary to paginate your data source, for example, if extracting data from a database, limit each SELECT statement to 500 records say.

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

  • Send Empty Values to Server — By default, the Applications Platform Private Cloud 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 Private Cloud tenant. These must match.
  • User Collation — When fetching data from the Applications Platform Private Cloud database, you can choose to use case-sensitive queries. For such scenarios, the Applications Platform Private Cloud Connector uses the database collation specified here. If your installation of Applications Platform Private Cloud 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 Private Cloud is a blob data type, use this option to specify the string-type data type (20 characters maximum) Applications Platform Private Cloud Connector must use instead.

  Step Configuration

  When creating new tasks, the Applications Platform Private Cloud Connector tool is located under Data Connectors of the Task Browser.

  NOTE: It is not possible to add the Connector to the task until at least one connection to an Applications Platform Private Cloud tenant has been defined in the global configuration.

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

  • Click and drag the Applications Platform Private Cloud 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 Private Cloud 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 Applications Platform Private Cloud 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 Private Cloud Connector step, then select this as Task step (see below).

  

  Provide a meaningful Name and Description for this step.

  TIP: If this task instance makes use of two or more Applications Platform Private Cloud Connector steps, ensure the Name used is unique for each individual 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 Private Cloud 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 Private Cloud 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 Private Cloud 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 Private Cloud Connection this step must use.

  

  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 data source XML and that required by the Applications Platform Private Cloud tenant. 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 Private Cloud 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.

  TIP: If you have selected No data source in the General tab, you must add BPA Platform formulas and variables to the left-hand data source XML tree structure before mapping.

  Creating Mappings

  Create links by dragging and dropping a data source field (left) onto its corresponding Applications Platform Private Cloud 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 Applications Platform Private Cloud tenant. These can be mapped as required.

  The Applications Platform Private Cloud 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 Private Cloud’s Schema

  If new fields, objects, and operations have been added to your Applications Platform Private Cloud tenant after this task step was originally created, use Schema Refresh to make the latest API metadata 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”. Available filter conditions are:

  Filter	Description
  <>	Not equal to
  =	equal to
  <	Less than
  >	Greater than
  <=	Less than or equal to
  >=	More than or equal to
  LIKE	Filter results where the data source value contains the specified string and any wildcards.
  NOT LIKE	Filter results where the data source value excludes the specified string and any wildcards.

  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 Cloud 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. 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

  The comment field in an 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 Private Cloud 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 Private Cloud Connector still includes it in the XML passed to Applications Platform Private Cloud but with a blank value. This effectively updates the database column in Applications Platform Private Cloud 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 Private Cloud 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