What is the MailChimp Integration Tool v1.0.10
The MailChimp Integration tool allows communication between BPA Platform and MailChimp®. All communication uses XML. You use the data integration tool to map BPA Platform data to MailChimp objects and operations. Operations such as, ADD, UPDATE, GET, and DELETE, are supported for a variety of business objects, such as, List, Campaign, and Click report.
The XML responses received back from the MailChimp API can be saved to file or passed to another BPA Platform tool for further processing. The responses can include details of the object requested, any errors from the provider, or the values of any automatically generated ID fields. For example, you can use MailChimp integration to provide an indirect link between systems that do not typically synchronise data with each other, such as synchronising contacts from a CRM platform as MailChimp subscribers, or even to provide reports containing data from both systems.
The MailChimp Integration Tool Pack
The MailChimp integration tool pack consists of:
- MailChimp Integration – The MailChimp Integration tool must be installed on the BPA Platform server and on any BPA Platform client machines. It is this that provides the translation between BPA Platform data and MailChimp objects and operations.
White Paper - MailChimp Integration Tool v1.0.10
MailChimp Integration System Requirements
The MailChimp Integration tool requires BPA Platform (formerly “TaskCentre”) 4.6 build 1944 or above.
This tool is compatible with MailChimp Integration API version 3.0.
MailChimp Integration Architecture
The diagram below provides a high-level system architecture overview of the MailChimp Integration tool pack, with BPA Platform and the MailChimp integration API.
Figure 1 — High-level system architecture of the MailChimp Integration
About the MailChimp Integration Tool
Global Configuration
The global configuration for this tool is used to create connections to MailChimp.
Figure 2 — MailChimp Integration – Global Configuration dialog
Click Add to create a connection to MailChimp.
Use Extended Logging
Enabling this option exposes the XML parsed between MailChimp Integration and the MailChimp integration API. You can view the log from the BPA Platform Event Log (Manage > Event Log).
Without extended logging, the Event Log only contains start and end of transaction messages, plus any error messages encountered at runtime.
Connection Dialog
You configure the connection to MailChimp here.
Figure 3 — MailChimp Integration – Connection dialog
Configure a meaningful Connection Name for this connection; this is the name displayed when adding tasks for MailChimp.
Within Data Centre, specify the MailChimp data centre linked to your account. For example, if the last part of your MailChimp API key is us1, the corresponding data centre is us1.
Within API Key, specify the API Key created in MailChimp for your account.
Optionally, choose a Module to show only objects from that module on the mapping tab.
Test Connection
Using the Test Connection button allows you to test the connection to the MailChimp API.
Update Objects and Operations
Enabling the Update objects and operations option allows the MailChimp Integration schema within BPA Platform to be refreshed.
Step Configuration
When creating new tasks, the MailChimp Integration tool is located under Data Connectors of the Task Browser.
General Tab
Figure 4 — MailChimp Integration – General tab
Provide a meaningful Name and Description for this 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. These can then be mapped to operational fields.
For example, you can extract various bits of information from an email and store them in BPA Platform variables. Then, having mapped them to MailChimp objects and operations, these can be stored in MailChimp 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. These may be another MailChimp Integration step, or a tool, such as Convert Recordset to XML.
- Custom schema — An XML schema defines the structure of the parsed XML: what tags are present, and the nesting of the tags. You Define the schema of the XML that will be used as the input data source for this step. The industry standard XSD format is used by the MailChimp Integration tool. Any XML processed by this step must conform to this schema else an error will be reported.
If the XSD schema is available, either import it into the Custom Schema Configuration (use the Import XSD/XML File button) or copy and paste it into the configuration box. If the XSD schema is not available, you can import an example of the runtime XML (Import XSD/XML File) or copy and paste it into the configuration box. Use the Parse button to create the schema.- Input source variable — As well as defining the schema, you must specify the BPA Platform variable that contains the XML data at runtime.
Connection Tab
You specify the MailChimp Connection this step must use.
Figure 5 — MailChimp Integration – Connection tab
All connections created in GLOBAL CONFIGURATION are presented here.
Alternatively, you can use a BPA Platform variable to create a dynamic connection, where the connection used is determined by runtime circumstances. At runtime, the contents of the variable must match the name of one of the GLOBAL CONFIGURATION connections — this is case-sensitive.
Mapping Tab
Here you define links between the incoming XML and the outgoing data that is sent to the MailChimp API. This defines how, at runtime, the incoming XML is to be translated into the XML required for the relevant object and operation.
Figure 6 — MailChimp Integration – Mapping tab
The Object drop-down shows the available objects. The Operations drop-down shows the operations available for the selected Object. For more information about which operation is available for an object, see SUPPORTED OBJECTS.
You create the links by clicking and dragging a data source field (left-hand pane) onto its corresponding data input field (right-hand pane). Note that only linked fields are used in the output XML. BPA Platform formulas and variables can be included in the source data — drag them from the Task Browser to the object’s XML tree control. These can then be linked to operation fields. Note that 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.
The MailChimp Integration 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 nonstandard requirement.
Options Tab
The Options tab allows you to define how errors in this step are handled at task runtime.
Figure 7 — MailChimp Integration – Options tab
Download Whitepaper
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).
Allowing the task to continue allows you to use the error XML received back from MailChimp Integration in a Save File step for investigation purposes, for example.
All errors are recorded to the BPA Platform Event Log (Manage > Event Log).
Working with Other Tools
The MailChimp Integration tool can directly interact with the following BPA Platform tools.
Consuming XML from Other Tools
MailChimp Integration can consume the output from the following tools:
| Icon | Tool Name | Tool Category |
|---|---|---|
 | Import Flat File | Input |
 | Import XML Document | Input |
 | Convert Recordset to XML | Format |
 | Transform Data | Format |
 | Call Task Tool | Execute |
 | Magento Integration | Data Connectors |
