Fundamentals

Architecture

The interface between JTL-Wawi and JTL-Connector consists of two layers. The first layer - provided by JTL-Software - is called Core.

The Core arbitrates between JTL-Wawi and your so-called endpoint logic. Your endpoint is the last piece of code and bridges between the Core and your target system.

To achieve this JTL-Connector makes use of the widely known MVC pattern. The Core provides the models and the view layer. Your opportunity is to provide the appropriate controller code to read data from or write data to your target system.

Request flow

Incoming JSON requests are decoded and validated inside the Core. It identifies the RPC parameters as well as the RPC method which has to be called.

Each RPC method will be mapped to a controller method which will be then invoked.

In the default implementation, the Core application is invoking a controller method with RPC parameters as arguments. The parameters are getting processed by the controller method and the result is returned to the application. In the last step the result will be converted into a RPC response and sent back to the client.

Note

The Core handles requests by default but it can be also handled by the endpoint implementation. You can check more about it here.

To review:

• Each call - executed by JTL-Wawi - raches the endpoint as RPC request.
• The Core decodes this request and determines the RPC parameters and RPC method.
• The Core or the endpoint maps the RPC method to its appropriate controller method and invokes it.
• The controller method performs the request and returns a result which in turn will be passed to the Core.
• The Core encodes this result as a valid RPC response and sends it back to JTL-Wawi.

Configuration

Two optional arguments can be passed when the connector Application is getting instantiated:

• $config - an object which implements the Noodlehaus\ConfigInterface interface
• $configSchema - an object which extends the Jtl\Connector\Core\Config\ConfigSchema class

Let’s focus on the class of the second argument, the Jtl\Connector\Core\Config\ConfigSchema. It is used to define which parameters must or may exist in the configuration. In short it validates the connector configuration. You can just use the default parameters required by the Core or add more parameters by your own. You can read more about this in the chapter configuration.

The used configuration class must implement the Noodlehaus\ConfigInterface interface. By default an instance of Jtl\Connector\Core\Config\FileConfig is used.

Core definitions

The Core contains special classes in the Jtl\Connector\Core\Definition namespace. Definitions are describing the connector environment in different parts. Here is a short description about them:

Name	Description
Action	Contains all available action names. Can be used to check if an action belongs to core or endpoint.
Controller	Contains all available controller names. Can be used to check if given name is real controller name.
ErrorCode	Application error codes.
Event	Can be used to generate event names (see events).
IdentityType	Contains identity types used by connector.
Model	Contains model names and their mapping to identities.
PaymentType	Contains payment types that are known by JTL-Wawi.
RelationType	Is responsible for defining relations between main identities and image identities.
RpcMethod	Helper class for defining RPC methods. Contains also method mappings (redirection) to other methods. E.g. the method connector.identify will be mapped to core.connector.identify.

Request in action

Suppose you want to handle the RPC method product.push. This method is responsible for inserting or updating product data into the online shop system.

We start with creating a Product controller class in the endpoint implementation.

// src/Controller/Product.php
namespace Acme\Connector\AcmeShop\Controller;

use Jtl\Connector\Core\Controller;
use Jtl\Connector\Core\Model\AbstractDataModel;

class Product implements PushInterface
{
    public function push(AbstractDataModel $model) : AbstractDataModel;
    {
        return $model;
    }
}

All controller objects that handle a push method must implement the Jtl\Connector\Core\Controller\PushInterface interface. In order to handle other RPC actions, the controller must implement:

• Jtl\Connector\Core\Controller\PushInterface for push
• Jtl\Connector\Core\Controller\PullInterface for pull
• Jtl\Connector\Core\Controller\DeleteInterface for delete
• Jtl\Connector\Core\Controller\StatisticsInterface for statistics

There is one more interface which helps to handle requests inside a transaction, the Jtl\Connector\Core\Controller\TransactionalInterface interface. Methods from this interface will be called only on push and delete RPC calls.

The second example shows the implementation of the TransactionalInterface in a controller which also implements a delete action.

namespace Acme\Connector\AcmeShop\Controller;

use Jtl\Connector\Core\Controller;
use Jtl\Connector\Core\Model\AbstractDataModel;

class Product implements DeleteInterface, TransactionalInterface
{
    public function delete(AbstractDataModel $model) : AbstractDataModel;
    {
        return $model;
    }

    public function beginTransaction(): bool
    {
        // called before 'delete' method
    }

    public function commit(): bool
    {
        // called after 'delete' method
    }

    public function rollback(): bool;
    {
        // called when exception was thrown in 'delete' method
    }
}