Shopify GraphQL Connector v1.0

The Shopify GraphQL Connector Introduction

What is the Shopify GraphQL Connector?

The Shopify GraphQL Connector provides an easy-to-use way of sending and retrieving data between BPA Platform and your Shopify store. This allows data to be synchronised between Shopify and third-party systems that it does not usually communicate with.

The Connector is used to map BPA Platform data to Shopify objects and operations, using the Shopify GraphQL Admin API. All standard Shopify administration objects are supported for Business-to-Consumer (B2C) and Business-to-Business (B2B) activity, as are custom metafields for both objects and fields.

All internal BPA Platform communication uses XML, although calls to, and responses from Shopify use the GraphQL format. Incoming recordset data can be mapped directly to XML elements in the Shopify GraphQL Connector without the need for external conversion. XML responses from the Connector can be saved and used by other BPA Platform tools for further processing, for example, as part of an end-to-end integration solution.

Features

• Connect directly to your Shopify store with an easy-to-use drag and drop user interface.
• Control which objects and operations are available at task design and runtime using our GraphQL Object designer to create queries or mutations.
• Create freehand queries for more complex or specific scenarios.
• Create relationships by combining supported parent-child items into a single GraphQL Object for use in a task step.
• Optionally hide fields not required within a GraphQL Object to reduce the presence of unnecessary fields during step design and in runtime data responses.
• Ability to save partial connections to allow users to either complete configuration at a separate time or to export a connection without its current authentication credentials.
• Export GraphQL Objects to other connections and deployments reducing design-time for commonly used business requirements.
• Set a password to lock one or more GraphQL Objects to prevent unauthorised editing.

Video Overview

White Paper - Shopify GraphQL Connector 1.0

The Shopify GraphQL Connector provides an easy-to-use way of sending and retrieving data between BPA Platform and your Shopify store.
This allows data to be synchronised between Shopify and third-party systems that it does not usually communicate with.

Download Now

The Shopify GraphQL Connector Tool Pack

The tool pack consists of:

• Shopify GraphQL Connector — The Shopify GraphQL Connector is a BPA Platform tool, used to communicate with the Shopify GraphQL Admin API. It must be installed on the server hosting BPA Platform, and on any BPA Platform client machines. It is this that provides the translation between the BPA Platform data and the Shopify objects and operations.

System Requirements

The Shopify GraphQL Connector tool pack requires BPA Platform 2021 or above.

This tool is compatible with the following version of Shopify’s GraphQL Admin API:

• GraphQL Admin API version 2023-07 to 2024-04 inclusive (Correct at the time of release. Newer versions may be available and supported.)

Architecture

The diagrams below provide high-level architectural deployment overviews of the Shopify GraphQL Connector.

Other deployment scenarios are supported. Contact your Codeless Platforms account manager for further details.

The Shopify GraphQL Connector uses the Shopify GraphQL Admin API to read and write data directly to yourShopify store.

Example On-Premise Architecture

This diagram provides an overview of the Shopify GraphQL Connector where BPA Platform is deployed onpremise.
The BPA Platform client can be deployed remotely (as shown), or on the same machine hosting the server.
If deployed remotely, the Connector tool must also be installed.

Example Cloud-Hosted Architecture

This diagram provides a high-level system architectural overview of the Shopify GraphQL Connector where BPA Platform deployment is cloud based.

This would suit a scenario where BPA Platform is partner-hosted and the customer does not require access to the BPA Platform client. All access to BPA Platform is managed on the hosting server machine.

Further variations of this deployment such as required remote client access, or use of the Connector as part of a partner-hosted multi-instance deployment are supported in BPA Platform 2023 and higher.

Working with Other Tools

The Shopify GraphQL Connector can interact directly with the following tools:

Consuming from Other Tools

The Shopify GraphQL Connector can consume output from the following tools:

Step Icon	Name	Step Type
	Call Stored Procedure (OLEDB)	Input, Data Connectors, Output, and Execute
	Database Query (ODBC)	Input and Data Connectors
	Import Flat File	Input
	Import XML Document	Input
	Retrieve Text Message	Input
	Convert Recordset to XML	Format
	Convert XML to Recordset	Format
	Transform Data	Format
	Call Task	Execute
	Applications Platform Connector	Data Connectors
	Web Service Connector	Data Connectors
	Shopify GraphQL Connector	Data Connectors

