Preparing for installation

Preparing for installation#

In this section you will prepare your environment by installing and configuring all software prerequisites.

Before installing nJAMS Server, make sure that your system meets all prerequisites. Each of the prerequisite steps must be carried out before performing the installation.

Preparing Oracle Database System#

If you want to use your Oracle RDBMS, create a dedicated schema and user for nJAMS Server to allow the Installer to create tables and views.

Required Oracle database privileges and settings:

In order to create the nJAMS Server database objects (tables, etc.) the following privileges are required by the database user:

Permission:

Type:

CONNECT

Role

RESOURCE

Role

CREATE TABLE

System privilege

CREATE VIEW

System privilege

CREATE SEQUENCE

System privilege

If your database account has not been provided with these required privileges, the nJAMS Server database cannot be created during installation procedure.

Access to DBA_RECYCLEBIN table:

Additionally, nJAMS Server needs to access the DBA_RECYCLEBIN table to be able to automatically delete and restore constraints if necessary. The nJAMS database user needs to have SELECT ON SYS.DBA_RECYCLEBIN permissions.

Please run the following SQL statement to set the required permission:

GRANT SELECT ON SYS.DBA_RECYCLEBIN TO <njams-user>;

If you want to manually configure an Oracle datasource in WildFly Application Server, the following WildFly property has to be set to an empty string:

njams.db.dialect=

Note

An empty string cannot be entered within WildFly’s Administration Console. Instead the WildFly CLI has to be used, or you have to edit WildFly’s config file standalone.xml.

Preparing Microsoft SQL Server#

For using Microsoft SQL Server database, prepare a database and a user, login to allow nJAMS Server Installer to create required tables and views.

Required SQL Server privileges and settings:

In order to create the nJAMS Server database objects (tables, etc.) the following privileges are required by the database user:

Privileges:

In order to create the nJAMS Server database objects (tables, etc.) the following privileges are required by the database user used for installing nJAMS Server:

  • CREATE TABLE

  • CREATE VIEW

  • DELETE

  • EXECUTE

  • INSERT

  • REFERENCES

  • SELECT

  • UPDATE

The LOGIN requires:

  • CONNECT SQL

Settings:

The following settings have to be applied to SQL Server:

  • Set transaction isolation level to READ_COMMITTED_SNAPSHOT

  • Set initial log file size to at least 5MB

If you want to manually configure a SQL Server datasource in WildFly Application Server, the following WildFly property has to be set:

njams.db.dialect = org.hibernate.dialect.SQLServer2012Dialect

Note

If you have a connection string that specifies a particular SQL Server instance, please enter a double backslash between machine name and instance name as follows in this example: jdbc:sqlserver://mymachine\\mssqlserver14:1433;databaseName=njams

SSL/TLS:

Please use TLS 1.2 or higher, in case you want to use a secure connection to your SQL Server instance. Previous versions 1.0 and 1.1 of TLS will not work any longer.

Preparing PostgreSQL#

If you want to configure a PostgreSQL datasource in WildFly Application Server, set the following property to an empty string:

njams.db.dialect=

Note

An empty string cannot be entered within WildFly’s Administration Console. Instead use WildFly CLI, or edit WildFly’s config file standalone.xml.

Preparing Elasticsearch Cluster#

In case you want to use a prepared Elasticsearch Cluster please note, that scripting has to be enabled. Login with terminal in the Elasticsearch node server(s) and edit <ES_HOME>/config/elasticsearch.yml.

The following entries have to be included, respectively changed:

For Elasticsearch 7.x and OpenSearch 1.3:

Make sure to include inline and stored scripts, e.g. script.allowed_types: [inline, stored] - script.painless.regex.enabled: true

Set up minimal security for your Elasticsearch / OpenSearch Cluster. Please see https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-minimal-setup.html for more details.