Exposing XML to Other Tools
The following tools can consume and process the XML outputted by the Magento Integration tool:
| Icon | Tool Name | Tool Category |
|---|---|---|
| Import Flat File | Input |
| Import XML Document | Input |
| Convert Recordset to XML | Format |
| Transform Data | Format |
| Call Task Tool | Execute |
 | MailChimp Integration | Data Connectors |
Exposing XML to Other Tools
MailChimp Integration’s output can be consumed by the following tools:
| Icon | Tool Name | Tool Category |
|---|---|---|
 | Convert XML to Recordset | Format |
 | Run Microsoft Reporting Services | Format |
| Transform Data | Format |
 | Save File | Output |
| Call Task Tool | Execute |
 | Web Service Connector Tool | Data Connectors |
| MailChimp Integration | Data Connectors |
Download Whitepaper
The MailChimp Integration tool outputs two documents:
Figure 8 — MailChimp Integration tool outputs
OutputData- Data returned from MailChimp Integration, for instance the created, updated or retrieved entity instances
SupplementaryReference
ErrorData
TheErrorDatadocument is structured as follows:
<Error>— All errors are created as an<Error>node, with the following sub-nodes:
<Object>— The name of the requested object, such as,Campaign
<CODE<— The error code returned by MailChimp
<MESSAGE>— The corresponding error message
<EXTENDEDINFO>— A string containing additional information about the error
<INPUTDATA>— The input data mapped for the object, plus all data contained in theSupplementaryReferencefield
Both outputs can be used:
- Directly by subsequent tool steps which consume XML data inputs
- If required, use the Convert XML to Recordset tool to convert the XML to a BPA Platform recordset
- Accessed using the output or error objects for response data (
XmlString), or the output or error schema (XmlSchema) present in the Task Browser
Supported Objects
At the time of writing, the following objects and operations are supported:
| MailChimp Object | Standard Operations | Comment | ||||
|---|---|---|---|---|---|---|
| Get | Add | Update | Delete | Other | ||
Campaigns: Campaign folder | ||||||
Campaigns: Campaign folder | Additional operations:
| |||||
Campaigns: Content | ||||||
Lists: List | Additional operation:
| |||||
Lists: Abuse report | ||||||
Lists: Interest group | ||||||
Lists: Interest | ||||||
Lists: Member | ||||||
Lists: Member tag | ||||||
Lists: Merge field | ||||||
Lists: Segment | Additional operation:
| |||||
Reports: Abuse report | Additional operation:
| |||||
Reports: Campaign report | ||||||
Reports: Click report | ||||||
Reports: Click report detail | ||||||
Reports: Email activity report | ||||||
Reports: Sent to report | ||||||
Reports: Unsubscribe report | ||||||
Runtime
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 were linked are brought across. The XML is passed to the connector tool, which then:
- Processes the data
- Performs the operation requested
- Sends back an XML document containing the response
The XML can then be used by other BPA Platform steps
Error Handling
Errors are written to the BPA Platform Event Log (Manage > Event Log). You define how errors are handled in the Options tab of the MailChimp Integration tool.
Reasons for the errors could include:
- Web service connection errors
- User privilege errors
- Errors from the MailChimp integration API
- Warnings and messages from the MailChimp API
MailChimp Account Security
The MailChimp Integration API is the only method used to connect to MailChimp and perform read / write tasks — all security present in the API is used.
