Amazon Connector v1.0

About the Amazon Connector

The Amazon Connector provides a straightforward way of enabling connectivity between your Amazon marketplace and other systems that BPA Platform can connect to that you use to maintain inventory or process orders.

The Amazon Connector takes away the need for script and provides an easy to use user interface for writing and retrieving data to/from Amazon Seller Central.

Fulfilled by Amazon (FBA) orders are supported natively in the Connector; Fulfilled by Merchant (FBM) is supported if the corresponding Private SP-API Developer account has Direct to Consumer Shipping permissions granted by Amazon.

The Amazon Connector takes away the need for script and provides an easy to use user interface for writing and retrieving data to and from your Amazon store using its Selling Partner API (SP-API). This means that the data is validated using the business rules defined by Amazon so the data cannot be accidentally corrupted through lack of knowledge of these rules.

Features

• Connects to the Amazon Selling Partner API (SP-API) to communicate with your Amazon store
• Allows for synchronisation solutions between your Amazon store and a third-party system:
  • Download and retrieve information on sales orders
  • Download and retrieve information on products
  • Upload inventory changes, i.e. stock levels and prices
  • Upload order status changes
  • Obtain reports on marketplace activity
• Drag & drop facility for mapping BPA Platform data to your Amazon store
• Visual links to easily identify the mappings between the incoming data of the XML source and the outgoing data to be sent to Amazon
• 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.

System Requirements

The following prerequisite software must be in place before installing the Amazon Connector.

Minimum BPA Platform Version

The Amazon Connector requires BPA Platform 2021 or above.

Personally Identifiable Information (PII)

If your marketplace activity needs Personally Identifiable Information (PII) to be retrieved, for example for order fulfilment or report requirements, then the ability to access such data is governed by Amazon’s policies. In such scenarios, a Private SP-API Developer account must be obtained by the customer, with Direct to Consumer Shipping permission granted by Amazon. Without this permission grant, it is not possible to retrieve PII.

Architecture

The diagrams below provide high-level architectural overviews of the Amazon Connector with BPA Platform and the Amazon marketplace in a number of commonly used deployments. Other variations are supported. For further information, contact your Codeless Platforms account manager.

Example On-Premise Architecture

The diagram below provides a high-level system architectural overview of an Amazon Connector implementation where BPA Platform is deployed on-premise. The BPA Platform client can be deployed remotely (as shown), or on the same machine hosting the server. If deployed remotely, the Connector must also be installed.

Example Cloud-Hosted Architecture

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

This would suit an iPaaS (Integration Platform as a Service) deployment 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. Other cloud-hosted connector tools could be added to this scenario to create a fully hosted integration solution.

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 2024 and higher.

Working with Other Tools

The Amazon Connector can directly interact with the following BPA Platform tools:

Consuming from Other Tools

Below is a list of other steps that an Amazon Connector step can directly interact with to consume information from.

This list is by no means exhaustive but instead includes the most common steps the tool can interact with:

Icon	Tool Name	Tool Category
	Call Stored Procedure (OLEDB)	Input, Data Connectors, Output, and Execute
	Database Query (ODBC)	Input and Data Connectors
	Database Query (OLEDB)	Input and Data Connectors
	Import Flat File	Input
	Import XML Document	Input
	Convert Recordset to XML	Format
	Convert XML to Recordset	Format
	Transform Data	Format
	Call Task	Execute
	Applications Platform Connector	Data Connectors
	Amazon Connector	Data Connectors

Objects Consumed

The Amazon 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)

Icon	Tool Name	Tool Category
	Retrieve Text Message	Input
	Convert XML to Recordset	Format
	Run Microsoft Reporting Services	Format
	Transform Data	Format
	Call Task	Execute
	Applications Platform Connector	Data Connectors
	Amazon Connector	Data Connectors

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

Objects Exposed

The Amazon 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; for XML, it contains the XML document received by the Amazon Connector.
• OutputData — The OutputData object contains two sub-objects:

• • XmlString — This is the XML document produced by the tool, containing data returned from Amazon. Also included are the key fields for the mapped elements affected by the used operation and a SupplementaryReference field for task auditing purposes.
  • 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 Amazon<Error> — The ErrorData object also contains two sub-objects:
    Error — All errors are created as an node, with the following sub-nodes:
    <Object /> — The name of the requested object
    <CODE /> — The error code returned by Amazon Connector
    <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>
    For more information about the errors received, see Error Handling.
  • 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 Amazon 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 (see Options Tab).

Reasons for the errors could include:

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