In addition, the Shopify GraphQL Connector can consume the output from other Data Connector tools that provide connectivity to an external application, such as an eCommerce, ERP or another CRM system.

Objects Consumed

The Shopify GraphQL Connector consumes the following objects exposed by other steps:

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

Exposing to Other Tools

The following tools can directly consume output from the Shopify GraphQL Connector:

Step Icon	Name	Step Type
	Retrieve Text Message	Input
	Convert XML to Recordset	Format
	Run Microsoft Reporting Services	Format
	Transform Data	Format
	Save File	Output
	Call Task	Execute
	Web Service Connector Tool	Data Connectors
	Shopify GraphQL Connector	Data Connectors

In addition, other Data Connector tools that provide connectivity to an external application, such as an eCommerce, ERP or another CRM system, can also consume the output from the Shopify GraphQL Connector.

Objects Exposed

The Shopify GraphQL Connector outputs the following objects which can be consumed by other tools:

• InputData — The InputData node is only available when another task step provides the consumed Data Source (see About the General Tab). When consuming a recordset, this node lists the recordset columns.
• OutputData — The OutputData object contains two sub-objects:
• XmlString — This is the XML document produced by the tool, containing data returned from Shopify. Also included are the key fields for the mapped elements affected by the used operation and a
  SupplementaryReference field for task auditing purposes. Any pass-through fields defined in the
  operation’s GraphQL Object are also present.
• 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 Shopify.
  <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 Shopify
  <MESSAGE ∕> — The corresponding error message
  <EXTENDEDINFO ∕> — A string containing additional information about the error
  <INPUTDATA ∕> — The header input data mapped for the object
  <∕Error>
  For more information about the errors received, see Error Handling.
• XmlSchema — This contains the error schema in XSD format.
• ResponseData — The ReponseData objects contains two sub-objects:
• XmlString — This contains the XML document containing the data received back from Shopify.
• XmlSchema — This contains the error schema in XSD format.
• — Standard step properties are also available enabling you to use statistical data of the Shopify GraphQL Connector step.

Where can the XML output be used?

The incoming data for any mapped fields in the Connector is translated into the correct XML format for the object and operation selected in the step configuration. The XML is passed to the Shopify GraphQL Admin API, 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-XMLconsuming 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 asFormat 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 Shopify GraphQL Connector.

Reasons for the errors could include:

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

Global Configuration

The global configuration for the Shopify GraphQL Connector is used to create the connection to the Shopify server.

You open this interface from the resources tree — expand System > Tools > Data Connectors and double-click Shopify GraphQL Connector.

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

Click Add to create a connection to Shopify.

The Shopify GraphQL Connector supports saving partially configured connections. This enables users to return to a previously incomplete connection to finalise details, or for previously configured connections to have certain details removed, for example, to log out from the current authenticated user account. Such connections are shown in the Global Configuration as Configuration Incomplete.

Using Extended Logging

Selecting this option exposes the full XML parsed between the Connector and Shopify.

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 General Node

You must name each Shopify GraphQL Connector connection you create.

Provide a unique Connection Name. If your Shopify GraphQL Connector makes use of a number of connections to different Shopify stores, then it is recommended that you add identifying details to the name. This is useful later when creating task steps.

About the Shopify Connection Node

The Shopify Connection node, selectable in the Connection Options tree, provides a summary of connection settings defined in the subsequent General and Cache nodes.

About the Shopify Connection – General Node

The Shopify Connection – General node is used to initiate the secure connection between BPA Platform and your Shopify store using the Shopify GraphQL Admin API.

In the Environment section, enter your Shopify Store Name, and in the the Authentication section, your Shopify account Access Token. Both values can be obtained from your Shopify store settings.

Use Test Connection to ensure that a successful connection can be made to the Shopify store.

The API Version list displays the currently supported Shopify GraphQL Admin API versions. Select the required API Version from the list and click Apply to use it in the current connection. This setting can be updated at any time, for example, to use a newer released API version from Shopify, however you must ensure that any schema differences which may exist between the differing versions are considered in your GraphQL Objects and any tool steps using them.

The read-only Schema URL for your connection is created based on the values provided above.

About the Shopify GraphQL Connector – Cache Node

The Cache node enables the dynamic caching of the store schema within the Connector, reducing the number of requests made to Shopify.

Click the Load Cache button to cache the Shopify store’s schema. Once loaded, this button is amended to Refresh Cache.

