Prerequisites

Before adding an Applications Platform ConnectorClosed The Applications Platform Connector allows communication between BPA Platform and Applications Platform. All communication uses XML. You use the Connector to map BPA Platform data to Applications Platform objects and operations. task step, ensure you have met the following:

Applications Platform Connector User Credentials

The Applications Platform Connector uses an Applications Platform user to access the Applications Platform tenant. It is recommended you create user credentials (username and password) specifically for the Applications Platform 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.

Connecting to an Applications Platform Tenant

Before you can use the Applications Platform Connector in a task step, you must create the connection to an Applications Platform tenant first.

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

Applications Platform Connector - Global Configuration

Click the image to view full size.

  1. If required, enable Use Extended Logging to expose the XML parsed between the Applications Platform Connector and Applications Platform. Note that this does generate a large amount of Event Log data.
  2. Click Add and enter the requested details required by your Applications Platform tenant.

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

    Applications Platform Connector Global Configuration - Connection Tab

    Supported Operations

    The Object drop-down shows the available tasks. The Operations drop-down shows the operations available for the selected Object:

    ►RunSync — Runs the called task when called by the original task; the original task waits for the called task to complete before continuing. Parameter-type variables can be used to pass data between the tasks; with RunSync operations, the original task cannot complete until the data is passed back.

    The data passed back is store in the output XML of the original task. This in turn can be consumed by another step capable of processing XML, such as the Convert XML to RecordsetClosed The Convert XML to Recordset tool is used to convert XML data into a flat-format BPA Platform recordset, allowing the data to be used by recordset-only consuming tools. This could then be used to power alerts via fax, email, or SMS, create reports, power a workflow, perform FTP transfer, and so on. tool.

    Use this operation if the original task requires data from the called task.

    ►Queued — Queues the second task but continues to run the original task to completion; both tasks run independently of each other. Data can be passed to a parameter-type variable in the called task. However, this operation does not allow data to be passed back as the original task has already completed running before the second task initialises.

    Use this option when only triggering a task to run, with or without data from the originating task.

    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.

    TIP: The Applications Platform Connector uses an Applications Platform user to access the Applications Platform tenant. It is recommended you create user credentials (username and password) specifically for the Applications Platform 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.

    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 variableClosed Variables are created and used extensively throughout and can either have fixed values or values that are dynamically populated when a task is run. Global variables are available for all tasks in this BPA Platform installation. Once created, global variables can be used by any task. 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.

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

    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.

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

    For more information, go to the main Connection tab topic.

  3. Go to the Server tab and select the Applications Platform environment to connect to.

    From the Server drop-down, select either:

    ►Applications Platform to connect to the Applications Platform tenant the username and password () 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.

    For more information, go to the main Server tab topic.

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

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

  5. Go to the Options tab and select the relevant API formats expected by your Applications Platform tenant. If your tenant does not make use of customised formats, this step can be skipped.

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

    Applications Platform Connector Global Configuration - Options Tab

    Click the image to view full size.

    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.

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

    TIP: Processing time for an Applications Platform 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 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 case-sensitive 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.

    You can change the view of the Options tab:

    ►Click in the toolbar to view the parameters grouped by categories.
    ►Click in the toolbar to view the parameters in descending alphabetical order.
  6. Click OK to save the new connection.

Where Should I Use an Applications Platform Connector Step?

The Applications Platform Connector step can either be used to start a task, that is, read data from Applications Platform for processing, or after a step that exposes XML such as the Import XML DocumentClosed The Import XML Document tool imports an XML document to be used and processed by other task steps. To validate the XML documents at runtime, you can either import an XML schema file (XSD), infer from an existing XML document, or manually construct the XSD. tool, that is, process data to and from Applications Platform.

You would then follow the step with a tool that can consume and use the XML document exposed by the Applications Platform Connector step, for example, the Run Microsoft Reporting ServicesClosed The Run Microsoft Reporting Services tool automates the running of Microsoft Reporting Services (MSRS) reports. tool.

EXAMPLE: The following example shows a process flow using a Applications Platform Connector step:

