Managing Applications

Creating An Application

You can use Self Service Portal to create (register) your application. This can be done before the application is actually developed and/or released.

First of all, a Self Service registration for an application is necessary to provide access to the application. Secondly, it provides a great overview of all the streaming data pipelines active on the streaming platform.

Custom vs. Connector

When creating an application in Self Service, you need to define the Application Type, which is either "Custom" or "Connector". This needs some explanation:

  • Custom: any custom developed and deployed application (e.g. Java, .NET) using the Axual Client

  • Connector: a connector application is running in Axual and serves as a data source or sink, connecting external systems like a database or message queue to 1 or more Streams. The type of system you make a connection with, determines which Connector Plugin to use. In order to use a connector, no development is required, merely configuration.

Creating A Custom Application

Are you integrating an external system with Axual, such as a database or message queue ? Please follow Creating A Connector Application
  1. To register your application, visit the Applications page and click the New Application button.
    You will see a screen as below:

    Add application page
  2. Start filling the form with required information:

    • ID: This represents the Application ID of your application. This is a string that uniquely identifies your application. We recommend to use a fully qualified package/class name as it is sufficiently unique within the organization, e.g. com.company.division.AlertingApp. The maximum length is 255 and the value should be alphanumeric with no spaces.

    • Name: The name of the application. It should not be more than 50 characters. Spaces are allowed.

    • Short Name: A unique human-readable short name of the application. This name is used as a label in Self Service. Only alphanumeric characters and underscore are allowed. Max length should not exceed 60 characters.

    • Owner: Choose the group which would be the owner of this application. Choose your DevOps team’s group. Is it not available yet? Please refer to Creating a group.

    • Type: choose "Custom"

    • Custom Type: Choose the type of application, purely acting as metadata.

    • Visibility: see Application visibility below

    • Description: A short summary describing the purpose of this application, e.g. "Enriching transaction events with transaction categories.". Must not exceed 200 characters.

At this point you have created your Application in Self Service. Once the application is successfully created, you will be directed to the application detail page.

the Application ID is used by consuming applications to keep track of where it left off consuming messages from a stream. Consumers sharing the same ID share the events on a stream. So one event can be only read by one consumer with the same Application ID (read more about consumer groups).

Configuring Application Principals

The application principal is used to authorize the application to use a stream (either producing or consuming) in an environment. The application principal consists of the Distinguished Name (DN) of the certificate used by the application, combined with the full chain of authority up to and including the Instance principal (ie. start the file with your application certificate, followed by the certificate of the entity that signed your certificate request, followed by the certificate of the entity that signed the previous one, etc, etc, until you reach the entity that is proclaimed as principal of the Instance you will run your application in).

What is defined here is NOT applicable for the SSL connection made between your application and the Broker at runtime. It is not authentication, only authorisation. You will have to provide a keystore with your application, with a valid certificate, signed by an intermediate or root CA which is supported by our truststore, which should contain the principal you’ve uploaded here.
For every distinct environment, an application principal needs to be defined. A principal could be re-used, but we strongly advice to have a unique one per environment. Without a principal, an application cannot have consume/produce-access to a stream.

To configure the application principal on the selected environment:

  1. Visit the detail page of the application.

  2. Select the environment for which you want to configure the principal.

  3. Click on the Configure button in the application box. You will see a modal as below:

Configure application principals modal
  1. Upload the PEM file of your application certificate, see Generating A Certificate PEM File

  2. The certificate chain will be shown, in a reverse order from Keystore Explorer, meaning the chain will start with your application certificate. Confirm that the uploaded certificate matches the certificate you will use for your application in the corresponding environment.

  3. Click on Save.
    The application box name will turn green indicating that the application is configured properly on that environment. Above steps can be repeated for different environments where application is required to access the stream.

If you are replacing an application certificate, you can register 2 principals at the same time, and choose to delete the old one once the application is not using it anymore.

Generating A Certificate PEM File

To reduce human error and to validate the uploaded certificates, we have opted to let the user upload a .pem file for his/her certificate-chain.

Most of the time, you are using a .jks file for your application already, so you can use the following instructions to extract a .pem from a .jks file, ready to be used in Self Service.

The following is taking into account that you are using a bash terminal and not ZSH or another custom terminal to run the following commands.
  1. Export the .jks keystore into the PKCS12 format using Keytool, which generally comes with every JRE installment.

Be sure to replace yourAlias with the alias of your application certificate, sourceKeyStore with the path of your .jks file, and password with your own password.

keytool -importkeystore \
  -alias yourAlias \
  -srckeystore sourceKeyStore.jks \
  -srcstoretype jks \
  -srcstorepass password \
  -destkeystore destFile.p12 \
  -deststoretype PKCS12 \
  -deststorepass password
  1. Retrieve the application certificate to the target .pem file, using the openssl command

openssl pkcs12 \
  -in destFile.p12 \
  -nokeys \
  -passin pass:password \
  -passout pass:password \
  | grep -v -e '^\s' | grep -v '^\(Bag\|subject\|issuer\)' > destKeyStore.pem

This results in a .pem file which can be uploaded as an application principal.

Requesting Stream Access

Before your application can produce to, or consume from, a stream, a Stream Access Request has to be done. If you are making a request for an environment for testing purposes (private), an approval will not be necessary. For all other (public) environments, approval is necessary. The request is then received by the data owner of the stream.

Requesting access to a stream is easy. Follow the steps below:

Before you request stream access, make sure you have configured the Application Principal for the specific environment in which you request access (see above)
  1. Visit the detail page of your application.

  2. Scroll to the bottom of the page where + Add request button is visible.

  3. Click on the button to open the Request approval modal:

Request approval modal
  1. Select the Application type by clicking on Consumer or Producer button.

  2. Select the Stream from the Stream dropdown. If there are already pending and/or approved requests for this stream a list of them will appear after selection.

  3. Select the Environment from the dropdown.

  4. Submit the request by clicking the Request approval button.

The data owner will receive your request and has to approve your ‘Stream Access Request’.

Deleting An Application

You can use Self Service Portal to delete your application. This can be done if there are no active producer/consumer stream connections in all environments.

  1. Visit the Application Detail page

  2. Click Edit Application.

  3. There is a Delete Application button on the bottom left of the page. Clicking on that button, if all constraints are met and deletion is possible, a confirmation modal opens, as below:

Delete application confirmation
  1. Clicking on Confirm will delete the application. Otherwise, a modal opens with information on how many active stream connections there are in all environments, as below:

Inform application modal

Application visibility

By setting the application visibility, you control whether applications will end up in the Applications page for everyone, or is just visible to the owner.

  • Public: choose this option if you are working on a normal application that will be eventually deployed in production, and is not confidential in any way

  • Private: choose for private if this is a test application that will never be deployed in production or an application that should not end up in the Applications page.