You must click the Refresh Cache button should any changes occur to the connected store’s structure to ensure the cache contains the latest schema data. Additionally, if this connection is changed to point to a different Shopify store, you are prompted to refresh the schema to cache the correct details for the new environment including any custom objects and fields.

About the Shopify Connection – Advanced Node

The Advanced node is used to manage pagination options within the Shopify GraphQL Connector.

Automatic Pagination

Some operations within the Shopify GraphQL Admin API will only return a specified number of records at any one time requiring multiple requests to be made in order to retrieve all expected data. These paging limits are described in the Shopify GraphQL Admin API documentation.

Automatic pagination is selected by default, enabling the Shopify GraphQL Connector to automatically return and combine all records for a request in a single output.

Manual Pagination

Selecting the Manual option allows pagination to be defined by the user during step design time and on a case-bycase basis.

Additional fields controlling the return of data are present in the operation schema and are processed by the API at
runtime. This can include, but is not limited to, the use of cursors to control the paging of data, checks for further
pages, and handling of the response when no further records are found.

The following fields are available for use when Manual pagination is enabled:

first
last
before
after
hasPreviousPage
hasNextPage
startCursor
endCursor

Refer to Shopify documentation for further details on GraphQL pagination.

Prefer ‘nodes’ over ‘edges’ for manual pagination

The Prefer ‘nodes’ over ‘edges’ for manual pagination setting, made available when the Manual option is selected, can be used to reduce the query cost of large queries. Pagination may be controlled without any of the edge properties; therefore if required, they can be safely excluded from the output schema.

An example of the returned data with nodes preferred over edges. The response data is contained within a ‘nodes’ array without the present of any edges, and represents a more streamlined structure.

If Prefer ‘nodes’ over ‘edges’ for manual pagination is not selected, the data returned is organised using edges
and nodes. The edges array contains multiple nodes, and is generally a more verbose structure.

An example of the returned data will look like this:

About the GraphQL Object Designer Tab

Use the GraphQL Object Designer to create GraphQL objects to interrogate and interact with your Shopify store.

A GraphQL Object can comprise:

• Query Object used to retrieve Shopify data.
• Mutation Object used to create, update, or delete objects in Shopify.
• Freehand Object where bespoke GraphQL script is used to create a single executable query operation against one or more objects in Shopify.

The Objects pane lists any objects created in this connection. This includes Query Objects, Mutation Objects and Freehand Objects. Selecting an object here displays its full structure in the Object Structure pane including any defined Input or Output Relationships or additional Pass-Through Properties.
Selection of any part of the structure will display a summary of its properties in the Details tab.

Example Query Object Details Tab

Input Arguments (Query and Mutation objects only)

The Input Arguments tab lists any available input fields and their properties for a selected item within an Object.
This may be for the Base Query Object or an Input Relationship, where defined. There are derived from the Shopify GraphQL Admin API.

A standard Query Object may contain multiple operations, for example, READ and SEARCH variations. Select from the Operation drop-list to display the field properties of each one. Input Arguments for operations in a standard Query Object are generally read-only.

Mutation Object Input Arguments contain an additional option to Update on Null. This can be applied to one or more fields enabling its value in your Shopify store to be overwritten if a Null value is passed to it at runtime. Leaving this option unselected for a field will result in existing values remaining unchanged if a Null value is present.

Output Fields (Query and Mutation objects only)

The Output Fields tab enables the selection of fields to be returned for a selected item within the Object Structure for a Query or Mutation Object. This may be for the Base Query Object or an Output Relationship, where defined. These are derived from the Shopify GraphQL Admin API.

Only values for fields selected in the Include Field column will be returned by the Connector at runtime. By default, any ID field types will always be selected.

The remaining columns display read-only properties relating to each field, including the field Type and whether it is Nullable.

Input and Output Schemas tab (Freehand Objects only)

The Input and Output Schemas tab displays the respective schema structures for a GraphQL Freehand Object.
These are a result of the structure generated during the creation of the Freehand Object. These tabs are read-only for this object type. To amend the Input or Output Schema for a GraphQL Freehand Object, you must edit and reexecute its script.

Sorting Listed GraphQL Objects

Objects listed in the Objects pane can be sorted in Ascending / Descending order based on the Object name and, if required, grouped by the Locked / Unlocked status of objects. Sort options are available for selection from the Objects sort drop-down.

Adding or Editing GraphQL Objects

To create a GraphQL Object, click the Add button in the Objects pane, or right click in the Objects pane and select Add from the pop-up menu.

