Table of contents

• Introduction

• Create A New Package
  • Adding Functionality
• The Table Of UI Options
• Tips To Use Connector Packages
• Closing Thoughts

Introduction

Alumio is the numero uno solution for businesses who search for a quick, stable and steadfast connection between ERP systems and the software they deploy. A connector package can be defined as a package installed in the Alumio environment which offers subscribers, publishers, transformers, etc, to fetch and receive data from external systems. It plays a major role in integrations and helps the Alumio users to establish critical connections even without much know-how. This article intends to provide a detailed explanation on what connector packages are and how a custom connector package can be created.

Packages must transform data to and from the standard entity structure as defined by Alumio. For example, when transforming a product into a structure of an external system, the product standard entity has to be utilized by the transformer as a starting point. 

On the other hand, when product data is being fetched from an external system, a transformer is required to transform the data into the structure of the product standard entity.

Alumio experts recommend using the various mechanics that are pre-built in Alumio while creating a subscriber. 

For instance, 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 functionalities 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, you have to create a composer.json file in the first place.  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 that 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. Here are some examples

• https://di.schema.alumio.com/register.prototype.json

  • Registers a new prototype.

• https://di.schema.alumio.com/register.default.prototype.json

  • Registers a new prototype where one prototype fits all objects.

• https://di.schema.alumio.com/register.configuration.json

  • Registers a new configuration.

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

1. Subscriber,

2. Publisher

3. Transformer, and

4. List-transformer

The object field configures the prototype. This can be an existing functionality like the http-subscriber, or an 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 on how to create a new class see the guide on how to create a subscriber, and the guide on how to create a publisher.

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

1. vendor/bin/magement di:list:type subscriber

2. vendor/bin/magement di:list:type publisher

3. vendor/bin/magement di:list:type transformer

4. vendor/bin/magement di:list:type list-transformer

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

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 Of UI Options

The table below shows all available UI options.

Tips To Use Connector Packages

Here are some tips for you:

1. The 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. 

2. Regardless, there is one exception to this, which is entity type. When introducing a new entity type it must be registered as a configuration.

Closing Thoughts

Alumio makes it super easy for everyone to create new connector packages and transformers using its dashboard. Once you have configured them, you can simply export the configuration and even convert the configuration into a prototype. We hope that the article guides you the right way while you work with the Alumio environment and our experts try to make the platform better everyday. Don't forget to check out our other articles and stay tuned with us for the new ones!