Connector packages

This guide will explain what connector packages are and how a custom connector package can be created.

A connector package is a package installed in an Alumio environment which offers subscribers, publishers, transformers, etc. to fetch and receive data from external systems. This guide will explain how a connector package can be created.

Packages must transform data from and to the standard entities structure as defined by Alumio. For example, when transforming a product into a structure of an external system the product standard entity must be used by the transformer as starting point. When product data is being fetched from an external system a transformer must be created that transforms the data into the structure of the product standard entity.

It is recommended to use as much mechanics that are built in Alumio when creating a subscriber. For example, if a HTTP type subscriber is created, there is no need to create requests using cURL or other packages, Alumio can already supply a HTTP client to the subscriber.

Connector packages can create new functionality in the following parts of Alumio.

  • Subscribers
  • Publishers
  • Transformers
  • List transformers

Create a new package

Connector packages must be installed through Composer. To create a new connector package first a composer.json file needs to be created.  A typical composer.json file should look something like the following:


    "name": "acme/example-connector", 
    "description": "Example connector.", 
    "type": "library", 
    "license": "proprietary", 
    "prefer-stable": true, 
    "minimum-stability": "rc", 
    "require": { 
        "php": "^7.3", 
        "magement/subscriber-api": "^1.0@RC", 
        “magement/publisher-api": "^1.0@RC", 
        “magement/transformer-api”: “^1.0@RC” 
    }, 
    "require-dev": { 
        “mediact/testing-suite”: “@stable” 
    } 
    "autoload": { 
        "psr-4": { 
            "Acme\\ExampleConnector\\: "src" 
        } 
    } 

Note: Packages must comply with the coding standards of Alumio. This is enforced by installing the "mediact/testing-suite" composer package. It offers PHP linters to ensure the coding standard is correct.

Adding functionality

To register a new subscriber, publisher, or transformer, create a JSON file within the "magement" directory of the connector package. With this registration file a new prototype or configuration can be created.

The file below shows an example of a subscriber. The subscriber uses the existing "HTTP subscriber" and configures a request. 

{
"$schema": "https://di.schema.mediact.com/register.prototype.json",
"type": "subscriber",
"identifier": "example-subscriber",
"name": "Example Subscriber",
"description": "Example subscriber",
"object": {
"prototype": "http-subscriber",
"parameters": {
"request": {
"uri": "/rest/&{store}/V1/customers/search",
"method": "get",
"payload": "&{@}"
},
"client": "%{client}"
}
},
"schema": {
"properties": {
"client": {
"title": "HTTP Client",
"default": "default",
"ui": {
"di:type": "http-client"
}
},
"store": {
"type": "string",
"title": "Store",
"default": "all"
}
}
}
}

 

The JSON files use the JSON schema format. The "$schema" property defines which kind of feature is created:

  • https://di.schema.alumio.com/register.prototype.json
    • Register a new prototype.
  • https://di.schema.alumio.com/register.default.prototype.json
    • Register a new prototype where one prototype fits all objects
  • https://di.schema.alumio.com/register.configuration.json
    • Register a new configuration.

Secondly a type is defined. The type defines whether a subscriber, publisher or transformer is registered. The type can be one of the following:

  • subscriber
  • publisher
  • transformer
  • list-transformer

The object field configures the prototype. This can be an existing functionality like the http-subscriber, or a entirely new class can be created. 

An existing prototype, like the "HTTP subscriber", can be used. Or, if Alumio does not offer the required functionality a new class can be created. For information how to create a new class see the guide on how to create a subscriber, and the the guide on how to create a publisher.


A list of the available prototypes that can be used to within connector packages can be fetched by executing the following commands from the command line. 

vendor/bin/magement di:list:type subscriber
vendor/bin/magement di:list:type publisher
vendor/bin/magement di:list:type transformer
vendor/bin/magement di:list:type list-transformer

When creating a new class the following interfaces must be implemented:

Type Description
subscriber \Magement\Subscriber\SubscriberInterface
publisher \Magement\Publisher\PublisherInterface 
transformer \Mediact\DataContainer\Transformer\TransformerInterface 
list-transformer \Magement\Entity\Transformer\ListTransformerInterface 
 

The "schema" property defines a schema which is used to show a form within the dashboard of Alumio. Fields can be customized by adding a "ui" property.

The example below shows an example where users can provide an URL and HTTP client.

{
"schema": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"title": "Webshop URL",
"ui: {
"ui:placeholder": "Enter the URL of the webshop."
}
},
"client": {
"title": "HTTP client",
"ui": {
"di:type": "http-client"
}
}
}
}

The table below shows all available UI options.

Type Allowed values Description
ui:help string Shows a help text below the field.
ui:placeholder string Shows a HTML5 placeholder inside an input field.
ui:widget textarea, checkboxes Determines how the field is rendered. 
ui:field json, graphql, boolean, date-time Determines how the field is rendered.
ui:order array of strings Defines the order of the fields. 
ui:hidden boolean Whether the field is hidden or not.
di:allow configuration, prototype Restrict fields to only user configurations or prototypes.
di:type string Allow users to select a configuration of the matching type or create a new inline object. 

Tips and tricks

Connector packages should not contain configurations and environment variables. These should always be created from the application itself by the user. Instead, prototypes should be created. The one exception to this is entity types. When introducing a new entity type it must be registered as configuration.

Creating transformers

Create new transformers using the dashboard. Then export the configuration and convert the configuration into a prototype.