Aigonix Studio

• 1: Overview
• 2: Application
• 3: Environment
• 4: Microservice
• 5: Integrations
• 6: Container Registry

1 - Overview

Aigonix Studio is the web-based interface for managing your Applications and Microservices in the Aigonix Platform. It is the main interface for interacting with the platform and is where you will spend most of your time when interacting with the platform.

In Studio you can create and manage Applications, Environments, Microservices and other products and services.

Getting started

To access Studio you need to be a customer of Aigonix. If you are not a customer, you can contact us to learn more and hopefully become one.

Once you have access to Studio, you can log in using your credentials at dolittle.studio. You can now create your first Application and start deploying your Microservices into that application.

Components

When you run your Microservices in the Aigonix Platform you will have access to a number of components that will help you manage your services.

You will define each Application with its Environments, and add Microservices to them. You define which Docker image to use for each Microservice, and whether or not you want to use the Dolittle Runtime. You can use a publicly available image, or store your container image in the provided container-registry.

If you use the Dolittle Runtime one will be made available to your Head and through it you will have access to Tenanted resources like the Event Store and Read Cache. If you do not use the Dolittle Runtime the service will run the assigned Docker-image without permanent storage (stateless).

You can make your services available to the internet if you so wish. If you do not they will only be available within the platform.

flowchart TB
    subgraph Legend
        S[Docker Container]
        R>Dolittle Runtime]
        D[(Database)]
        F[\Studio function/]
    end
    subgraph Customer
        subgraph app1[Application with 3 Environments]
            subgraph app1dev[Development Environment]
                subgraph App1DevMS1[Microservice with Runtime]
                    App1DevMS1head[Head] --SDK--> App1DevMS1runtime>Runtime]

                    App1DevMS1runtime --uses--> App1DevMS1EventStore[(Event Store)]
                    App1DevMS1runtime --makes available--> App1DevMS1ReadCache[(Read Cache)]
                end
                subgraph App1DevMS2[Microservice]
                    App1DevMS2Head[Head]

                end
                App1DevMS1EventStore --in--> app1devDB[(Dev Database)]
                App1DevMS1ReadCache --in--> app1devDB
                Logs1dev[\Log viewer/] -.gathers logs.-> App1DevMS1head
                Logs1dev -.gathers logs.-> App1DevMS2Head
            end
            subgraph app1test[Test Environment]
                subgraph App1TestMS1[Microservice with Runtime]
                    App1TestMS1Head[Head] --uses--> App1TestMS1Runtime>Runtime]

                    App1TestMS1Runtime --uses--> App1TestMS1EventStore[(Event Store)]
                    App1TestMS1Runtime --makes available--> App1TestMS1ReadCache[(Read Cache)]
                end
                subgraph App1TestMS2[Microservice]
                    App1TestMS2Head[Head]
                end
                App1TestMS1EventStore --in--> app1testDB[(Test Database)]
                App1TestMS1ReadCache --in--> app1testDB

                Logs1test[\Log viewer/] -.gathers logs.-> App1TestMS1Head
                Logs1test -.gathers logs.-> App1TestMS2Head
            end
            subgraph app1prod[Production Environment]
                subgraph App1ProdMS1[Microservice with Runtime]
                    App1ProdMS1Head[Head] --uses-->  App1ProdMS1Runtime>Runtime]

                    App1ProdMS1Runtime --uses--> App1ProdMS1EventStore[(Event Store)]
                    App1ProdMS1Runtime --makes available--> App1ProdMS1ReadCache[(Read Cache)]
                end
                subgraph App1ProdMS2[Microservice]
                    App1ProdMS2Head[Head]
                end

                App1ProdMS1EventStore --in--> app1prodDB[(Prod Database)]
                App1ProdMS1ReadCache --in--> app1prodDB

                Logs1prod[\Log viewer/] -.gathers logs.-> App1ProdMS1Head
                Logs1prod[\Log viewer/]  -.gathers logs.-> App1ProdMS2Head
            end
            Docs1[\Documentation/]


            app1devDB -.regular backups.-> Backups1[\Backups/]
            app1testDB -.regular backups.-> Backups1
            app1prodDB -.regular backups.-> Backups1
        end
        subgraph app2[Application with 1 Environment]
            subgraph app2prod[Production Environment]
                subgraph App2ProdMS1[Microservice with Runtime]
                    App2ProdMS1Head[Head] --uses--> App2ProdMS1Runtime>Runtime]

                    App2ProdMS1Runtime --uses--> App2ProdMS1EventStore[(Event Store)]
                    App2ProdMS1Runtime --makes available--> App2ProdMS1ReadCache[(Read Cache)]
                end
                subgraph App2ProdMS2[Microservice]
                    App2ProdMS2Head[Head]
                end
                App2ProdMS1EventStore --in--> app2prodDB[(Prod Database)]
                App2ProdMS1ReadCache --in--> app2prodDB

                Logs2prod[\Log viewer/] -.gathers logs.-> App2ProdMS1Head
                Logs2prod -.gathers logs.-> App2ProdMS2Head
            end

            Docs2[\Documentation/]

            app2prodDB -.regular backups.-> Backups2[\Backups/]
        end
        ACR[\Container Registry/]
    end