In this example, Applications Platform is being used as a web portal by the helpdesk team. When a ticket is closed, the Applications Platform Connector extracts the ticket details into an XML document. This is converted to a BPA Platform recordset by the Convert XML to Recordset tool. The Format as Flat FileClosed The Format as Flat File tool takes a BPA Platform recordset and converts it to a flat file to be used by another task step or external program. The flat file output can be delimited or fixed width. You can also choose whether the flat file contains data for single or multiple record types. tool converts the recordset into a file that can be emailed to the customer via the Send Email (SMTP)Closed The Send Email (SMTP) tool sends messages to any SMTP compliant mail server. This tool is capable of sending multiple messages in either text or HTML formats, incorporating data from Input and Format steps to any number of recipients. If recordset data being used from an Input step includes a column containing email addresses, then this can be used as a "dynamic" recipient address. tool. The CRM system is also updated with the ticket details via the Web Service Connector tool, which consumes the same file outputted by the Format as Flat File tool.

For more information about creating tasks, see How to Create a Basic Task.

For a detailed list of those tools the Applications Platform Connector tool can interact with, go to Working with Other Tools.

Adding a New Task Step

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

  1. Open the relevant task (if creating a new task, see How to Create a Basic Task).
  2. Either:
► Click and drag the Applications Platform Connector icon from the Task Browser to the task Design area.

–OR–

► From the task's Design tab, right-click on empty space and select New > Data Connectors > Applications Platform Connector.
  1. Use the General tab to choose 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 XMLClosed The Convert Recordset to XML tool converts one or more flat-structure BPA Platform recordsets into a hierarchical XML structure. It provides "translation services" between the standard BPA Platform tools, such as Database Query (ODBC), and advanced BPA Platform tools that accept XML as their input. or Transform DataClosed Transform Data is a Format tool that enables a new structure to be created from an existing XML or recordset data source. The output generated by this tool is ready for use in a destination system which consumes or requires XML. step in the task before the Applications Platform Connector step, then select this as Task step (see below).

    Applications Platform Connector - Step Configuration - General Tab

    Click the image to view full size.

    Provide a meaningful Name and Description for this step.

    TIP: If this task instance makes use of two or more Applications Platform Connector steps, ensure the Name used is unique for each individual step.

    Choose your Data source. This 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.

    For example, you can extract various bits of information from an email and store them in BPA Platform variables. The variables are then mapped to Applications Platformoperational 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 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 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.

    General Tab - Custom Schema Configuration

    Click the image to view full size.

    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, you must specify the BPA Platform variable that contains the XML data at runtime.

    For more information, go to the main General tab topic.

  2. Go to the Connection tab and select the relevant global connection for this task step. Although you can setup multiple global connections, each to a individual Applications Platform tenant, the Applications Platform Connector can only process data from a single tenant.

    Applications Platform Connector - Step Configuration - Connection Tab

    Click the image to view full size.

    All connections created in the 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 connections — this is case-sensitive.

    Note: Where variables or formulas are being used to create dynamic connections, you are prompted to select a template connection first to populate the Object and Operation drop-downs in the Mapping tab.

  3. Go to the Mapping tab and map the relevant input data source elements to the Applications Platform operation and elements.

    Applications Platform Connector - Step Configuration - Mapping Tab

    Click the image to view full size.

    The Object drop-down shows the available 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.

    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

    You 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 Task 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 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 Schema

    If new fields, objects, and operations have been added to your Applications Platform tenant after this task step was originally created, use Schema Refresh to make the latest API metadata available for use (first ensure Update Objects and Operations is selected in the relevant global connection).

    For more information, go to the main Mapping tab topic.

  4. Go to the Options tab and select the relevant error handling options for this task step.

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

    Applications Platform Connector Step Configuration - Options Tab

    Click the image to view full size.

    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 FileClosed The Save File tool saves output from another task step capable of producing document, as one or more files on the local drive, on-premise file server, external server, or cloud based server. step for investigation purposes, for example.

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

    ►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. Select either:

    ►Only ID — For the returned records, include the IDs of the lookup field or pick-list item. The ID elements are suffixed with _id.
    ►Only Name / Code — For the returned records, include the names of the lookup field item, or the code of the pick-list item. The XML element tabs are suffixed with _name or _code as appropriate.
    ►Both — Return both the ID, and the name or code where available.

    For more information, go to the main Options tab topic.

  5. Click  to save the task step.