Please refer to chapter Recommendations to setup an Elasticsearch cluster for production to learn more about sizing and configuration of an appropriate Elasticsearch cluster for nJAMS.

Preparing messaging#

Starting with release 6, nJAMS Server receives events from nJAMS Clients via HTTP/S by default. Using HTTP/S as commuication layer is the easiest way to receive events from nJAMS Clients connected to integration platforms in various runtime environments such as containers, cloud, etc.

nJAMS Server can be configured to receive events from nJAMS Client using a Data Provider of type HTTP/S. The default URL is:

[njams-server]:[port]/processing/ingest/[dpendpoint]

By default, the Data Provider endpoint suffix is sdk, so the complete URL of the Data Provider would be for example https://localhost:8080/processing/ingest/sdk. You can specify the endpoint suffix in the configuration of a Data Provider.

Furthermore, nJAMS Server makes use of common messaging platforms like TIBCO EMS, Apache ActiveMQ / Artemis to communicate with nJAMS Client. It still makes a ton of sense to use a classic messaging layer between nJAMS Server and nJAMS Client with regards to delivery reliability and decoupling.

If you decide to use nJAMS with a messaging platform (JMS) or event streaming platform (Kafka), this platform has to be provided by the customer. In the further course it is described how such a platform must be configured for nJAMS.

Preparing JMS Provider (optional)#

nJAMS Server requires a JMS Server up and running.

Preparing Apache ActiveMQ Classic / Artemis:

For using your own corporate ActiveMQ Classic / Artemis instance, create a separate user for nJAMS Server that is authorized to the following destinations:

Destinations:

Type:

Privileges:

<prefix>.event

queue

read, write

<prefix>.error

queue

read, write

<prefix>.metrics

queue

read, write

<prefix>.command

queue

read, write

<prefix>.commands

topic

read, write

The <prefix> can be defined by the user, default prefix is njams. The prefix can be specified when you create or update a JMS Connection in nJAMS Server UI. For creating or updating a JMS Connection please refer to manual nJAMS Server Administration Guide.

If you want nJAMS Server Installer to install an Apache ActiveMQ JMS Provider, you are asked to enter the prefix for the destination name.

Note

If you want nJAMS Server Installer to create the destinations, the used JMS user needs admin privilege.

Preparing TIBCO EMS:

For using your own corporate TIBCO EMS server, create a separate user for nJAMS Server that is authorized to the following destinations:

Destinations:

Type:

Privileges:

<prefix>.event

queue

receive, send

<prefix>.error

queue

receive, send

<prefix>.metrics

queue

receive, send

<prefix>.command

queue

receive, send

<prefix>.commands

topic

subscribe, publish

This user also needs the following admin permissions to use TIBCO EMS queue/topic statistics for nJAMS Data Provider:

  • view-destination

  • view-server

The <prefix> can be defined by the user, by creating or updating a Data Provider in nJAMS Server UI.

Note

It is recommended to add an expiration time of 5 seconds to the <prefix>.command queue.

This is a sample script to create destinations required by nJAMS Server:

create user njams "njams user" password=njams
grant admin njams view-destination,view-server
create queue njams.event
create queue njams.error
create queue njams.metrics
create queue njams.command expiration=5
create topic njams.commands expiration=5
grant queue njams.event user=njams receive,send
grant queue njams.error user=njams receive,send
grant queue njams.metrics user=njams receive,send
grant queue njams.command user=njams receive,send
grant topic njams.commands user=njams subscribe,publish

Preparing Kafka instance#

For using your own corporate Kafka instance, create a separate user for nJAMS Server that is authorized to the following topics:

Destinations:

Type:

Privileges:

<prefix>.event

topic

read, write, describe

<prefix>.project

topic

read, write, describe

<prefix>.error

topic

read, write, describe

<prefix>.metrics

topic

read, write, describe

<prefix>.commands

topic

read, write, describe

This user also needs permission for the prefix of the consumer group of the connection.