Select the required object type from the options provided and click OK.

An existing GraphQL Object listed in the Objects pane can be amended by selecting the object and clicking the Edit button.

GraphQL Query Object

A GraphQL Query Object is used to retrieve data from your Shopify store.

Select a base object from the drop-down list and provide a unique name for your object. This will be used to identify the object on the Mapping tab when creating a task step – see About the Mapping Tab.

Note that the name you enter for the object is limited to 63 alphanumeric characters and can include hyphens (-), underscores (_), and full-stops (.).

From the Enabled Operations pane remove any operations which are not required. Base objects and their operations are exposed by the Shopify GraphQL Admin API.

Click OK to save.

The new Query Object is now displayed in the Objects pane. Selecting an item in the Objects pane will display its Object Structure.

Further configuration is possible by adding optional child Output Relationships (if supported for the selected Base Object) or Pass-Through Properties. See Defining GraphQL Objects.

GraphQL Mutation Object

A GraphQL Mutation Object is used to create, update, or delete objects in Shopify.

Select a base object from the drop-down list and provide a unique name for your mutation. This will be used to identify the object on the Mapping tab when creating a task step – see About the Mapping Tab. Each base object represents a single object and operation combination.

Note that the name you enter for the object is limited to 63 alphanumeric characters and can include hyphens (-), underscores (_), and full-stops (.).

Click OK to save.

The new mutation object is displayed in the Objects pane. Selection of an object in the Objects pane will display it’s Object Structure.

Further configuration is possible by adding optional child Input and Output Relationships (if supported for the selected Base Object) or Pass-Through Properties. See Defining GraphQL Objects.

GraphQL Freehand Object

A GraphQL Freehand Object can be Add-ed or Edit-ed to support bespoke GraphQL query results which may not be easily achieved using a standard Query Object. For example, a query may require more complex statements to facilitate a specific result.

The Freehand Object Designer allows custom or one-off queries to either be manually entered or copied from another source such as GraphiQL which can be used in conjunction with the Shopify GraphQL Admin API.

Such objects will appear in the Connector tool step assigned as an Execute operation type.

Enter a name for the Freehand Object. This will be used to identify the object on the Mapping tab when creating a task step – see About the Mapping Tab.

Note that the name you enter is limited to 63 alphanumeric characters and can include hyphens (-), underscores (_), and full-stops (.).

In the Freehand Query pane, enter the GraphQL script for the freehand query. This can be manually entered, or copied and pasted from an external source.

Where mapped values are required for a field at runtime, the Insert Parameter button will place a parameter marker into the GraphQL script at the current cursor position; alternatively you can manually enter parameters at the required point in the script using the following syntax $$param$$. Parameter names can additionally be amended, as required.

Click Execute Query or hit the F5 key to validate the entered script and run the query. If parameters are present in the query, sample or example values should be provided here to allow the query to successfully run.

The Persist Values option enables sample or example parameter values to be retained within the Freehand Object. These values are only used when the query is executed during the creation or amendment of the object and do not affect the query in a task step at runtime. If this setting is unchecked, then any entered values are not saved
for future use after the query is executed.

Click Reset Values to remove all previously entered values, if required.

Once executed, the Output Preview pane will display the results returned from Shopify. The Input Schema pane will present the parameter fields which will be present in the tool step’s Mapping tab for this Freehand Object. The Output Schema pane will show the schema structure which will be returned by the tool at runtime.

Click OK to save the new object and return to the GraphQL Object Designer.

Defining GraphQL Objects

An individual GraphQL Query Object and Mutation can be extended to include additional object rules which are then displayed in the Object Structure pane.

Rules are defined by selecting the Object in the Object Structure pane, clicking Add.

Select the required rule type and click OK.

Pass-Through Property

Pass-through properties work in the same manner as the Supplementary Reference field (see About the Mapping Tab), and are used to pass data required by the task or task designer into and out of the tool step without being passed to Shopify.

The name defined here is made available as an additional element in the input schema (Operation Data) for the tool step and will appear in its Output XML, therefore the property name you define is restricted to 63 alphanumeric characters and can include hyphens (-), underscores (_), and full-stops (.). In addition, the property name must conform to XML standards, such as, no spaces or punctuation marks, and not starting with a number. There is no limit on the number of pass-through properties you create for a business object.

Defining Input Relationship Rules (Mutation objects only)