Global Configuration

The global configuration for the Amazon Connector is used to create a connection to a seller’s Amazon marketplace in a specific country. This enables data to be either read from or written to your marketplace store in that country.

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

The dialog box displays the Connections list of the global configuration and is where the Amazon Connector connections are created and managed. If you have multiple marketplace stores, or stores in multiple countries, then connections must be created for each store.

Click Add to create a connection to Amazon.

The Amazon 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 the Selling Partner API.

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

In line with Amazon’s data retention policies, Extended Logging will not occur where a connection in use at runtime is configured to use the Restricted Data Access Mode (see About the Amazon Connection > General Node). This is to prevent Personally Identifiable Information (PII) being stored in the Event Log database table.

About the General Node

You must name each Amazon Connector connection you create.

Provide a unique Connection Name. If you have multiple Amazon stores, or operate in multiple countries then a separate connection is required for each one. It is recommended that you add identifying details to the name. This is useful later when creating task steps.

Enabling Update Objects and Operations allows the Amazon Connector schema in BPA Platform to be refreshed when an update is made to the objects and operations (for example, a new API version is made available by Amazon).

About the Amazon Connection Node

The Amazon Connection node, selectable in the Connection Options tree, provides a brief summary, and the current status of configured connections. Prior to connection authentication (see the Amazon Connection > General Node) the default values for each field will appear as Unknown.

About the Amazon Connection > General Node

Use the General node to determine the Amazon marketplace account to be used for this connection.

Select the location of the Amazon marketplace from the Country drop-down list.

• If connecting to an Amazon marketplace that uses Fulfilled by Amazon (FBA), or where there is no requirement to access Personally Identifiable Information (PII), select Authorise.This will open the Amazon Seller Central Authorisation Console. Enter the credentials for the account to be used in your Amazon Connector connection. This connection uses OAuth 2.0 which is an open protocol authorising secure data sharing between applications using the exchange of tokens.
• If connecting to an Amazon marketplace that uses Fulfilled by Merchant (FBM), or where you need access to Personally Identifiable Information (PII), select the Enable Restricted Data Access Mode check box.This mode will require a Private SP-API developer account with Amazon-granted permission for the Direct-to-Consumer Shipping role. Other restricted roles are available and may also be granted by Amazon as part of a customer’s application for the account. These may be applicable to access some report types, for example, Tax and Invoicing.

  Enter the AWS IAM User Access Key, AWS IAM User Secret Access Key and AWS IAM Role ARN for the application retrieved from the IAM Console in the AWS Management Console.

  Enter the App ID, Client Identifier, Client Secret and Refresh Token for the marketplace to be used in this connection. These can be found in the Developer Central area of Seller Central under Apps and Services > Develop Apps.

  Amazon require the Client Secret credential to be rotated at least every 180 days. This rotation process must be applied in any connections where the Restricted Data Access Mode is used to ensure continued runtime activity. Refer to https://developer-docs.amazon.com/sp-api/docs/rotating-your-apps-lwa-credentials for further details on this policy and how to obtain a new Client Secret. Note that you have seven days after generation of a new Client Secret to replace the previous value present in an Amazon Connector connection.

  Once populated, select Authorise to create the Restricted Data Access mode connection to Amazon.

When initial authentication has been established using either option, the Test Connection button can be used to confirm the connection to Amazon.

The Log Out button can optionally be used to disconnect an established connection. The user must repeat the authentication process to re-establish the connection.

Amazon Connection > Advanced Node

The Advanced node enables optional changes to some configuration settings relating to Amazon’s SP-API rate limits and the handling of pagination within the Amazon Connector.

Setting the Requested Retry Limit

Amazon’s SP-API rate limits determine how many calls can be attempted to individual operations within an API during any given time period. Where an HTTP 429 response status code is returned from Amazon, this indicates that too many requests have been made during that time. In such instances, the Amazon Connector will re-attempt up to 3 retries as a default. If further retry attempts are deemed necessary, this value can be amended using the Number of Retries option. The maximum number of retries available is 10.

The Retry Wait Time drop-down is used to set the time interval (in seconds) between retry attempts (if the Number of Retries is more than 0). By default, the interval between retries is 3 seconds with the option to increase this to a maximum of 30 seconds.

Pagination Selection

Enable Pagination is selected by default, enabling the Amazon Connector to automatically return and combine all records for a request in a single output. Some operations within the Amazon SP-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 Amazon SP-API documentation.

