Table of contents
- Introduction
- The 3 Parts Of A Connector Package
- An In-depth Subscriber Example
- An Example Of Transformer
- An Example Of Publisher
- Wrapping Up!
Introduction
Connector package is a composer package that contains JSON files and optionally PHP classes. Like various other packages, a connector package also comes with several parts that better define its functionalities. This article takes a swipe at the various parts of the connector packages that an Alumio user can implement during integrations.
The 3 Parts Of A Connector Package
Connector packages are generally segregated into three parts:
Subscribers: They fetch data from a (external) source
Transformers: They transform data structures from the source to a generic data structure. Reversely, they are also capable of transforming data structures from a generic structure to the structure required by the endpoint.
Publishers: They send data to the endpoint
The JSON files contain “prototypes” which can be seen as templates to create PHP objects. The file below, for example, registers a Shopware order subscriber. It uses the default http-subscriber provided by Alumio and has a request pre-configured to fetch orders.
When Alumio doesn’t offer the functionality that is required, custom classes can be created by its users. For example, in order to fetch or send data or to create an authentication method, custom classes can be created.
An In-depth Subscriber Example
The experts from Alumio have curated an easy-to-understand subscriber model. Pay close attention to the notes!
{
"$schema": "https://di.schema.mediact.com/register.prototype.json",
"type": "subscriber",
Note 1: This defines the type of object you are creating. For a connector package, you will need at least two types:
- A subscriber to receive/fetch data from an (external) source and,
- A publisher to send data to an endpoint.
"identifier": "shopware-v3-order-subscriber",
"name": "Shopware V3 order subscriber",
"description": "Subscriber for Shopware order",
"object": {
"prototype": "http-subscriber",
Note 2: The prototype defines the type of subscriber. This can also be replaced with the “class” property if a custom implementation is required.
"parameters": {
Note 3: Parameters are used to configure the objects. A request is defined which contains a request body to filter the API results. Only those orders that have been updated since the last run are fetched.
"request": {
"uri": "/api/v3/search/order",
"method": "post",
"payload": {
"limit": "&{limit}",
"filter": [
{
"type": "multi",
"operator": "OR",
"queries": [
{
"type": "multi",
"queries": [
{
"type": "equals",
"field": "updatedAt",
"value": null
},
{
"type": "range",
"field": "createdAt",
"parameters": {
"gte":"&{mutation_date}"
Note 4: &{mutation_date} is a placeholder. Its value will be replaced with an actual value.
}
}
]
},
{
"type": "range",
"field": "updatedAt",
"parameters": {
"gte": "&{mutation_date}"
}
}
]
},
{
"type": "not",
"queries": [
{
"type": "equalsAny",
"field": "id",
"value": "&{identity_path}"
}
]
}
],
"sort": [
{
"field": "updatedAt",
"order": "ASC"
},
{
"field": "createdAt",
"order": "ASC"
}
]
}
},
"client": "%{client}",
Note 5: Alumio users can configure HTTP clients from the dashboard. The selected HTTP client will be used. See the schema property.
"transformer": {
Note 6: A couple of standard transformers are added. A connector package must transform incoming data into a generic entity defined by Alumio. Transformers can be easily created from the dashboard. The configurations can be exported and copied into this file.
"prototype": "chain",
"parameters": {
"transformers": [
{
"prototype": "list-mapper",
"parameters": {
"accessor": {
"prototype": "pattern",
"parameters": {
"pattern": "*"
}
},
"mappers": [
{
"prototype": "list-inherit-from",
"parameters": {
"array": {
"limit": "%{limit}",
"mutation_date": "%{start_date}",
"identity_path": ["00000000000000000000000000000000"]
}
}
}
]
}
},
{
"prototype": "identity-tracker-load",
"parameters": {
"tracker": "%{mutation_tracker}",
"datePath": "mutation_date",
"identityPath": "tracker_state_identities"
}
},
{
"prototype": "conditional",
"parameters": {
"filters": [
{
"prototype": "value-condition",
"parameters": {
"accessor": {
"prototype": "pattern",
"parameters": {
"pattern": "tracker_state_identities"
}
},
"conditions": [
{
"prototype": "not-empty"
}
]
}
}
],
"transformers": [
{
"prototype": "pattern-copy",
"parameters": {
"pattern": "tracker_state_identities",
"replacement": "identity_path"
}
}
]
}
},
{
"prototype": "list-mapper",
"parameters": {
"accessor": {
"prototype": "pattern",
"parameters": {
"pattern": "*"
}
},
"mappers": [
{
"prototype": "list-diff-keys",
"parameters": {
"array": {
"tracker_state_identities": true
}
}
}
]
}
}
]
}
}
}
},
"schema": {
Note 7: The schema node defines input fields in the dashboard. It can be used in the parameters/arguments node to dynamically add data. For example, a store code, http client, etc.
"properties": {
"client": {
"title": "Shopware HTTP Client",
"ui": {
"di:type": "http-client"
Note 8: With “di:type”, Alumio users can enter configurations like a previously made HTTP client. The HTTP client will need a base url, authentication plugins, etc. This can all be configured from the dashboard and will not be a part of the connector package.
}
},
"mutation_tracker": {
"type": "string",
"title": "Mutation Date Storage Path",
"default": "shopware-order-mutation-date",
"ui": {
"di:type": "storage"
Note 9: Here, users must enter a storage. In this example, it is used to store the mutation dates of orders so those dates can be used while fetching the orders.
}
},
"limit": {
"type": "integer",
"title": "Data Limit",
"default": 50
},
"start_date": {
"type": "string",
"title": "Start Date",
"format": "date-time"
}
}
}
}
An Example Of Transformer
The file below shows how to register a new transformer. It moves a field from product_code to product_id. Transformers can be created and tested in the dashboard. Subsequently, they can be exported. The exported JSON data structure can then be used to create a prototype.
{
"$schema": "https://di.schema.mediact.com/register.prototype.json",
"type": "list-transformer",
"identifier": "example",
"name": "Example",
"description": null,
"object": {
"prototype": "data",
"parameters": {
"transformers": [
{
"prototype": "pattern-copy",
"parameters": {
"pattern": "product_code",
"replacement": "product_id"
}
}
]
}
}
}An Example Of Publisher
The file below shows an example publisher. It will send order updates to a Shopware environment. The request is pre-configured and thus, the Alumio users do not have to know the API endpoints.
{
"$schema": "https://di.schema.mediact.com/register.prototype.json",
"type": "publisher",
"identifier": "shopware-v3-update-order-status-publisher",
"name": "Shopware V3 Order Status Update Publisher",
"object": {
"prototype": "http-publisher",
"parameters": {
"client": "%{client}",
"request": {
"uri": "/api/v3/order/&{id}",
"method": "patch"
}
}
},
"schema": {
"properties": {
"client": {
"title": "Shopware HTTP Client",
"magement": {
"type": "http-client"
}
}
}
}
}
Wrapping Up!
Alumio is leading the pack of iPaaS integration platforms and allows you to create connections to various systems such as an ERP, a CRM, or even a shipping partner, and much more. It enables the merchants or platform users to supervise these data streams. Thanks to the real-time integration, all channels receive precise and factual data on products, customers, logistics, and finance. The Alumio connector packages is a key component to driving these data flows and we hope that this guide has provided some useful insights into them. Stay tuned with us for more guides and articles!