Input relationships join a Child Object to its Parent Object to add additional levels in the structure of a Mutation.
For example, to present the initial fields to create a customer, and then to add addresses or marketing preferences
for those customers. Child objects are only available where defined in the Shopify GraphQL Admin API.

Right-click an object in the Object Structure and select Add, or use the Add button. If an Input Relationship exists, the corresponding option will be available for selection.

Select a child item from the Child Object drop-down.

Enter the Input Relationship name which is limited to 63 alphanumeric characters and can include hyphens (-), underscores (_), and full-stops (.).

Select OK to save. The Input Relationship will now appear in the Object Structure beneath its parent item.

If required, you can view or configure the fields available in the Input Relationship by navigating to the Input Arguments tab (see Input Arguments (Query and Mutation objects only)).

Defining Output Relationship Rules (Query and Mutation objects only)

An Output Relationship joins one or more related output objects to the Base Object to control the return of data from Shopify using the Connector at runtime. These objects are only available where defined in the Shopify GraphQL Admin API.

Right-click an object in the Object Structure and select Add, or use the Add button. If an Output Relationship exists, the corresponding option will be available for selection.

Select the child item from the Child Object drop-down.

Enter the Output Relationship name which is limited to 63 alphanumeric characters and can include hyphens (-), underscores (_), and full-stops (.).

Select OK to save. The Output Relationship will now appear in the Object Structure beneath its parent item.