Users can deselect this setting, however if an operation uses pagination in its responses, it will require use of the nextToken field in the Amazon Connector step at runtime to manage the successful return of all records. Additional handling in the task would also be required to stop subsequent calls to the Amazon SP-API when no further records can be retrieved.

Step Configuration

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

To add a new Amazon 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 Amazon 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 >Amazon Connector.

About the General Tab

Use the General tab to choose the BPA Platform data source to be mapped to the Amazon Connector. You can map data source objects from either an XML or recordset source.

On the General tab, provide a meaningful Name and Description (Optional) for this step.

Choose your Data source. This 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 fields and passed to Amazon Connector objects at task runtime operational objects and fields 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 Amazon 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 Amazon Connector 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, you must 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

You must specify the Amazon Connector connection this task must use.

All fully configured connections created in the are presented here. Select the relevant connection from the Connection drop-down.

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.

About the Recordset Tab

The Recordset tab is only present if a recordset source is used as the input to the Connector 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 the 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.

Click OK.

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 against the field name in the XML Structure pane.

To reset an item assigned as a key in the XML Structure, right-click on the required key items in the XML Structure pane and select the Set As Key option from the pop-up menu.

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

The Mapping tab of the Amazon Connector allows you to define the mappings between the input data source (see the General Tab) and that required by the selected Amazon object and operation.

The aim of this tab is to define the links between the incoming data and the outgoing data that is to be sent to Amazon.

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

The Object drop-down presents a list of functions available for selection within the Amazon Connector. The Operations drop-down presents the operations available for the selected Object.

The left-hand Input Data pane holds those data source fields available for mapping (see the General Tab). The right-hand Operation Data pane displays those fields for the selected Object and Operation combination.

Creating Mappings

Create links by dragging and dropping a Input Data field onto its corresponding Operation Data field. Mandatory Operation Data fields are shown in bold.

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 for the formula or variable and link to the relevant Operation Data 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.

Resolving anyType Elements

Fields marked with a blue down-facing arrow have been declared as anyType format in the XSD. If your Operation Data requires declared matching data types, you can resolve this here. Click blue down-facing arrow 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. Note that the selected Object and Operation for the tool step, as well as the Input Data and Operation Data schemas must be identical to that used in the .dtlx file for an import to be successful.

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 Object Schema

Use Schema Refresh to reflect any changes made to the object and operation schema following any change made to the structure of your mapped objects — Ensure that Update objects and operations option has been selected on the General Node in the Global Configuration (see the General Node).

Further Mapping Controls for an Element

You can further control how incoming 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 (mapped so therefore is required), use the options in the If mapping cannot be made due to missing data pane to control the Amazon Connector‘s behaviour.

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

Both panes contain the same behavioural options:

• Create Empty Element — Send to Amazon
• 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 Amazon
• Error — At task runtime, the Amazon Connector step fails and an error is written to the BPA Platform Event Log

Supported Objects

The objects and operations currently supported are displayed in the tables below. Bold fields indicate mandatory field entry.

Object: Catalog items

Object: Feed (Native)

cancelFeedCancels the feed that you specify. Only feeds with processingStatus=IN_QUEUE can be cancelled. Cancelled feeds are returned in subsequent calls to the getFeed and getFeeds operations.feedIdgetFeedReturns feed details (including the resultDocumentId, if available) for the feed that you specify.feedIdcreateFeedDocumentCreates a feed document for the feed type that you specify. This operation returns a presigned URL for uploading the feed document contents. It also returns a feedDocumentId value that you can pass in with a subsequent call to the createFeed operation.body
contentTypegetFeedDocumentReturns the information required for retrieving a feed document’s contents.feedDocumentId

Object: Feed

Object: Order

Fulfilled by Amazon

The FulfillmentChannels - item field can be set to filter returned results based on whether they were fulfilled by Amazon or the seller:

Setting the parameter to:

• AFN will return results fulfilled by Amazon.
• MFN will return results fulfilled by the seller.
• Leaving the parameter blank will enable the default setting and will return results for both fulfillment channels.

Object: Report

Object: Report (Native)

About the Options Tab

The Options tab allows you to set how errors in the step are handled at task runtime:

For example, if an error occurs you can decide if you want the task to continue with processing the next step along or abort and terminate the task completely.

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.

You can also optionally alter the XML Output Behaviour on Null Values at runtime. By default the tool will include any fields in the response XML structure even if those fields contain Null values for one or more records in the dataset. If fields with Null values are not required in the returned data, selection of Omit XML will only return the XML data for fields where values are present.

Click OK to complete the step configuration.