2 - Application

An Application is a logical grouping of Microservices. It is the top-level container for your Microservices and is used to group them together. An Application can have multiple Environments, which are used to separate your Microservices into different stages of your development process.

When you create a new application you will define a name for it and which environments the application should have.

Microservices

Each application acts as a separate area wherein your microservices run. When you navigate in an application in Studio you will see the services that are deployed in that application.

Each microservice will be listed with their name, container-image, which version of the Dolittle Runtime (if any) they are set up with, their publich URL (if any) and their status. If your application has multiple environments you can switch between them using the dropdown in the top right corner.

You can navigate into each Microservice to see more details about it, such as the logs for the service, the configuration for the service and metrics like the CPU and Memory consumption of the service. You can change the configuration of the service and restart it from this view.

Functions

There are several functions available in an Application -view. You can create new Microservices, and you can access the backups of the databases that are used by the services in that application.

Each application has its own docker-image container registry, which you can access from the application view.

There is a log-viewer, which consolidates logs from all the services in the application into one view. Here you can filter the logs by service, time and search for specific text. You can also have a live-view of the logs, which will update the view as new logs are generated.

There is a documentation-view in the application that contains sections on how to access the container-registry, how to access the underlying Kubernetes cluster if needed and how to setup Azure Pipelines to deploy your containers directly to the application.

3 - Environment

An environment is a grouping of Microservices within an Application. Environments are commonly used to separate instances of your Microservices into different stages of your development process.

When you create an Application you define which environment(s) you want in that Application. The available options are Development, Test and Production. You can choose to have all three, or just one or two of them.

Microservices

Each environment acts as a separate area wherein your microservices run. When you navigate to an Application in Studio it will list the Microservices running in the current environment. The current Environment is displayed and can be changed in a drop-down box on the top right corner of the page.

Databases

Each environment has its own database. The database is used by the Microservices in that environment to store their data. The database is a MongoDB database and is managed by the Aigonix Platform. You can access the database backups through the Studio interface. If necessary you can also access the database through port-forwarding to the Kubernetes cluster. You will need to contact Aigonix Support to get the elevated permissions needed to access the database directly.

4 - Microservice

A Microservice is a single unit of deployment in the Aigonix Platform. It is a containerized application that runs in a Kubernetes cluster. Each Microservice is deployed as a separate container in the cluster.

A Microservice lives inside an Application and can be deployed to multiple Environments in that application.

A Microservice in the Aigonix Platform is a Head and optionally a Runtime and data-storage. If you use the Dolittle Runtime you will have access to the Event Store and Read Cache for that Microservice.