The available fields that can be returned by the Connector can now be controlled within the Output Fields tab (see Output Fields (Query and Mutation objects only).

Some Shopify GraphQL Admin API objects support cursor-based pagination, which limits the amount of records which can be returned in a single Query Object response or page. Pagination allows all records to be returned as a series of pages and joined to form a single data output from the Connector. The Connector only supports pagination for these objects at the highest level at which they appear in a Query Object.

If a pagination-supported Child Object is added as an Output Relationship and its Parent Object also supports pagination, then we must limit the number of records it can return at runtime if its Parent Object also returns more than one record. It is not possible to return paged responses at multiple levels in a Query Object. The Child Record Limit is used to handle the amount of child records returned in this scenario. The default is set to 20 records however this can be amended to a maximum of 250 based on your Query Object‘s requirements. Further pagination handling for pagination can be configured in the connection’s Advanced tab (see About the Shopify Connection – Advanced Node).

Securing GraphQL Objects

Once created, GraphQL Objects can be password locked, preventing unintentional changes or deletion. When exported, locked GraphQL Objects are encrypted to prevent the structure from being viewed or altered.

Locking and Unlocking GraphQL Objects

With one or more objects selected in the GraphQL Objects pane, click the Lock button.

Enter a password, then re-enter the password to confirm it. If required, use the ‘eye’ display icon to show the plain text password value, and the ‘eye’ hide icon to return to its obfuscated state.

The selected GraphQL Objects will be locked and will display a locked status icon in the Objects pane.

To unlock one or more password-protected Objects, select those which require unlocking and click on the Unlock button, before entering the correct Password.

Importing and Exporting Defined GraphQL Objects

You can export the GraphQL Object configuration you have created as a backup or to use in another installation of the Shopify GraphQL Connector. The configuration is exported as an XML file. At the time of writing, you must export all objects found here; you cannot choose a selection of objects for export.

Similarly, you must import all objects found in the XML file, rather than choosing a selection. If any object already exists in the Shopify GraphQL Connector installation, you are prompted for which action to take (Replace, Do Nothing, or Create New (note that Create New appends (_1) to the object name after import).

Duplicating Objects

An existing Object can be duplicated to create an exact copy. This may be useful, for example, if distinct changes are required which may subtly alter the available options within an object or specific operation.

With the Objects to be duplicated selected, click the Duplicate button. The duplicate object or objects will retain the name of the original items with the addition of a numerical suffix (i.e. _1). Once created, these duplicated objects can be edited either to rename them or amend their configuration.

Step Configuration

When creating new tasks, the Shopify GraphQL Connector is located under the Data Connectors category of the Task Browser.

To add a new Shopify GraphQL Connector step to an existing task:

Open the relevant task (if creating a new task, see How to Create a Basic Task).

Either:

• Click and drag the Shopify GraphQL 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 Connector > Shopify GraphQL Connector.

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

About the General Tab

The General tab is used to Name, describe (Description), and enable and configure the optional Data source settings for the Shopify GraphQL Connector task step.

The Data source can either be:

• No data source — If you do not make use of a dedicated XML or recordset 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 then mapped to Shopify GraphQL Connector which are passed to the API at task runtime.
• Task step — The data source can be set to an available BPA Platform XML or recordset data source.
  Only those steps that are capable of natively exposing an XML document or recordset at runtime are listed. This may be another Shopify GraphQL Connector step, or a tool such as Transform Data, Retrieve Text Message, or Database Query (ODBC).
• 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
  Shopify GraphQL 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 using a recordset input data source, this option
  does not apply.

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. If using a recordset input data source, this option does not apply.

About the Connection Tab

Specify the Connection this step must use.

All connections created in the connector’s Global Configuration (see 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 a configured Connection (see Global Configuration) — this is case sensitive.

About the Recordset Tab

The Recordset tab is only present if a recordset source is used as the input to the tool step. Selection of the Enable Recordset Shaping option enables the creation of a nested XML schema structure from a flat recordset input for use in the tool’s Mapping tab and subsequently at runtime.

By default, the XML Structure pane will display the flattened structure from the input recordset (as displayed in the Recordset Columns pane). This can then be manipulated as required.

Adding a child element to the XML schema

One or more items in the Recordset Columns pane can be selected and added as child elements in the XML schema. Multiple levels of child objects are permitted.

With the required items selected in the Recordset Columns pane, select Add New Child Element option using the right-click menu.

Enter the new Child Element name, including the path if you are adding the new entry to an existing child element.

In the example below, the new element Cases will become a child element of the Contacts element.

Additional items can be added to child elements by using drag-and-drop to move them from the Recordset Columns pane to the XML Structure pane, or by right-clicking the selected Recordset Columns items and choosing Add from the resulting menu options.

Hiding recordset elements in the XML schema

Items can be set to a hidden status in the XML Structure and will no longer appear in the tool step for mapping. To do this, right click one or more items in the Recordset Columns pane and select the Hide in Header option from the pop-up menu. Hidden items no longer appear in XML Structure and are displayed greyed out in the Recordset Columns pane.

To reinstate the hidden recordset items in the XML schema, right-click on the hidden item in the Recordset Columns pane and select the Show in Header option from the pop-up menu.

Set Key elements in the XML schema

Individual items in the XML Structure can be flagged as Key fields requiring mapping by selecting the Set As Key option in the right-click menu. These are then denoted by the (Key) text shown appended to the field name in the XML Structure pane.

Removing items from the XML schema

Items in the XML structure can be removed from use in the tool’s Mapping tab and subsequently at runtime by right-clicking on the required items in the XML Structure pane and selecting the Remove option from the pop-up menu.

About the Mapping Tab

Here you define links between the incoming data (Input Data pane) and the outgoing data that is sent to Shopify (Operation Data pane). This defines how, at runtime, the incoming data is to be translated into the XML required for the relevant object and operation.

From here you can:

• Automatically map where input and output parameter names match
• Create mappings from a set of transform functions to change the data between input and output
• Use nested looping to support hierarchical data structures
• Import and export mappings so that they can be reused in other steps
• Filter the data returned for SEARCH operations

The Object drop-down shows the GraphQL Objects created in the Shopify GraphQL Connector. The Operations drop-down shows the operations available for the selected Object.

The left-hand Input Data pane shows those data source fields available for mapping. The right-hand Operation Data pane displays those fields for the selected Object and Operation combination.

Creating Mappings

Create links by dragging and dropping an Input Data field onto its corresponding Operation Data item. Run-time mandatory fields, as defined in the Shopify GraphQL Connector, are shown in bold — you can save a step with unmapped mandatory fields. 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 — create a Fixed / Dynamic function (refer to the product help) for the formula or function and link to the relevant input field.

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 SupplementaryReference field appears in addition to, and can be used in conjunction with, any Pass-Through Properties created for the selected GraphQL Object.

Resolving anyType Elements

Input fields marked with a have been declared as anyType format in the XSD. If your Operation Data requires you to declare an undefined data type, you can resolve this here. Click and select the relevant data type:

Using Functions

The Mapping tab makes use of the Data Transformation Layer (DTL) feature of BPA Platform, where you can use available functions to manipulate the data. Use the Functions pane to add transformation functions:

Functions

Aggregation — Aggregation functions define operations for specific nodes.

Node Count
This function counts the number of occurrences of a node in the source recordset or XML document. The result is then passed to the mapped Operation Data node.

Sum
This function calculates the total of the values from all iterations of an element in the source recordset or XML document. The sum of the values is used as the new value in the mapped Operation Data element.

Data — Data functions perform operations on source data to generate new data to be passed to the mapped Operation Data element.

Fixed / Dynamic
This function passes a static or dynamic value to the mapped Operation Data field. Use a variable or recordset column to generate the dynamic data.

Run VBScript
Use this function to perform VBScript operations to process source data, generate data to be submitted in the call at runtime, or both. The resulting value is passed to the mapped Operation Data field.

Lookup — Lookup functions are used to find values in a nominated source, by a key.

External Lookup
Use this function to lookup values from an external database. This uses existing
Database Query (ODBC) or Database Query (OLEDB) global connections.

Internal Lookup
Use this function to find an alternative value for source data from a predefined lookup table.

Looping — Looping functions loop through the source recordset or XML document to perform functions on all iterations of a node.

Interleaved Merge
This function loops through the source recordset or XML document and merges data
from specified elements into a single occurrence for the mapped Operation Data element.

Simple Loop
This function loops through the source recordset or XML document and creates an
Operation Data node for every iteration of a source node it finds.

Split by type
Use this function to take data from a single source node and split it into two or more Operation Data nodes dependent on a nominated identifier.

Additional Functionality

In the Transformation Mappings pane, click:

to import and use an existing mappings file (.DTLX) from a previous task

to export the current mappings for use in another task or as a backup (.DTLX)

to reset all current mappings

to delete the highlighted mapping

to delete the highlighted function

Refreshing the Tool Input Schema

Use Schema Refresh to reflect any changes made to the underlying fields and items of your mapped business object — Ensure that necessary refreshing of the cache (see About the Shopify GraphQL Connector – Cache Node or About the GraphQL Object Designer Tab has taken place in the relevant global connection.

Further Mapping Controls for an Element

You can further control how mapped data is processed for each mapped element, for example if expected data is missing. To do this, right-click the required element and select Options:

If the input source XML is missing this mapped element in its structure (mapped so therefore is required), use the options in the If mapping cannot be made due to missing data pane to control the behaviour of Shopify GraphQL Connector.

If the input source XML contains the mapped element but has no value, that is, received as either <element></element> or <element/>, use the options in the If mapping cannot be made due to empty data pane to control the behaviour of the Shopify GraphQL Connector‘s behaviour.

Both panes contain the same behavioural options:

• Create Empty Element — Send <element></element> to Shopify
• Create Element containing — If a missing element or data is received, always send the element with the value specified in the provided text box
• Don’t create Element — Do not include the element in the XML sent to Shopify
• Error — At task runtime, the Shopify GraphQL Connector step fails, an error is written to the BPA Platform Event Log

About the Options Tab

The Options tab allows you to define how errors and output behaviours 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).

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

You can also optionally alter the XML Output Behaviour on Null Values at runtime. By default the tool will include any fields (Include XML) in the response XML structure even if those fields contain Null or empty values for one or
more records in the dataset.

If fields with Null or empty field values are not required in the returned data, selection of Omit XML on Null or empty string will only return the XML data for fields where values are present.

If fields with only Null field values are not required in the returned data, selection of Omit XML on Null fields only will only return the XML data for fields where values are present, or the field is empty.

Supported Objects and Operations

Provision of supported objects and operations is handled by the GraphQL Object Designer. All items exposed by the Shopify GraphQL Admin API are available to the Connector. These can be retrieved from Shopify by loading or refreshing the cache in a connection’s global configuration. The GraphQL Object Designer then controls which objects and operations are available to the user during step design.

GraphQL Query Object Types

• READ — Retrieve objects for specific Shopify record(s).
• SEARCH — Search for records based on provided parameters.

GraphQL Mutation Objects

GraphQL mutations modify data using the Shopify GraphQL Admin API. These can take the form of standard activity types such as adding, updating or deleting records, but also specific actions such as revoke, calculate and activate. A Mutation Object is presented with an associated EXECUTE operation in the tool step.

GraphQL Freehand Objects

• EXECUTE— Runs the custom query script defined in the GraphQL Freehand Object against the defined records.

White Paper - Shopify GraphQL Connector 1.0

The Shopify GraphQL Connector provides an easy-to-use way of sending and retrieving data between BPA Platform and your Shopify store.
This allows data to be synchronised between Shopify and third-party systems that it does not usually communicate with.

Download White Paper