If you do not use the Dolittle Runtime the Microservice will be stateless and will not have access to any storage. Any state you need to store will have to be stored in an external service. You will have access to the local file-system, but that is not persisted between Microservice restarts, and we do not recommend relying upon it.

Docker image

Each Microservice is deployed using a Docker image. You can use a publicly available image, or you can use a Docker image that you have built yourself and stored in the container-registry that is available for each application.

Head

Head is the name of the pod where your Microservice Docker image is deployed. It is the entry-point for your Microservice and is the only part of your Microservice that may be exposed to the internet. A Microservice must have a Head and can have a Runtime.

Dolittle Runtime

Each Microservice can be deployed with the Dolittle Runtime. The Dolittle Runtime is available as a docker image, and will be deployed alongside your Head. Your code communicates with the Runtime through the Dolittle SDK. The Runtime is used to connect to the Event Store and will make the resource-system available to you, where you can get the Tenanted Read Cache and to publish events to the Event Horizon.

Configuration

Each Microservice can be configured with a set of environment variables and configuration-files. These variables are available to your code and can be used to configure your Microservice. The Aigonix Studio gives you an interface to manage these variables and files.

Your code can read the environment variables and configuration-files. The files will be available under the /app/data -folder in your container. The Aigonix Platform will make sure that the files are available in the container when it is deployed. Therefore any files your image contains in /app/data will not be available when running in the Aigonix Platform.

You can upload files through Aigonix Studio, and you can also download the files and environment variables from Studio.

Secrets

You can also use the environment variables to store secrets, like connection strings and API-keys. Mark these environment-variables as secret to ensure that they be stored encrypted in the platform. You may want to look into a proper secret-management system, like Azure Key Vault or Amazon Key Management System if you have a lot of secrets, and just store the access-keys in the environment variables.

5 - Integrations

Integrations in Aigonix lets you work with your existing business-data in an ERP-system. The integrations support an Event Driven Architecture and is designed to make translation from ERP-specific terms to domain terms easy.

By setting up integrations your business data from an ERP -system (Infor M3) synchronize to an message stream. This data can then be used by your Microservices to provide functionality to your users and customers.

This article will introduce you to the concepts of the Aigonix integrations and show you how to set up a connection to an ERP -system and how to map data from the ERP -system into messages. It also describes how to consume these messages in your services.

Conceptual overview

graph TB
    People(People) --set up connection--> Connection[Aigonix integrations]
    People --use--> Services
    Connection <--changes--> ERP[ERP-system]
    Connection <--messages--> KT[/Messages/]
    Services <--reacts to--> KT

Central to this is the concept of a message-type. You define how to translate data from the ERP -system into messages. Message-types are defined in the Aigonix Studio -interface where you can select the tables and fields you want to translate. This mapping then translates the changes in business-data into messages whenever such a change is detected.

Connections

In order to translate data from the ERP -system into messages a connection must be specified. The connection defines how to connect to the ERP -system and the message-types how to translate the data into messages. Once you define the connection you can either run an instance of the ERP Integration service yourself (on-premises), or automatically host one in the Aigonix platform. This service is the conduit between the messages and the ERP -system. It discovers changes and translates those into messages. It also reacts to messages and calls programs in the ERP-system at your request.

Message-types

The message-types are defined in the Aigonix Studio -interface, and deployed to the ERP Integration service. They are defined in terms of the data in the ERP -system.

Setting up a connection

Step 0: Name and deploy the connection

Step 1: Connect to the Metadata Publisher

Step 2: Connect to ION

Mapping tables

At this point you have a connection to your M3 -instance, and are ready to start mapping data from it to messages with the mapping interface. This interface is available by clicking on the “message types”, next to “configuration”.

Step 0: Create a message-type

Step 1: Name the message-type

Step 2: Select the table

Step 3: Select the fields

Step 4: Name the fields

Step 5: Save the message-type

Step 6: Deploy the message-type

Step N: Refine the message-types

Consuming data

Having mapped the business-data from your ERP -instance into messages-types and deployed these message-type to the connection you can now consume messages in your services.

The connection will translate changes in the ERP -instance into messages that are available as a stream on a Kafka -topic.

If you do not want or need a full stream of changes, just the “latest state” of the message-type (in our example - the latest state of an item in the catalogue) you can activate a REST -interface. This is often what you need if you want to display the data in a user interface, or work with it in tools like Power-BI.

Option 1: Event stream (messages on a Kafka topic)

Option 2: REST API (latest state of a message-type)

Summary

In this article we have seen how to set up a connection to an ERP -system and how to map data from the ERP -system into messages. We have also shown how to consume these messages in your services. This is the core of the Aigonix integration, and it is how you make your business-data available to your services.

The Aigonix integration is designed to make it easy to work with your business-data and to make it easy to translate from the “language” of your ERP -system to the “language” of your services. This is done by mapping the data from the ERP -system into messages that are available as a stream. You can also use the REST -interface to get the latest-state of the message-types.

By setting up a connection to your organization’s ERP -system you make the business-data available to your services. This lets you build services that react to changes in the business-data expressed in your domain-language and that affect changes in the business-data, without needing a direct connection to the ERP -system.

Details (for the technically inclined)

The Aigonix integration works by connecting to the ERP -system (M3) and translating changes in the business-data into messages. This is done by the ERP Integration service, which knows how to poll and to set up webhooks for ION. It translates to messages, and sends that to the correct streams. The ERP integration service exposes webhooks that ION can use to notify of changes, and it polls at intervals to discover changes in data.

An interface to configure the ERP Integrations service exists in Aigonix studio, which is how you configure message-types and set up new connections. The ERP Integration service can run on-premises, or it can be hosted in the Aigonix platform. In either case it is controlled by your setup in Aigonix studio.

You decide whether to self-host or use the Aigonix platform to run the integration-service. This decision typically relies on your networking rules.

graph TB
    subgraph Enterprise with M3
        ION --calls--> M3P[Programs]
        M3P --enact changes--> M3DB
        ION --accesses--> M3DB[(Business data)]
        MDP[Metadata publisher] --describes schema--> M3DB
    end
    subgraph Aigonix platform
        MS[Your services] --consumes--> KT
        subgraph Aigonix integrations
            Connection --configures--> ERPI
            Mapping --defines mapping for--> ERPI[ERP Integration service]
            ERPI --publishes--> KT[/Messages/]
        end
    end
    ERPI --polling--> ION
    ION --webhooks--> ERPI
    Mapping --gets metadata from--> MDP
    People(People) --map messages--> Mapping
    People --configure connection--> Connection
    People --use--> MS

6 - Container Registry

All Microservices running in the Aigonix Platform are running in Docker containers. You can run public images, or you can run your own images. If you do not wish to publish the images of your Microservices to publicly available registries you can use one Aigonix provides for you.

This container registry is available at a unique host for your customer account. You can find the host in the documentation for your Application in Studio. It will look like {your-random-id}.azurecr.io.

To list what images are available in the registry you can navigate to the container-registry in Aigonix Studio, or you use the az command-line tool. You will need to log in to the Azure CLI and then you can run

az acr repository list --name {your-random-id} -o table

from your command-line. This will list all the images available in the registry.

To push a new image to the registry you tag the image with the registry host and then push it to the registry. You can do this with the docker command-line tool. Let us say you have an image called my-image that you want to push to the registry. You would then run

docker tag my-image {your-random-id}.azurecr.io/my-image:latest
docker push {your-random-id}.azurecr.io/my-image:latest

from your command-line. This will push the image to the registry and make it available for you to use in your Microservices. This image will not be available on public registries, it will only be available to you.