abas Essentials SDK

This is the documentation for abas Essentials SDK.

Introduction

abas Essentials SDK is a software development kit intended to be used for customizing abas Essentials.

abas Essentials SDK enables developers to handle all parts of an abas Essentials customization in one project. As abas Essentials SDK uses the technology of JFOP server Apps for code deployment in abas Essentials, abas Essentials SDK projects are called ESDK Apps.

The following abas Essentials customizations can be automated using abas Essentials SDK:

Add logic and automated tests to the project using abas Java Objects (AJO) or other programming languages
Create/update data objects, enumerations and/or named types in abas Essentials
Add/update/delete variables from variable tables
Create new additional variable tables
Import customized database screens
Import infosystems and infosystem screens
Copy any files to $MANDANTDIR or sub-directories
Add lines to fop.txt
Add lines to mandantdir.env
Add lines to logging.custom.properties

1. Project setup

Setting up a new ESDK App Project for development.

1.1. Prerequisites

For development with abas Essentials SDK we recommend the following software and tools:

1.1.1. Software on your development machine

To develop an app, the following technologies must already be installed on your development machine:

JDK8, Java Development Kit
Gradle, a build automation tool
Docker, a software containerization platform

For further information take a look at the appropriate homepages.

1.1.2. Develpoment tools

an IDE (e.g. Eclipse, IntelliJ IDEA, abas Tools)
a commandline interface (bash, PowerShell, Terminal)
an abas Essentials client
a Nexus Artifact Server

You can use a dockerized abas Essentials client and Nexus Artifact Server or one or both as a self-hosted and self-administered instance.

1.1.3. abas Essentials and Nexus Artifact Server as Docker Containers

We recommend to develop with Docker containers.

To download the docker images and start the erp and nexus containers you can download the docker-compose.yml file and run

docker-compose up -d

The ESDK Project Builder generates a docker-compose.yml file for the abas Essentials version you have chosen as "Development Version".

Alternatively you can run the following two commands and do the naming and port mapping manually:

docker run --init -d --name erp -p 2205:22 -p 8001:80 -p 6560:6550 -p 48592:48392 -e ABAS_GUI_PORT=48592 -h dockerbau sdp.registry.abas.sh/abas/test:<version> run (1)

docker run -d --name nexus -p 8081:8081 sonatype/nexus:oss

1	Replace `<version>` with the version of abas Essentials you want to develop against, e.g. 2017r4n16p02. For version 2016r4n13 you don’t need the option `run`

Using docker logs erp -f you can see all log messages during container start up.

1.1.4. Self-hosted and self-administered instances

If you already have an abas Essentials installation and/or a Nexus Artifact Server and want to use them for development, you can do so, too.

You need to make sure that your abas Essentials installation can access the Nexus Artifact Server. Otherwise the publishHomeDirJars and publishClientDirJars tasks will not work. Often when using an existing abas Essentials installation it does not have access to your local computer. If you want to use a dockerized Nexus Artifact Server you can also start it on the server your abas Essentials installation runs on.

2. Setup ESDK development environment

Set up a development environment for a new or an existing ESDK App.

Overview abas ESDK development environment

2.1. Setup abas Essentials client and Nexus Artifact Server

2.1.1. Log in to the abas Partner Docker Registry

To access the abas Essentials Docker images you have to log in to the abas Partner Docker Registry.

docker login sdp.registry.abas.sh

Use your extranet credentials for authentication.

In order to be able to pull Docker images from the abas Partner Docker Registry you need to accept the License Agreement.

2.1.2. Start the containers

Start abas Essentials and Nexus Artifact Server containers as described in the Docker chapter.

2.2. Download and configure the mini-GUI

When the abas Essentials container is ready, open the following URL in the browser of your choice: http://<your-ip-address>:8001 Download abasgui-mini-erp.tgz and wineks-erp.ini. Unpack the abasgui-mini-erp.tgz archive, rename the wineks-erp.ini file to wineks.ini and copy it into the unpacked mini-GUI directory. Edit the wineks.ini file to look like this:

[wineks]
server   = erp
sprachen = Deutsch Englisch

[erp]
host=<your ip address> (1)
useEksd=true
portEksd=48592 (2)
client=/abas/erp
text=abasERP in Docker

1	Enter your IP address, your IP address can be determined by executing `ifconfig` (Linux/Mac) or `ipconfig` (Windows) in your preferred command line interface.
2	Enter the abas GUI port here, the port mapping is done in the `docker run` command you executed earlier, or is configured in the `docker.compose.yml` file.

2.3. Start abas Essentials

Start abas Essentials by running wineks.exe, or for newer abas Essentials clients abasgui.exe.

You can only run wineks.exe, or abasgui.exe on Windows. If you are on another operating system, you need to use a virtual machine to use the abas Essentials user interface (not for ESDK App development in general).

3. Create your ESDK App

3.1. Register your App ID

Go to the ESDK Developer Portal. After logging in with your extranet credentials, you will see a list of all App IDs already registered by your company. To add a new App ID press the red plus button in the upper right corner. Enter your desired App ID and click the Create button.

App ID creation is free of charge. To ensure every ESDK App uses a unique App ID we require App ID registration for all ESDK Apps (no matter whether you plan to publish your App to the abas Marketplace or not). If you do not register your App ID, you cannot install your ESDK App using the ESDK App Installer. Since another App can register and use your App ID, your App’s additional variables might be overridden.

3.2. Create your components in abas Essentials

You can create for example infosystems, additional databases, variables, database screens, data objects, translations, keys and enumerations.

3.3. Create a new ESDK project

After you finished creating your components in abas Essentials, you need to create a new ESDK App Project. You can use the commandline tool Project Initializer, or the web interface Project Builder.

3.3.1. Project Initializer

Use the Project Initializer to generate the initial project structure.

3.3.2. Project Builder

Go to the ESDK Project Builder and fill in the appropriate data, such as connection data and the name and dependencies of your app. Reference all the components you previously created in the abas Essentials client, generate and download the project Zip file. Unzip the project to a directory of your choice.

Extranet credentials are required to login and access the ESDK Project Builder. If you do not have extranet credentials you can contact us.

3.4. Configure your project settings

There is a predefined template available to connect to the abas Essentials client and Nexus Artifact Server in a Docker container. Generate the settings on your development machine by running: ./initGradleProperties.sh in your preferred command line interface to create the gradle.properties file.

Make sure that after you run initGradleProperties.sh every host value (nexus, edp and ssh) in the gradle.properties file is set to your IP or the IP of the machine the erp runs on. Using localhost will not work!

3.4.1. Configuring the SSH connection timeout

The default timeout for connecting to your abas Essentials client via SSH is 3 seconds.

To configure the timeout add the timeout property to your ssh closure in your build.gradle and set it to the desired value (e.g. 5000 for 5 seconds):

build.gradle

ssh {
        host = SSH_HOST
        port = SSH_PORT.toInteger()
        user = SSH_USER
        password = SSH_PASSWORD
        timeout = 5000
}

Alternatively, you can add it as a property to your gradle.properties and reference it in your build.gradle:

gradle.properties

SSH_HOST=yourhost
SSH_PORT=2205
SSH_USER=erp
SSH_PASSWORD=none
SSH_TIMEOUT=5000

build.gradle

ssh {
        host = SSH_HOST
        port = SSH_PORT.toInteger()
        user = SSH_USER
        password = SSH_PASSWORD
        timeout = SSH_TIMEOUT.toInteger()
}

3.4.2. Logging

By default the abas Gradle Plugin logs all EDP commands to build/logs/edp.log.

The logging directory can be changed by setting logFileLocation in the abas section of your build.gradle file:

build.gradle

abas {
    ...
    logFileLocation = "$buildDir/logging"
}

For example, you can redirect the EDP log output to a separate directory with the called task’s name within build/logs as follows:

build.gradle

abas {
    ...
    gradle.taskGraph.whenReady {
        logFileLocation = "$buildDir/logs/${gradle.taskGraph.getAllTasks().get(gradle.taskGraph.getAllTasks().size() - 1).name}"
    }
}

When calling ./gradlew checkPreconditions this would generate a log file build/logs/checkPreconditions/edp.log.

3.5. Import the project in your IDE

Import the project as a Gradle project in your IDE. In Eclipse for instance, this enables you to execute Gradle tasks directly from an Eclipse View.

When using abas Tools please make sure to use the latest version, at least version 1.4.0.

3.6. Export your abas Essentials components

Use the Gradle task "exportAll" from our abas Gradle Plugin to export all of your new components from the abas Essentials client to your project. You can either run the task right from your IDE or in your preferred command line interface. To run it on the command line: change to the directory where your app is located and execute the following Gradle command: ./gradlew exportAll

To get an overview about all available tasks, you can run ./gradlew tasks on your command line interface. The abas Gradle Plugin tasks are listed in the group Abas tasks.

3.7. Add logic

Once the exportAll step is finished, your abas Essentials components are copied to your project and you can start to add some logic.

3.7.1. Regenerate the AJO classes

To include classes for your newly created components run the installAjo task.

3.7.2. Provide abas specific dependencies

In order for your project to know about the abas specific dependencies, needed for development with JEDP and AJO, run the publishAllJars tasks and refresh the Gradle project in your IDE.

3.7.3. Use additional dependencies

To add dependencies to your project they have to be in a Maven repository. This can either be a publicly available Maven repository like Maven Central or a private one that runs locally or in your company’s internal infrastructure.

You have to first add the repository to the repositories block in your build.gradle, then add the dependency to your dependencies block. Specify the Maven group, module name and version. E.g. to add Google’s Gson Library to your app add the following to your build.gradle:

build.gradle

repositories {
    ...
    mavenCentral()
    ...
}
...
dependencies {
    ...
    implementation 'com.google.code.gson:gson:2.8.5'
    ...
}

For more information regarding dependency management refer to the Gradle Documentation.

How the shared option influences additional dependencies

In your build.gradle you can use the shared option to specify what configuration you want to use for parent.delegation of your JFOP-Server App. You can use parent.delegation=true or parent.delegation=false.

For ESDK Apps the default value for parent.delegation is false. If you set shared = true, parent.delegation is set true and the default value for parent is set to DEFAULT_SHARED automatically if nothing else is specified.

For simple EventHandler classes that only use the jar files in abas Essentials standard delivery, this is fine. You can specify an alternative value for your parent classpath by setting parent=<YourClasspathName> in your build.gradle file like in the following example:

esdk {
	app {
		...
        shared = true
        parent = DEFAULT
		...
	}
	...
}

The parent option also allows you to create a dependency structure between multiple apps that are interdependent:

esdk {
	app {
		...
        shared = true
        parent = <YourAppId>
		...
	}
	...
}

You should only change parent.delegation to true by setting shared=true in your build.gradle, if you explicitly need to share dependencies provided by another JFOP-Server App (the jar files in $HOMDIR/java/lib are provided with the JFOP-Server App named DEFAULT).

If you are using third-party libraries, we highly recommend to let shared set to false and specify the app’s dependencies explicitly. This keeps its classpath clean and avoids version collisions between third-party libraries that come with your app and the abas Essentials standard delivery.

How to explicitly use a dependency

There are three configurations that define which dependencies the app needs when and how they are provided:

provided: Those dependencies are needed to compile the app but are provided at runtime by the s3jfopserver_bootstrap.classpath and thus not packaged with the app. They must not be listed in the app’s classpath file. The ESDK Gradle Plugin checks that they are not used in the other dependency configurations.
implementation dependencies are needed to compile the app and are explicitly listed in the app’s classpath file. If they do not belong to group de.abas.homedir or de.abas.clientdir, they are packaged with the app and get installed in the JFOP-Server App’s lib directory.
runtime dependencies are not needed to compile the app but to execute it at runtime. Examples are logging frameworks, Apache Commons Collections or abas-jfop-base.

An example

If you want or have to explicitly use a JAR provided in $HOMEDIR/java/lib you can reference it in your build.gradle 's dependency block using the provided, implementation or runtime configuration. All libraries in $HOMEDIR/java/lib are uploaded to the Nexus server and can be referenced as following:

build.gradle

dependencies {
        provided "de.abas.homedir:abas-db-base:1.0.0"
        provided "de.abas.homedir:jedp:1.0.0"
        provided "de.abas.homedir:abas-jfop-runtime-api:1.0.0"
        provided "de.abas.homedir:abas-erp-common:1.0.0"
        provided "de.abas.homedir:abas-enums:1.0.0"

        implementation "de.abas.homedir:abas-axi2:1.0.0"
        implementation "de.abas.homedir:abas-axi:1.0.0"
        implementation "de.abas.homedir:abas-db-internal:1.0.0"
        implementation "de.abas.clientdir:abas-db:1.0.0-SNAPSHOT"
        implementation "de.abas.clientdir:abas-db-infosys:1.0.0-SNAPSHOT"

        runtime "de.abas.homedir:commons-collections:1.0.0"
        runtime "de.abas.homedir:abas-jfop-base:1.0.0"
        runtime "de.abas.homedir:jcl-over-slf4j:1.0.0"
        runtime "de.abas.homedir:slf4j-api:1.0.0"

        testImplementation "junit:junit:4.12"
        testImplementation "org.hamcrest:hamcrest-all:1.3"

        integTestImplementation "de.abas.homedir:abas-db-util:1.0.0"
}

All provided dependencies are automatically added to the implementation classpath (and thus to the deprecated compile classpath).

While missing provided and implementation dependencies get reported by the compiler or your IDE, missing runtime dependencies stand out when executing the app. A ClassNotFoundException is thrown, mentioning the missing class. The shell script jarversion.sh, provided by abas Essentials standard delivery, helps to find the right jar file:

jarversion.sh -c <fully-qualified class name>

jarversion.sh Example

$ jarversion.sh -c de.abas.erp.db.DbContext
Class: de.abas.erp.db.DbContext
Path: file:/abas/s3/java/lib/abas-db-base.jar!/de/abas/erp/db/DbContext.class

3.8. Use the esdk-client-api

The esdk-client-api enables you to use common functionality in your ESDK App's code, such as checking the abas Essentials has a valid license for your ESDK App, or getting properties such as your app’s name or App ID during runtime.

To use the esdk-client-api add the following dependency to the build.gradle file of your ESDK App:

dependencies {
    ...
    licensing "de.abas.esdk:client-api:0.0.12:all"
    ...
}

In order to resolve the esdk-client-api dependency you need to add the following repository:

repositories {
    ...
    maven { url "https://registry.abas.sh/artifactory/abas.maven-public/" }
    ...
}

For additional help refer to the esdk-client-api’s Javadoc.

3.8.1. Add license checks

To ensure, only abas Essentials clients with a valid license for your ESDK App can execute your app’s logic, you should add license checks.

At any point in your ESDK App's code you can check the license using the validate method provided by the LicenseChecker class from the esdk-client-api.

The validate method returns true for a valid license and false for an invalid license. You can then choose by yourself, whether, in case of an invalid license, you want to just display a warning, notify someone or abort the execution of your app’s logic.

In order for the license check to pass, the following conditions must be met:

A full-cloud or hybrid installation, i.e. Cloud Connect's License Controller, is set up and installed.
Your ESDK App needs to be registered on the abas Marketplace.
The abas Essentials client your ESDK App is installed in also needs to have a valid license for your app. Raise a request if you need a development license for an abas Essentials installation in one of our Docker images.

Do not overuse the license check, since every license check reduces the overall performance of your ESDK App.

3.9. Synchronizing your changes

Transferring changes between your abas Essentials development client and your local ESDK App Project The abas Gradle Plugin offers a range of Gradle tasks for transferring changes between your abas Essentials development client and your local ESDK App Project.

Tasks to transfer changes from your abas Essentials development client into you project are export tasks. Tasks to transfer changes from your local project to your abas Essentials development client are import or install tasks.

All ESDK App development specific tasks are grouped in either abas-basic or abas-advanced.

The abas-basic group contains all tasks necessary to get you started with ESDK App development:

checkPreconditions Check if your connection settings are correct
publishAllJars Make homedir and clientdir Jars available on the Nexus Artifact Server
exportAll export all configured components from your abas Essentials client to your project
syncCode synchronize code changes
fullInstall install all your app components and code in an abas Essentials client

If you are a more advanced user of the abas Gradle Plugin, you can also use the tasks in abas-advanced to only install/import or export the components you changed. This saves you some time during development but since there are quite a view components, it is also a less structured view.

3.10. Create the ESDK App

Once your app is ready to be delivered, you can create a jar file containing all the components that belong to your app.

The Gradle task createAppJar will pack all necessary files and information in a jar file.

./gradlew createAppJar

3.11. Install your app in another abas Essentials client

Install your app from the cloud or locally using the ESDK App Installer.

4. Nexus

Once you start developing an ESDK App, you need all AJO dependencies to be available in the Sonatype Nexus Artifact server, so that your IDE has access to these dependencies and you can develop logic for your ESDK App in AJO.

Previously samba shares where needed to access $MANDANTDIR/java/lib and $HOMEDIR/java/lib from your IDE. This is no longer necessary. All dependencies in $HOMEDIR/java/lib and $MANDANTDIR/java/lib are published to a repository on the Sonatype Nexus Artifact server.

Once the AJO artifacts are available on Sonatype Nexus, no connection to the client is needed at all for writing code and compiling against the AJO libraries.

4.1. Configuration

The Nexus Artifact Server can be run in a Docker container (as suggested in Setup ESDK development environment) or deployed and maintained by yourself.

Both Nexus Artifact Server versions, version 2 and 3, are supported. Nexus Server version 2 is the default.

The connection properties to your Nexus container need to be configured in the gradle.properties file in your project. For more details refer to Setup.

For your project to get the libraries from your Nexus, you will need to indicate two repositories. The first repository contains all the HOMEDIR libraries ($HOMEDIR/java/lib). The second repository contains the CLIENTDIR libraries, mainly abas-db.jar and abas-db-infosystem.jar ($MANDANTDIR/abasbase/java/lib).

For Sonatype Nexus version 2 specify:

repositories {
    maven { url "http://$NEXUS_HOST:$NEXUS_PORT/nexus/content/repositories/$NEXUS_NAME-SNAPSHOT" }
    maven { url "http://$NEXUS_HOST:$NEXUS_PORT/nexus/content/repositories/$NEXUS_NAME" }
}

For Sonatype Nexus version 3 specify:

repositories {
    maven { url "http://$NEXUS_HOST:$NEXUS_PORT/repository/$NEXUS_NAME-SNAPSHOT" }
    maven { url "http://$NEXUS_HOST:$NEXUS_PORT/repository/$NEXUS_NAME" }
}

Make sure the build.gradle file in your projects actually uses the NEXUS_VERSION property. It should contain the following line:

nexusVersion = NEXUS_VERSION

5. Project structure

The project resources can be found in the following directory and file structure.

yourAppProject
├── build.gradle (1)
├── docker-compose.yml (2)
├── gradle.properties (3)
├── gradle.properties.template (4)
├── gradlew (5)
├── gradlew.bat (6)
├── gradle (7)
├── README.md (8)
├── .gitignore (9)
├── Jenkinsfile (10)
└── src
    ├── integTest (11)
    ├── main (12)
    │   ├── java (13)
    │   └── resources (14)
    │       ├── advancedDbScreens (15)
    │       ├── base (16)
    │       ├── data (17)
    │       ├── dbscreens (18)
    │       ├── enums (19)
    │       ├── enumsAfterVarreorg (20)
    │       ├── IS (21)
    │       ├── keys (22)
    │       ├── namedTypes (23)
    │       ├── vartab (24)
    │       ├── fop.json (25)
    │       └── logging.custom.properties (26)
    └── test (27)

1	Project build configuration
2	ERP and Nexus as Docker containers
3	Generated with initGradleProperties.sh and gradle.properties.template
4	Template for your local gradle.properties file
5	Wrapper to execute Gradle tasks
6	Wrapper to execute Gradle tasks for windows
7	Directory for gradle distribution
8	Introduction how to setup a project
9	Configuration file for Git to specify what files should be ignored.
10	Template for a Jenkins Job configuration.
11	Your integration tests
12	Project source code and resources
13	Your source code
14	Your project resources
15	DB screens to override standard screens completely when installed in the client
16	Files to be transferred to the client
17	Data to import to the client
18	DB screens to be installed on the client
19	Enumerations to be imported
20	Enumerations to be imported after varreorg of imported vartabs
21	Infosystems which will be installed on the client
22	Keys which will be installed on the client
23	Named types which will be installed on the client
24	Variable table changes and custom databases
25	fop.txt changes
26	Specify your ESDK Apps log output
27	Your tests (e.g.: JUnit tests)

All files need to be saved in UTF-8 encoding. The only exception are files in src/main/resources/base that are explicitly needed in s3 encoding in the abas Essentials client, such as FOPs.

6. Project components

You can specify all components belonging to your app in the app{ … } section of the build.gradle file.

6.1. Example for GeoLocation

This is an example how this look like for our Geolocation demo app.

esdk {
	app {
		name = "GeoLocation"
		vendorId = "ag"
		appId = "g30l0"
		shared = false
		infosystems = ["IS.OW1.GEOLOCATION"]
		tables = ["GeolocationConfig", "Kunde"]
		screens = ["Customer:Customer": ["A", "D"], "GeolocationConfig:GeolocationConfig": ["A"]]
		data = ["data.json"]
		languages = "DA"
		essentialsVersions = ["2017r1n00-2017r4n16", "2018r1n00-2018r4n16"]
	}
	...
}

You can find the complete app source here: GeoLocation

6.2. All projects components

esdk {
	app {
		name = "" (1)
		vendorId = "" (2)
		appId = "" (3)
		shared = false (4)
		infosystems = [""] (5)
		tables = [""] (6)
		data = [""] (7)
		keys = [""] (8)
		enums = [""] (9)
		namedTypes = [""] (10)
		screens = [""] (11)
		advancedScreens = [""] (12)
		essentialsVersions = [""] (13)
		preconditions = [""] (14)
		languages = "" (15)
		workdirs = [""] (16)
	}
	...
}

1	The name for your ESDK App
2	Your vendor ID
3	Your App ID
4	Whether your JFOP server app uses parentDelegation.
5	Infosystems belonging to the app
6	Standard and additional tables
7	Data files to be imported during the installation
8	Keys
9	Enumerations
10	Named Types
11	Customized standard and additional database screens
12	Customized standard database screens to override screen completely
13	Version rang(es) you ESDK App is compatible to
14	Preconditions to be met prior to installation
15	Languages
16	Workdirs

7. Task overview

The following picture gives an overview about the most relevant ESDK tasks.

The tasks are grouped in basic and advanced ESDK tasks. Use the advanced tasks if you want to make specific changes. The basic tasks are a set of (advanced) tasks to simplify the app development.

8. Basic tasks

8.1. Publishing all JARs

This task executes both, publishHomeDirJars and publishClientDirJars to the Nexus server to get you ready for development.

8.2. Exporting all Components

The exportAll task runs all export tasks so that all project dependent components are exported at once.

For more information about the dependent tasks read each tasks documentation.

The export tasks run by exportAll are:

exportIS
exportDictionaries
exportEnums
exportNamedTypes
exportKeys
exportData
exportScreen
exportVartab

8.3. Checking Installation Preconditions

This Gradle task checks the preconditions for installing an ESDK App in an abas Essentials client.

First, all connection settings are tested:

Is the abas Essentials client accessible via EDP
Is the abas Essentials client accessible via SSH
Is the Nexus Artifact Server reachable
Is the abas environment set
Are the user rights sufficient

You can also configure additional checks for your ESDK App:

Check for an abas Essentials version range.
Check for specific working directories.

8.4. Installing the ESDK App

Main installation routine for installing an ESDK App using the abas Gradle Plugin.

8.4.1. Setup

Before the installation can be started, there are a few prerequisites.

The abas Essentials client needs to be running and accessible via both SSH and EDP. Further the Sonatype Nexus Artifact server needs to be running and username and password of a user with read and write rights need to be available.

If the abas Essentials client and/or the Sonatype Nexus Artifact server are supposed to run in a Docker container, the Docker container(s) should be started and running before the ESDK App installation is started.

In every ESDK App a file named gradle.properties needs to be created right in the root folder of the project. In this file all properties regarding credentials and host names or ports must be defined.

gradle.properties

ABAS_HOMEDIR=/abas/s3 (1)
ABAS_CLIENTDIR=/abas/erp (2)
ABAS_CLIENTID=erp (3)

EDP_CLIENT=/abas/erp (4)
EDP_USER= (5)
EDP_PASSWORD=sy (6)
EDP_HOST=<abas IP address> (7)
EDP_PORT=6550 (8)

NEXUS_HOST=<nexus IP address> (9)
NEXUS_PORT=8081 (10)
NEXUS_URL=https://your-custom-url (11)
NEXUS_NAME=docker (12)
NEXUS_USER_NAME=admin (13)
NEXUS_PASSWORD=admin123 (14)
NEXUS_VERSION=2 (15)

SSH_HOST=<abas IP address> (16)
SSH_PORT=22 (17)
SSH_USER=erp (18)
SSH_PASSWORD=none (19)
SSH_KEY= (20)

installType=SSH (21)

version=0.0.1 (22)

esdkSnapshotURL=https://registry.abas.sh/artifactory/abas.esdk.snapshots/ (23)

nexusUser=<abas extranet username> (24)
nexusPassword=<abas extranet password> (25)

1	Absolute path to `$HOMEDIR` in the abas Essentials client
2	Absolute path to `$MANDANTDIR` in the abas Essentials client
3	Name of abas Essentials client as in the `mandantdir.env`
4	The EDP client (in most cases same as `ABAS_CLIENTDIR`)
5	When Linux logins are used for authentication in abas Essentials, the username has to be specified here
6	Password used for authentication in abas Essentials
7	Host name or IP address of the server abas Essentials is running on
8	EDP port (if it is not reconfigured 6550 is the default port for EDP)
9	Host name or IP address of the server Sonatype Nexus is running on
10	Port the Sonatype Nexus Artifact server communicates on
11	Alternative to specifying `NEXUS_HOST` and `NEXUS_PORT`, if you are using a self-hosted Sonatype Nexus Artifact server you can specify its base URL with this property
12	Name of the repository the AJO artifacts will be stored in on Sonatype Nexus
13	Username to authenticate to Sonatype Nexus (admin is the default username after Sonatype Nexus is installed in a Docker container)
14	Password to authenticate to Sonatype Nexus (admin123 is the default password after Sonatype Nexus is installed in a Docker container)
15	Version of Sonatype Nexus (2 is the default value, optionally you can configure to use Sonatype Nexus Version 3)
16	Host name or IP address of the server abas Essentials is running on
17	ssh port (if it is not reconfigured 22 is the default port for ssh)
18	Needs to be a Linux user known to abas Essentials (usually s3 or the login for a specific client of the abas Essentials instance)
19	Password required to sign in via ssh to the server abas Essentials is running on using the specified user (it can’t be empty, if no password is assigned just put any string here)
20	Instead of a password an ssh key file can be used for authentication, the path to the file needs to be specified here
21	Installation type, only `SSH` and `LOCAL` are valid (usually one wants to use `SSH`)
22	Mandatory version of the ESDK App (must be a valid semantic version number)
23	To use SNAPSHOT version specify for to resolve abas specific dependencies within the abas Essentials SDK plugin
24	Specify to use SNAPSHOT version. Every abas partner and customer can use their abas Extranet username here
25	Specify to use SNAPSHOT version. Every abas partner and customer can use their abas Extranet password here

The properties esdkSnapshotURL, nexusUser and nexusPassword can also be entered in a gradle.properties file in $GRADLE_USER_HOME. This is the global configuration file (if it does not exist, just create it). The advantage is that these properties don’t need to be entered in every app’s gradle.properties file.

To apply a Snapshot version add the following buildscript paragraph to your app’s build.gradle:

buildscript {
        repositories {
                mavenLocal()
                mavenCentral()
                maven {
                        credentials {
                                username nexusUser
                                password nexusPassword
                        }
                        url esdkReleaseURL
                }
                maven {
                        credentials {
                                username nexusUser
                                password nexusPassword
                        }
                        url esdkSnapshotURL
                }
        }
        dependencies {
                classpath 'de.abas.esdk:gradlePlugin:0.12.14-SNAPSHOT'
        }
}

Then apply the plugin like this: apply plugin: 'de.abas.esdk'

8.4.2. Full Install

Once the $HOMEDIR/java/lib jars are uploaded successfully to an available Sonatype Nexus Artifact server, the task fullInstall can be run.

This task installs the ESDK App in the abas client specified during setup. The task fullInstall consists of (and therefore executes) the following tasks in the mentioned order:

After running ./gradlew fullInstall your app will be installed in the specified client and ready to use as configured by you.

8.5. Synchronizing the abas Client with Local Changes

Generate and publish your classes.

These tasks are called installAjo, publishClientDirJars and redeployApp.

8.6. Creating the ESDK App JAR

Creates the app JAR which can be installed in another abas Essentials client.

You can find the app JAR under the build directory: <yourAppDirectory>/build/libs/<appName>-<version>-standalone.jar

In abas Tools the build directory is not shown in the project view, use a file browser instead.

8.7. Submitting the ESDK App for abas Marketplace Approval

To submit your ESDK App for publication on the abas Marketplace, you need to create a ZIP archive from your ESDK App Project.

You need to use the packEsdkApp task in the abas-basic task group or run ./gradlew packEsdkApp to create this ZIP archive.

The ZIP archive can then be found in <your-project-dir>/build/esdk-app/.

Make sure your project’s version is updated in the gradle.properties.template file (during development you might configure the version in your gradle.properties file only, however this file is only for local development and will not be packed into the zip file).

Use this step in a Continuous Integration Pipeline to automatically build your project.

9. Support tasks

9.1. Submitting the ESDK App to Receive Support

To submit your ESDK App for support, you need to create a ZIP archive from your ESDK App Project.

You can use the packProjectForSupport task in the abas-support task group or run ./gradlew packProjectForSupport to create the ZIP archive.

The ZIP archive can then be found in <your-project-dir>/build/esdk-app/.

10. Advanced tasks

10.1. Transfer files

10.1.1. installBaseFiles

The Gradle task installBaseFiles tries to copy all the files and subfolders present in the base folder of your resources, into the target abas client directory.

The base folder can contain files at its root, and subfolders and their files.

You can use the base folder to store configuration files, FOPs, and other types of files which do not apply to the other gradle tasks of the ESDK plugin.

Configuration file

You can add a file named .config (case sensitive) at the root of the base and/or in any of the subfolders. In this file, you can specify a list of the files (present in the same folder the .config file is), with special things you would like to do to the files. The options supported are - ro : make the read only file - rw : make the field read & writable by everybody - x : make the file executable - crlf : apply crlf- (remove MS Windows carriage return character from each end of line. ONLY do this on text files, NEVER on binaries) - nooverwrite : this will tell the program to not overwrite your the file if it’s already present in the destination folder. The option values must be separated by a comma.

Example:

config.properties=crlf,ro

This will make the file config.properties read only, and will remove the carriage return character from every line of that file.

No export task

There is no export task for baseFiles, as they are all individual and need to be managed from the project itself.

10.2. Enumerations

10.2.1. exportEnums

Using the exportEnums task it is possible to export existing enumerations from the client specified in the gradle.properties file.

To export an existing enumeration you need to enter the enumeration’s classname in a enums section in the app section of the build.gradle as following:

esdk {
    app {
        ...
        enums = [ "ClientUsage", "AbcPriority" ]
    }
}

We recommend to use a unique classname for your enumeration, this can best be assured by using your App ID as namespace. E.g. for an App ID spare and an enumeration with search word FORMAT you could use SpareFormat as classname.

To export all enumerations specified in the build.gradle file to a file named enums.xml in src/main/resources/enums, run:

./gradlew exportEnums

Advanced enumerations

The task exportEnums only supports enums with enumeration elements of type ValueSet:Identifier (109:1) and ValueSet:ValueSetIdentifier (109:2) by default. Enumerations using other types of enumeration elements can also be exported, but you need to specify the according dependent selection. Configure an enums.json file in src/main/resources/enums with dependent selections as needed. E.g. for a customer dependent selection:

enums.json

{
  "dependents" : [
        {
          "dbnr" : 0,
          "grnr" : 1,
          "headfields" : ["id", "guid", "nummer", "such", "name"],
          "tablefields" : []
        }
  ]
}

For more information on data export and dependent selections refer to exportData.

10.2.2. importEnums

The Gradle task importEnums imports all xml files in the directory src/main/resources/enums of an ESDK App.

Normally only one import file is needed, containing all necessary enumerations.

If an enumeration already exists, it is updated if changes are necessary. To identify an already existing enumeration, every enumeration created by the importEnums task gets a guid, a 38 digit number, uniquely identifying the specific object among all other objects (regardless which database or group).

To import all enumerations in src/main/resources/enums of an ESDK App Project run:

./gradlew importEnums

10.2.3. importEnumsAfterVarreorg

Imports vartab dependent enums after variable table reorganization from xml files to client.

10.2.4. enumReorg

After importing enumerations a reorganization is needed to be able to use the newly imported or updated enumerations.

To execute the enumerations reorganization run:

./gradlew enumReorg

Both namedTypesReorg and enumReorg run the same reorganization command on the client. Therefore, if your project consists of both, enumerations and named types there is no need to run both reorganization tasks. After running both import tasks just run namedTypesReorg.

10.2.5. enumReorgAfterVarreorg

After importing enumerations a reorganization is needed to be able to use the newly imported or updated enumerations.

To execute the enumerations reorganization run:

./gradlew enumReorgAfterVarreorg

10.3. Data

10.3.1. exportData

General Description

One or more json formatted files can be added to src/main/resources/data to describe what data should be exported.

This json file’s name needs to be added to the esdk section of the build.gradle file of an abas Essentials project like this:

esdk {
    app {
        ...
        data = [ "mydata.json" ]
    }
}

A json export data specification needs to contain at least one RootSelection, e.g.

{
  "roots" : [
    {
      "dbnr" : 0,
      "grnr" : 1,
      "headfields" : [ "id", "guid", "such", "name" ],
      "tablefields" : [],
      "criteria" : "id=(167,0,0)"
    }
  ]
}

Running the exportData task will check if there are undefined dependencies such as reference fields. E.g. the following json export data description won’t work with the exportData task as it contains a reference field.

{
  "roots" : [
    {
      "dbnr" : 0,
      "grnr" : 1,
      "headfields" : [ "id", "guid", "such", "name", "staat" ],
      "tablefields" : [],
      "criteria" : "id=(167,0,0)"
    }
  ]
}

./gradlew exportData

 You have to give a DependentSelection for 97:1
 To define it in your 'src/main/resources/enums/enums.json' data export file, add:
         "dependents" : [
                 {
                         "dbnr" : 97
                         "grnr" : 1
                         "headfields" : [ "id", "guid", such", "name" ]
                         "tablefields" : []
                 }
         ]

As indicated above in case of exporting with reference fields a DependentSelection is needed to define what to export from the object the reference field points to, e.g.:

{
  "roots" : [
    {
      "dbnr" : 0,
      "grnr" : 1,
      "headfields" : [ "id", "guid", "such", "name", "staat" ],
      "tablefields" : [],
      "criteria" : "id=(167,0,0)"
    }
  ],
  "dependents" : [
    {
      "dbnr" : 97,
      "grnr" : 1,
      "headfields" : [ "id", "guid", "such", "name" ],
      "tablefields" : []
    }
  ]
}

Object Identification

Each selection, no matter if root or dependent, needs to have at least 'id' and the field used as identifier as head fields and, if any table fields are defined, 'zid' must be one of them.

If the 'guid' field is not filled in the object that is exported, it will be filled with a generated guid in the export file (not in the object that is exported).

Customized Object Identification

By default objects are identified by guid. Every object created by the data import gets a guid and if an object with the same guid in that database and group already exists it will be updated.

Object identification can be customized by using the "identifier" option:

{
  "roots" : [
    {
      "dbnr" : 0,
      "grnr" : 1,
      "identifier" : "such",
      "headfields" : [ "id", "guid", "such", "name", "staat" ],
      "tablefields" : [],
      "criteria" : "id=(167,0,0)"
    }
  ],
  "dependents" : [
    {
      "dbnr" : 97,
      "grnr" : 1,
      "identifier" : "nummer",
      "headfields" : [ "id", "nummer", "guid", "such", "name" ],
      "tablefields" : []
    }
  ]
}

The identifier then shows up as an attribute to each RecordSet tag:

<RecordSet tableNumber="0:1" tableName="Kunde:Kunde" identifier="such" standard="false">

Referencing Standard Objects

Standard objects can be marked as such by adding the "standard" option to the selection:

{
  "roots" : [
    {
      "dbnr" : 88,
      "grnr" : 3,
      "identifier" : "such",
      "headfields" : [ "id", "such", "name",  "aktiv", "kanal", "arb", "laytyp", "kontext", "layname", "genlayout", "genlayname" ],
      "tablefields" : [],
      "criteria" : "such==ISJASOW1AUO"
    }
  ],
  "dependents" : [
    {
      "dbnr" : 65,
      "grnr" : 1,
      "standard" : true,
      "identifier" : "nummer",
      "headfields" : [ "id", "nummer" ],
      "tablefields" : []
    },
    {
      "dbnr" : 88,
      "grnr" : 6,
      "standard" : true,
      "identifier" : "such",
      "headfields" : [ "id", "such" ],
      "tablefields" : []
    }
  ]
}

The standard option then shows up as an attribute to each RecordSet tag:

<RecordSet tableNumber="65:1" tableName="Infosystem:Infosystem" identifier="nummer" standard="true">

References to Objects created during the Installation

For data objects with dependencies on objects created during the installation process, such as Infosystems or additional variable tables, a customized identifier combined with the standard option can be used to fill these fields during data import.

For example a call parameter with an additional variable table as source context and an Infosystem as target context could be configured for export as follows:

{
  "roots" : [
    {
      "dbnr" : 87,
      "grnr" : 9,
      "headfields" : [ "id", "guid", "such", "zielobj", "kontexttyp", "aufrktxt" ],
      "tablefields" : [ "zid", "zielaktion", "zielvar", "aufrwtyp", "aufrwert" ],
      "criteria" : "nummer==100268"
    }
  ],
  "dependents" : [
    {
      "dbnr" : 12,
      "grnr" : 26,
      "identifier" : "vgrtxt14",
      "standard" : true,
      "headfields" : [ "id", "vgrtxt14" ],
      "tablefields" : []
    },
    {
      "dbnr" : 65,
      "grnr" : 1,
      "standard" : true,
      "identifier" : "classname",
      "headfields" : [ "id", "classname" ],
      "tablefields" : []
    }
  ]
}

Configuring the Import Behaviour

There are two additional configuration options. The first one is "importonce". With this option you can define, that objects should only be imported once, and if already present should not be updated. Use the importonce option for the object that should only be imported once.

The second one is "importmode". With this option you can configure how to handle password and readonly fields. You can decide between "tolerant" and "normal" mode where normal is the default. On normal mode password and readonly fields can successfully be exported (an empty field will be exported) but fail on import. On tolerant mode password, empty and readonly fields are ignored during export and import. In this case, a warning which contains the ignored field name is displayed. Use the importmode option for password or readonly fields if you want the export and import to behave different as usual.

{
  "roots" : [
    {
      "dbnr" : 0,
      "grnr" : 1,
      "identifier" : "such",
      "importonce" : true,
      "importmode" : "tolerant",
      "headfields" : [ "id", "guid", "such", "name" ],
      "tablefields" : [],
      "criteria" : "id=(167,0,0)"
    }
  ]
}

The importOnce option then shows up as an attribute in the RecordSet tag:

<RecordSet tableNumber="0:1" tableName="Kunde:Kunde" importOnce="true" importMode="tolerant">

Call Parameter Lists

Currently, it is not possible to fully automatically export call parameter list objects. To later successfully import call parameter lists, they need to be in a <RecordSet> with attribute tableNumber set to "87:21" and the <RecordSet> element needs to contain the <Head> and <Row> elements.

Also, the import needs the reference field aufruf to be present (for standard call parameter lists you can also reference the objects in aufruf as standard objects).

This is an example of a data.xml file containing call parameter list objects that can be imported successfully:

data.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ABASData>
    <RecordSet tableNumber="87:21" tableName="Datenexport:APListe" identifier="nummer" standard="false" importOnce="false" importMode="normal">
        <Record id="(1595,87,0)">
            <Head>
                <Field name="id" abasType="ID87">(1595,87,0)</Field>
                <Field name="nummer" abasType="NK87">60000</Field>
            </Head>
            <Row number="1">
                <Field name="zid" abasType="IDZ87:23">(1596,87,0)</Field>
                <Field name="aufruf" abasType="ID87:9">(1585,87,0)</Field>
                <Field name="aktiv" abasType="B1">1</Field>
            </Row>
            <Row number="2">
                <Field name="zid" abasType="IDZ87:23">(1597,87,0)</Field>
                <Field name="aufruf" abasType="ID87:9">(1588,87,0)</Field>
                <Field name="aktiv" abasType="B1">0</Field>
            </Row>
        </Record>
    </RecordSet>
    <RecordSet tableNumber="87:21" tableName="Datenexport:APListe" identifier="nummer" standard="false" importOnce="false" importMode="normal">
        <Record id="(1585,87,0)">
            <Head>
                <Field name="id" abasType="ID2">(1585,87,0)</Field>
                <Field name="nummer" abasType="NK2">60002</Field>
            </Head>
            <Row number="1">
                <Field name="zid" abasType="IDZ87:23">(1586,87,0)</Field>
                <Field name="aufruf" abasType="ID87:9">(1408,87,0)</Field>
                <Field name="aktiv" abasType="B1">0</Field>
            </Row>
        </Record>
    </RecordSet>
    <RecordSet tableNumber="87:21" tableName="Datenexport:APListe" identifier="nummer" standard="true" importOnce="false" importMode="normal">
        <Record id="(1588,87,0)">
            <Head>
                <Field name="id" abasType="ID2">(1588,87,0)</Field>
                <Field name="nummer" abasType="NK2">60003</Field>
            </Head>
        </Record>
    </RecordSet>
    <RecordSet tableNumber="87:9" tableName="Datenexport:Aufrufparameter" identifier="nummer" standard="true" importOnce="false" importMode="normal">
        <Record id="(1408,87,0)">
            <Head>
                <Field name="id" abasType="ID2">(1408,87,0)</Field>
                <Field name="nummer" abasType="NK2">52686</Field>
            </Head>
        </Record>
    </RecordSet>
</ABASData>

10.3.2. importData

The Gradle task importData tries to import all xml files in the directory src/main/resources/data of an ESDK App.

Each xml import file needs to contain all object data required for the import, this includes all dependent objects (the objects reference fields point to).

Within one xml import file the right import order is determined automatically.

If more than one xml import file is present, the object to import in each file should be independent from one another.

We recommend to use a unique identifier for your data objects, wherever possible. This can best be assured by using your App ID as namespace.

To import all xml files in src/main/resources/data of an ESDK App Project run:

./gradlew importData

Call Parameter Lists

Since currently, existing objects can only be identified using one specific field (rather than a combination of fields or a selection string) only standard call parameter lists with a general context can be uniquely identified.

If you need to update standard call parameter lists with a fixed context, you can currently only identify them using the field id. However, this is not an appropriate unique identifier for an object outside a single abas installation.

Beware, if you still choose to use the field id to identify standard call parameter lists with a fixed context this will only work reliably for one single installation, so using the field id is okay only for ESDK Apps implemented for a specific client, NOT a range of clients or an ESDK App for Marketplace.

10.4. Infosystems

10.4.1. exportIS

The task exportIS exports all infosystems that are referenced in the infosystems property in the esdk closure in your build.gradle file:

esdk {
    app {
        ...
        infosystems = ["IS.OW1.TESTINFO", "IS.OW1.REPLACEMENTCATALOGUE"]
    }
}

The infosystem(s) get exported to the isrein folder in your abas Essentials client using infosys_export.sh. They are then transferred to the IS folder in the source folder src/main/resources of your abas Essentials app project.

10.4.2. installIS

The task installIS installs all infosystems within the IS folder in the source folder src/main/resources of your abas Essentials app project.

The infosystem(s) get transferred to your client and installed using the shell scripts infosysimport.sh - if the infosystem does not exist yet - or infosys_upgrade.sh - if the infosystem does exist and needs to be updated.

The identity number used when exporting will be removed during the import, so the infosystem can be imported even if the identity number is already in use in the target client.

10.5. Keys

10.5.1. exportKeys

Using the exportKeys task it is possible to export existing keys from the client specified in the gradle.properties file.

To export an existing key you need to enter the key’s idno in a keys section in the app section of the build.gradle as following:

esdk {
    app {
        ...
        keys = [ "45678", "45679" ]
    }
}

To export all keys specified in the build.gradle file to a file named keys.xml in src/main/resources/keys run:

./gradlew exportKeys

10.5.2. importKeys

The Gradle task importKeys imports all xml files in the directory src/main/resources/keys of an ESDK App.

Normally only one import file is needed, containing all necessary keys.

If a key already exists, it is updated if changes are necessary. To identify an already existing key, every key created by the importKeys task gets a guid, a 38 digit number uniquely identifying the specific object among all other objects (regardless which database or group).

We recommend to use a unique key name (field schlname/keyName) for your key, this can best be assured by using your App ID as namespace. E.g. for an App ID spare and a key with search word CUSTCONT you could use SpareCustomerContact as key name.

To import all keys in src/main/resources/keys of an ESDK App Project run:

./gradlew importKeys

10.5.3. keyReorg

Reorganizes key table.

10.6. Named types

10.6.1. exportNamedTypes

By using the exportNamedTypes task it is possible to export existing named types from the client specified in the gradle.properties file.

To export an existing named type you need to enter the named types’s classname in the namedTypes section in the app section of the build.gradle as following:

esdk {
    app {
        ...
        namedTypes = [ "InstallationDate", "DisclaimerText" ]
    }
}

We recommend to use a unique classname for your named types, this can best be assured by using your App ID as namespace. E.g. for an App ID spare and an named type with search word INSTDATE you could use SpareInstallationDate as classname.

To export all named types specified in the build.gradle file to a file named namedTypes.xml in src/main/resources/namedTypes, run:

./gradlew exportNamedTypes

10.6.2. importNamedTypes

The Gradle task importNamedTypes imports all xml files in the directory src/main/resources/namedTypes of an ESDK App.

Normally only one import file is needed, containing all necessary named types.

If a named type already exists, it is updated if changes are necessary. To identify an already existing named type, every named type created by the importNamedTypes task gets a guid, a 38 digit number, uniquely identifying the specific object among all other objects (regardless which database or group).

To import all named types in src/main/resources/namedTypes of an ESDK App Project run:

./gradlew importNamedTypes

10.6.3. namedTypesReorg

After importing named types a reorganization is needed to be able to use the newly imported or updated named types.

To execute the named types reorganization run:

./gradlew namedTypesReorg

10.7. Variable tables

10.7.1. General

Importing and exporting variable tables

Field types

Field types which contain special characters (for example colon in reference fields) must be in quotation marks.

Alias fields

Alias fields are only supported if they are alias fields of app fields.
Alias fields of standard fields are currently not supported.

Shell Groups

If you export variables from a shell group, there will be a duplicate entry exported in the .schm file. One for the shell group and one for the origin of the shell. To use the .schm file for import please remove the entry for the shell group from the .schm file manually.

Umlauts / special characters

Umlauts or other special characters for database and group names are currently not supported.

10.7.2. installVartab

In a file with the suffix .schm in src/main/resources/vartab all variable table changes for one variable table can be defined. It is possible to add custom variables, as well as update and delete them.

The .schm file needs to contain all variables of a variable table relevant for the abas Essentials app this .schm file is for. There must be one .schm file for each variable table that needs changes for the ESDK App.

To define which variables are relevant for the app we defined the definition of namespaces. All variables belonging to an ESDK App have to contain two namespace definitions: vendorId and appId

Namespace definition

The vendorId and appId of an ESDK App are defined in the build.gradle of the abas Essentials project. They are stated in the esdk section as following:

build.gradle

esdk {
    app {
        name="myApp"
        vendorId="xx"
        appId="xxxxx"
    }
}

A variable for an ESDK App should have the following format in an abas variable table:

<vendorId>y<appId><variable_name> (1) (2) (3)

1	The `vendorId` follows this formatting convention: `[a-z][a-z0-9]` Note that technically the `vendorId` is not needed. It is just intended to be used for a better visual clustering of "your" fields in the variable table. Currently, always the prefix `xx` is used, regardless what `vendorId` is specified.
2	The `appId` follows this formatting convention: `[a-z0-9]{5}`
3	The actual variable name can have the following formatting: `[a-z0-9]{1,12}`

Adding variables to variable tables

In the .schm file only the actual variable name (<variable_name> above) needs to be inserted.

The .schm file needs to have the following format:

Kunde.schm

database Kunde {
        number 0
        classname Customer
        structure Kunde {
            groupNumber 1
                head {
            field GL40 testhead {
                                label ""
                                heading ""
                                description "Test field head edited"
                                screen EDITABLE
                                showPriority A
                                changePriority A
                        }
                        field "P70:2" testref {
                                label ""
                                heading ""
                                description "Test reference field head"
                                screen EDITABLE
                                showPriority A
                                changePriority A
                        }
                }
        }
}

To define table variables follow this example of an additional database file:

TestDb.schm

database TestDb {
        number 25
        classname TestDb
        structure TestStructure {
                head {
                        field GL30 testhead {
                                label ""
                                heading ""
                                description "Test field head"
                                screen EDITABLE
                                showPriority A
                                changePriority A
                        }
                }
                table {
                        field GL30 testtable {
                                label ""
                                heading ""
                                description "Test field table"
                                screen EDITABLE
                                showPriority A
                                changePriority A
                        }
                }
        }
}

The value for groupNumber is 0 by default and is therefore left out in the second example.

Skip fields, especially buttons, need to have skip in the field definition:

field BU3 skip testbutton {
    label ""
        heading ""
        description "Test Button"
        screen VIEW_EDITABLE
        showPriority A
        changePriority A
}

To add an alias field for an app field use the following syntax:

field GL30 testhead {
        label ""
        heading ""
        description "Test field head"
        screen EDITABLE
        showPriority A
        changePriority A aliases {
                field GL40 testalias {
                        label ""
                        heading ""
                        description "Test field head alias"
                        screen EDITABLE
                        showPriority A
                        changePriority A
                }
        }
}

If the above examples are installed via the installVartab Gradle task, the variables are added to the according variable tables, if they don’t already exist.

Edit existing variables in variable tables

If a variable already exists, it is checked during installVartab whether there are any changes. Only if there are changes, the changes will be applied and result in one or more VVAR records which will then require reorganization via varreorg.

For example, to change the testhead field in variable table TestDb from type GL30 to GL40 run installVartab on the following file:

TestDb.schm

database TestDb {
        number 25
        classname TestDb
        structure TestStructure {
                head {
                        field GL40 testhead {
                                label ""
                                heading ""
                                description "Test field head"
                                screen EDITABLE
                                showPriority A
                                changePriority A
                        }
                }
                table {
                        field GL30 testtable {
                                label ""
                                heading ""
                                description "Test field table"
                                screen EDITABLE
                                showPriority A
                                changePriority A
                        }
                }
        }
}

Delete variables from variable tables

A .schm file needs to contain all variables in that variable table belonging to that abas Essentials app.

Therefore, all variables in the app’s namespace (having the apps Vendor ID and App ID), that are not defined in the .schm file for the variable table, will be deleted.

For example, to delete the field testtable from the variable table TestDb run installVartab on the following file:

TestDb.schm

database TestDb {
        number 25
        classname TestDb
        structure TestStructure {
                head {
                        field GL40 testhead {
                                label ""
                                heading ""
                                description "Test field head"
                                screen EDITABLE
                                showPriority A
                                changePriority A
                        }
                }
        }
}

Renaming variables with installVartab will lead to data loss without certain precautions. If you want to rename your variable in a productive system and don’t want to lose your data, you need to do it in two iterations (two versions):

Add a new variable with the new name and write all data from the old variable to the new variable. At this point, data transfer from one field to the other is a manual step after app installation.
Delete the old variable.

Just replacing the variable will lead to the old variable being deleted and a new variable being created. The deleted variable will lose all data.

Alternatively, if the type is compatible, you can use an alias field and keep the old variable.

10.7.3. exportVartab

The exportVartab task exports all custom variable tables as .schm files, that are defined in the app section of the build.gradle file.

build.gradle

esdk {
    app {
        name = "sparePartsCatalogueApp"
        vendorId = "ag"
        appId = "spare"
        shared = false
        infosystems = [ "IS.OW1.REPLACEMENTCATALOGUE" ]
        tables = [ "Replacement" ] (1)
        data = [ "data.json" ]
    }
}

1	Add all variable table names to the array named tables. For multiple variable tables just add Strings separated by comma, e.g. `[ "Replacement", "Teil" ]`

The exported .schm files can be found in src/main/resources/vartab in a directory named as the class name of the variable table that was exported.

10.7.4. varreorg

The varrorg task checks if variable tables prepared for variable table reorganization exist (VVAR objects). If VVAR objects exist a variable table reorganization is executed, else an appropriate message is displayed and variable table reorganization is skipped.

10.8. Screens

10.8.1. exportScreens

The task exportScreens exports screens from the abas Essentials client into the ESDK App Project.

Additional Database Screens and App Tabs in Standard Database Screens

To specify what screens to export add a screens attribute to your build.gradle’s app section and specify Database and Group classname of the table the screen is for as well as the priorities you want to export:

build.gradle

esdk {
    app {
        screens=["Customer:Customer": ["A", "D"], "TestDb:TestStructure": ["A"]]
    }
}

For customized standard database screens you can also specify the screen number instead of Database and Group classnames:

build.gradle

esdk {
        app {
                screens=["77": ["A"]]
        }
}

For customized standard database screens only the app tab(s) and menu buttons of your app will be exported.

Add your app tab(s) to the first tab container in the main screen or the first tab container in the line zoom, depending on whether you want to add head or table fields.

Note: Only menu buttons containing your App ID in their field name will be exported.

Note: You cannot add tabs to inner tab pages.

To identify your tab set the key attribute to <classname>$<appid>_<count> e.g.: product$train_0 If you are using abas Tools to add a tab to your screen the key attribute will be generated as <classname>$<count> e.g. product$0, so you just have to add <appid>_ there.

If no tab container exists in the main screen or line zoom, add a tab container around the outermost layout in the screen. Put all existing content in the first tab and add your app tab with your fields after that. When installing, a tab container with a general tab will be added automatically around the outermost layout and your app tab will be added after the general tab.

If no line zoom exists, add a line zoom and an app tab in that line zoom. When installing, a line zoom will be created and your app tab will be added to the tab container in that line zoom.

For customized additional database screens the complete screen is exported.

If there is no customized screen for your database or no key identifier is set for your app for standard databases the export will fail.

Overriding Standard Database Screens

If you want to override standard screens completely, you can use the advancedScreens attribute in the app section of your build.gradle file. Specify standard screens that should be overridden completely as follows:

build.gradle

esdk {
        app {
                advancedScreens=["77": ["A"], "Customer:Customer": ["A", "D"]]
        }
}

Using the advancedScreens configuration might lead to the loss of other changes in the previously already customized screen (such as changes made by other apps or the customer himself).

The advancedScreens configuration is not allowed for ESDK App meant to be published to the abas Marketplace and will lead to rejection.

10.8.2. installScreens

The task installScreens installs all customized screens that are part of the ESDK App.

Additional Database Screens and App Tabs in Standard Database Screens

All screens to import must be present in src/main/resources/dbscreens in the .screen format.

Overriding Standard Database Screens

All advanced screens to import must be present in src/main/resources/advancedDbScreens in the .screen format.

The advancedScreens configuration is not allowed for ESDK App meant to be published to the abas Marketplace and will lead to rejection.

10.9. Language support

10.9.1. exportDictionaries

The Gradle task exportDictionaries exports all screen texts for all infosystems and variable tables in the ESDK App Project. The screen texts will be exported into msg.ma files per infosystem/variable table in either src/main/resources/IS or src/main/resources/vartab.

To export all screen texts into msg.ma files run:

./gradlew exportDictionaries

The exported msg.ma files will include all languages specified in the app section of the build.gradle of the ESDK App Project. All texts that are already available in one of the specified languages will be already included.

You can add all missing texts in all specified languages to the msg.ma files manually. These can then be imported using the importDictionaries task.

10.9.2. importDictionaries

The Gradle task importDictionaries imports all msg.ma files in the ESDK App Project into the dictionary of the abas Essentials client.

The msg.ma files containing translations are either found in src/main/resources/IS or src/main/resources/vartab as they either belong to an infosystem or to a variable table.

The languages to import must be specified in the app section of the build.gradle of the ESDK App Project as following:

esdk {
        app {
                ...
                languages = "EA" (1)
        }
}

1	Specify all languages as found in the Configuration data object in the abas Essentials client e.g. `E` for English and `A` for American English.

To import all dictionaries for all specified languages run:

./gradlew importDictionaries

Only texts that are not already translated in the abas Essentials client the task is run for will be imported. Only languages that are installed in the abas Essentials client will be considered.

10.10. Working directories

10.10.1. createWorkdirs

The Gradle task createWorkdirs creates working directories if missing and activates inactive ones needed by the ESDK App.

All needed working directories can be defined in the build.gradle:

esdk {
    app {
        ...
        workdirs = [ "ow1", "owdir" ]
    }
}

After installing, manual configuration of these working directories for additional users might be necessary.

10.11. Install AJO

10.11.1. installAjo

Runs ajo_install.sh on the client only for components in the app project.

10.12. Change fop.txt

10.12.1. installFopTxt

The installFopTxt task adds all lines to fop.txt specified in the file fop.json.

The file has to be added to your project here: <your project>/src/main/resources/fop.json. In this file, you can specify any entries you need to add to the fop.txt using the following json format:

fop.json Example for a Standard Database using AJO identifiers

[
  {
    "databaseName" : "(Sales)",
    "groupName" : "(PackingSlip)",
    "editorMode" : "neu",
    "event" : "maskende",
    "key" : "*",
    "field" : "*",
    "headOrTable" : "K",
    "isContinue" : "[C]",
    "handler" : "java:de.abas.example.YourClass@appid"
  }
]

Instead of specifying database and group you can also use the screen number. This is not recommended for additional tables, since additional tables are installed in the next free additional database. So the screen number changes depending on the client the app is installed in.

fop.json Example for a Standard Database using the screen number

[
  {
    "screenNumber": "35",
    "editorMode" : "*",
    "event" : "maskpruef",
    "key" : "*",
    "field" : "*",
    "headOrTable" : "K",
    "isContinue" : "[C]",
    "handler" : "java:de.abas.example.YourClass@appid"
  }
]

fop.json Example for an Additional Table

[
  {
    "databaseName" : "GermanDatabaseName",
    "groupName" : "GermanGroupName",
    "editorMode" : "neu",
    "event" : "maskende",
    "key" : "*",
    "field" : "*",
    "headOrTable" : "K",
    "isContinue" : "[C]",
    "handler" : "java:de.abas.example.YourClass@appid"
  }
]

If you want to add a fop.txt entry for every database and/or group, you can leave databaseName and/or groupName empty.

The fop.txt is extended by the apps entries. A comment brace is factored around all fop.txt lines belonging to one app, to identify an app’s scope of lines and be able to add new lines for that app, update existing lines and delete old lines automatically.

WARNING: fop.txt lines for an app that was installed with an ESDK version before 0.4.11 will not get updated or deleted automatically. These lines either have to be maintained manually or manually moved inside the comment brace for the app when installing the app with this or a newer version. The latter has only to be done once.

10.13. Configure logging

10.13.1. installLog

This tasks adds a logging configuration to the abas Essentials client’s logging.custom.properties file in $MANDANTDIR/java/log/config. All your ESDK Apps log output of the defined log level can then be found in the file specified in the logging.custom.properties file in your ESDK App Project.

Updating the logging.custom.properties file is currently not supported. If you change lines and rerun installLog the changed lines will be imported but not replaced. Therefore changes to your log configuration have to be done manually, after installLog has run.

10.14. Change mandantdir.env

10.15. installMandantdirEnv

The task installMandantdirEnv inserts all properties of the mandantdir.env file in the source folder src/main/resources of your abas Essentials app project to the mandantdir.env file in your development client. The custom properties will be inserted after the BEGIN section of your client.

Custom properties will be inserted if the properties key does not exist yet. To update a value of an existing properties key, you need to manually delete that key from the mandantdir.env file of your client, prior to running installMandantdirEnv.

10.16. Publish JARs

10.16.1. publishClientDirJars

This task publishes all artifacts in $MANDANTDIR/abasbase/java/lib as Snapshots into the defined Sonatype Nexus repository.

10.16.2. publishHomeDirJars

This task publishes all artifacts in $HOMEDIR/java/lib as Releases into the defined Sonatype Nexus repository.

10.16.3. removeNexusFromClient

Removes Nexus from client dir (for major updates).

10.17. Redeploy JFOP server app

10.17.1. redeployApp

Redeploys the JFOP server App.

10.18. Print project information

10.18.1. printVersion

The printVersion task prints the current version of your project. The version of your project can be stored in either one of the following files:

settings.gradle
gradle.properties
build.gradle

Regardless of which of these files you use to set the version, the printVersion task will print it to the console.

10.18.2. printDockerTags

The task printDockerTags will print all tags of the Docker image abas/test in sdp.registry.abas.sh that are applicable for the defined abas Essentials version ranges of your project.

In order to use these Docker images you need to have access to the sdp.registry.abas.sh Docker Registry.

11. Documentation tasks

11.1. esdkAppDocumentation

Adding documentation for your ESDK App.

11.1.1. Writing ESDK App documentation

To add documentation for your ESDK App create a documentation folder in your ESDK App Project directory. Within the documentation folder add a source folder src/main/asciidoc and create a file index.adoc within that source folder.

Add the following structure to the index.adoc file:

index.adoc

:docinfo:
= <name of your app>
Documentation
:nofooter:

This document describes the <name of your app> app.

== About

<name of your app> +
(C) <name of your company>

https://your-website.com/

You write your ESDK App's documentation by adding .adoc files to the documentation/src/main/asciidoc folder and referencing them in your index.adoc file.

For example, add a file subpage.adoc with the following content:

subpage.adoc

== <Headline of your subpage>
This is a subpage about subcontent

Content goes here!

You can include this file in your index.adoc by adding include::subpage.adoc[] before == About:

index.adoc

...
This document describes the <name of your app> app.

include::subpage.adoc[]

== About
...

The formatting is provided by Asciidoctor, refer to the Asciidoctor documentation for help on how to format your documentation with headings, lists, images, etc.

11.1.2. Rendering and viewing the ESDK App documentation

To render the documentation run ./gradlew esdkAppDocumentation or execute the esdkAppDocumentation task from the documentation task group in your IDE. Afterwards you can view the documentation by opening <you-project-dir>/build/asciidoc/html5/index.html in a browser of your choice.

11.2. packEsdkAppDocumentation

You can create a ZIP archive from your rendered documentation by running ./gradlew packEsdkAppDocumentation or executing the packEsdkAppDocumentation task from the documentation task group in your IDE.

The ZIP archive can then be found in <you-project-dir>/build/esdk-app/.

12. Verification tasks

12.1. verify

Runs all tests.

12.2. integTestTask

Runs integration tests.

You may use the ESDK testing utilities to setup integration tests easily.

12.3. addJacocoToAppClasspath

Configures JFOP server for Jacoco by adding the Jacoco agent to the ESDK App's classpath and configuring a JFOP server instance for the user who executes the task.

12.4. instrumentJfopServer

Redeploys the ESDK App in the JFOP server and depends on task addJacocoToAppClasspath.

12.5. retrieveServerSideCoverage

Dumps the code coverage statistics into a coverage-serverside.exec file in $MANDANTDIR/esdk/test-infrastructure/reports and copies it into the local ESDK App Project.

12.6. calculateCodeCoverage

Considers all .exec files in build/jacoco to calculate the code coverage and generates a HTML report. It depends on retrieveServerSideCoverage.

12.7. codeCoverageVerification

Verifies that the code coverage of all tests meets abas' requirements for ESDK Apps to go on the abas Marketplace.

13. Other tasks

13.1. esdkVersion

Displays the version of the ESDK plugin.

13.2. prepareVartab

Prepares the vartab import file for installation.

13.3. createApp

Creates the JFOP server app.

13.4. installApp

Installs the JFOP server App on client.

13.5. processAppResources

Copies all resources files to build/abas/resources.

14. Compatible Essentials Versions

To check for an abas version number, you need to enter a version range in the essentialsVersions section in the app section of the build.gradle as following:

esdk {
    app {
        ...
        essentialsVersions = ["2017r1n00-2017r4n17"]
    }
}

Multiple version ranges are supported, e.g.: essentialsVersions = ["2016r4n13-2016r4n15", "2017r1n00-2017r4n17"]

To create a new standalone app JAR using the createAppJar task you have to specify at least one abas Essentials version range. Otherwise the following error message will be displayed:

abas Essentials version compatibility check failed: no compatible abas Essentials versions specified

Installing existing standalone app JARs without abas Essentials version compatibility ranges are supported but will lead to the following warning:

abas Essentials version compatibility check failed: no 'essentialsVersions' compatibility specified.

15. Code Coverage Reports and Verification

This chapter describes how to calculate and verify the code coverage, meaning the percentage of production code that is covered by tests.

15.1. Code Coverage Reports

To calculate the overall code coverage for your ESDK App you need to execute the Gradle task calculateCodeCoverage.

All tests will be executed and the code coverage will be calculated. A HTML code coverage report is generated and can be viewed by opening build/reports/jacoco/html/calculateCodeCoverage/html/index.html.

15.2. Code Coverage Verification

To verify that the code coverage meets the requirements set by abas for ESDK Apps to go on the abas Marketplace, execute the Gradle task codeCoverageVerification.

The task passes if all requirements are met. If one or more requirements are not met it will fail and display a message stating what requirements were not met.

16. ESDK APIs and Libraries

To make common tasks less time-consuming and error-prone, we provide a set of some small APIs. All of them are available in the Maven repository https://registry.abas.sh/artifactory/abas.maven-public/.

Library Name Purpose How to use it Javadoc

client-api

de.abas.esdk:client-api:0.0.12:all

License checking, reading app properties

See Use the esdk-client-api for an example

Client API Javadoc

test-utils

de.abas.esdk.test.util:esdk-test-utils:0.0.2

Integration testing using the app project’s gradle.properties

See integTestTask and a newly generated project by the ESDK Developer Portal's project initializer

Testing Utilities Javadoc

versionchecker

de.abas.esdk.versionchecker:versionchecker:0.10.19

Reading abas Essentials versions, comparing them or check version matches

The Javadoc provides some examples

Version Checker Javadoc

17. ESDK App Installer

Using the ESDK App Installer to install ESDK Apps

17.1. Preface

The ESDK App Installer is an application able to install an ESDK App fully automated. The ESDK App needs to be available as a standalone JAR file. This JAR file is created by executing the Gradle task createAppJar after the app was previously installed using the fullInstall task.

17.2. Usage

The current version of the ESDK App Installer can be downloaded here as a ZIP file.

Choose the current version of the ESDK App Installer and download it.
Copy the downloaded ZIP file into the client directory of the abas Essentials client you want your app installed on.
Unzip the file.
Change into the unzipped folder.
Change into the bin folder.

The ESDK App Installer is ready to be used to install an ESDK App in this abas Essentials client.

usage: ./esdk-app-installer [-a <artifact>] [--eapps-only] [-f] [-h] [-l <arg>] [--maven-repo-password <maven-repo-password>] [--maven-repo-user <maven-repo-user>] [--nexus-password <nexus-password>]
       [--nexus-user <nexus-user>] [-p <edp-password>] [-q] [-s] [-u <edp-user>] [-v] [--version] [--yes-i-have-a-backup]
    -a,--artifact <artifact>                        Archive path or link to nexus artifact
       --eapps-only                                 Only installs the essentialsApps infosystem. All other installation actions will be ignored.
    -f,--force                                      Forces installation of given ESDK App, even if the same or a higher version is already installed.
    -h,--help                                       show usage
    -l,--languages <arg>                            App installation languages (e.g. English and French: EF)
       --maven-repo-password <maven-repo-password>  maven repository password
       --maven-repo-user <maven-repo-user>          maven repository user
       --nexus-password <nexus-password>            Deprecated. Use 'maven-repo-password' instead.
       --nexus-user <nexus-user>                    Deprecated. Use 'maven-repo-user' instead.
    -p,--edp-password <edp-password>                EDP password
    -q,--quiet                                      quiet log output
    -s,--skip                                       do not install essentialsApps infosystem
    -u,--edp-user <edp-user>                        EDP user
    -v,--verbose                                    verbose log output
       --version                                    display version of ESDK App Installer
       --yes-i-have-a-backup                        Backup of the ERP System was created
For more information visit: https://documentation.abas.cloud/en/esdk/#esdk-app-installer

The ESDK App Installer requires an Internet connection to install ESDK Apps.

To install an app that is available on an artifact server execute:

./esdk-app-installer -a <link to the app on an artifact server> [-u abasuser] -p abaspwd --maven-repo-user mavenRepoUser --maven-repo-password mavenRepopwd

e.g.:

./esdk-app-installer -a https://registry.abas.sh/repository/abas.esdk.snapshots/de/abas/esdk/app/abasag-sparePartsCatalogue/0.4-SNAPSHOT/abasag-sparePartsCatalogue-0.4-20170520.095006-1.jar -p sy --maven-repo-user myuser --maven-repo-password C0mpl1c4t3d

To install an app that is available locally execute:

./esdk-app-installer -a <path to local app JAR file> [-u abasuser] -p abaspwd

e.g.:

./esdk-app-installer -a /abas/erp/sparePartCatalogueApp-standalone-app.jar -p sy

All non-optional arguments except for the path to the local app JAR file or link to the app on an artifact repository can also be supplied interactively. Executing

./esdk-app-installer -a <path to local app JAR/link to the app on an artifact server>

e.g.

./esdk-app-installer -a https://registry.abas.sh/artifactory/abas.esdk.snapshots/de/abas/esdk/app/abasag-sparePartsCatalogue/0.4-SNAPSHOT/abasag-sparePartsCatalogue-0.4-20170520.095006-1.jar

./esdk-app-installer -a /abas/erp/sparePartCatalogueApp-standalone-app.jar

will prompt you for all other necessary arguments. All password inputs will be hidden.

The argument abasuser is optional, if not supplied it will be read from the environment.

To install the app in specific languages, use the -l / --languages argument with the language(s) to install:

./esdk-app-installer -a <path to local app JAR/link to app on an artifact server> -l <language(s)>

e.g.

./esdk-app-installer -a https://registry.abas.sh/artifactory/abas.esdk.snapshots/de/abas/esdk/app/abasag-sparePartsCatalogue/0.4-SNAPSHOT/abasag-sparePartsCatalogue-0.4-20170520.095006-1.jar -l E

./esdk-app-installer -a /abas/erp/sparePartCatalogueApp-standalone-app.jar -l E

Only languages contained in the app JAR will have texts, other languages will have no effect.

17.3. Use with abas Essentials as a Docker container

Download the installer to your local machine Usage
Copy the installer into the abas Essentials container
docker cp <path to downloaded installer>/installer.0.12.14.zip erp:/abas/erp
Create your app JAR Preface
Copy the app JAR into the abas Essentials container
docker cp <path to you App JAR>/<yourappname>.<version>-standalone.jar erp:/abas/erp
Run bash with the user erp inside the abas Essentials container
docker exec -u erp -it erp bash
Set the client environment
cd /abas/erp && eval $(sh denv.sh)
Unzip the installer
unzip installer.0.12.14.zip
run the installer with the required options <Usage>
esdk-app-installer/bin/esdk-app-installer -a <yourappname>.<version>-standalone.jar

To exit the container type exit.

Alternatively download the installer by executing the following command in your Docker container:

wget -qO- 'https://bintray.com/abas/abas-essentials-sdk/download_file?file_path=de%2Fabas%2Fesdk%2Finstaller%2F0.12.14%2Finstaller-0.12.14.zip' -O app-installer-tmp.zip && unzip -q app-installer-tmp.zip && rm -rf app-installer-tmp.zip

17.4. Logging

The ESDK App Installer logs to the console and to a file. The log file can be found in $MANDANTDIR/esdk-installations/<appId>/<version> and is named installation.log. If the same version of an ESDK App is installed again, the previously existing installation.log is kept. It gets an index that is incremented each time a new installation.log is created in the same directory.

Additionally, the EDP communication is logged to edp.log within $MANDANTDIR/esdk-installations/<appId>/<version>.

For an ESDK App with App ID train and version 0.0.1 that was installed three times the log directory structure and files would look like this:

ls $MANDANTDIR/esdk-installations/train/0.0.1/
edp.log  installation-2.log  installation-1.log  installation.log

The default log level is INFO and informs about each step the installer is executing, e.g.:

Checking preconditions for train 0.12.4
Starting app installation for train 0.12.4
Installing JFOP server app trainingApp
Installing enumerations [/tmp/esdk4272199647961008308app/enums/enums.xml]
Running enum reorg
Installing vartabs CustomTestDb.schm
Running varreorg
Installing enumerations [/tmp/esdk4272199647961008308app/enumsAfterVarreorg/enum.xml]
Running enum reorg
Installing database screens 0_a.screen
Installing fop.txt changes
Installing logging.custom.properties changes
Installing files from base
Installing infosystems [[TESTINFO]]
Regenerating AJO classes for [[TESTINFO]] and enumerations
Installing data objects from [/tmp/esdk4272199647961008308app/data/data.xml]
Redeploying JFOP server app trainingApp
Installing keys [/tmp/esdk4272199647961008308app/keys/keys.xml]
Running key reorg
Installation of train 0.12.4 successfully completed

To only display warning and error messages, the installer can be run with the quiet option -q / --quiet: ./esdk-app-installer -a <path to local app JAR/link to app on an artifact server> -q

To get more detailed log messages, the installer can be run with the verbose option -v / --verbose: ./esdk-app-installer -a <path to local app JAR/link to app on an artifact server> -v

17.5. Infosystem ESSENTIALSAPPS

The Infosystem ESSENTIALSAPPS gives an overview of all installed apps in the abas Essentials client. It is an app itself and gets installed whenever the ESDK App Installer is used.

If installed, the Infosystem ESSENTIALSAPPS is used to determine, whether an ESDK App is already installed in the same or a higher version. By default, if the same or a higher version of the ESDK App is already installed, the installation is skipped.

The installation can be forced with the -f/--force option.

The installation of the infosystem ESSENTIALSAPPS app can be skipped with the -s/--skip option of the ESDK App Installer.

./esdk-app-installer -a <path to local app JAR/link to app on artifact server> -s

e.g.

./esdk-app-installer -a https://registry.abas.sh/artifactory/abas.esdk.snapshots/de/abas/esdk/app/abasag-sparePartsCatalogue/0.4-SNAPSHOT/abasag-sparePartsCatalogue-0.4-20170520.095006-1.jar -s

./esdk-app-installer -a /abas/erp/sparePartCatalogueApp-standalone-app.jar -s

18. Demo Project trainingApp

The demo project trainingApp demonstrates all ESDK features using the latest ESDK version (this can also be a SNAPSHOT version).

The trainingApp is for presenting features and therefore not all components make sense together as they are only intended to show how to use the specific ESDK features.

The trainingApp can be found on Github.

19. Infosystem ESSENTIALSAPPS

Use the infosystem ESSENTIALSAPPS to get information about all installed apps on your abas Essentials installation.

The infosystem gives you information about:

Error during installation (icon): Indicates if the current installation was successful
App ID
App Version: The version of the app which is currently installed
Installation date
Installation duration
Licensing (icon): Indicates whether the app has a valid license (green), does not use licensing (blue), is not licensed (red), or the licensing server is not running (grey).
abas Essentials version compatibility: The abas Essentials version ranges the app is compatible to
abas Essentials version compatibility (icon): Shows if the app is compatible to the actual abas Essentials version
Components (Button): Lists all components belonging to the app
Installation Log File (Button): Shows the installation log file of the current version
Installation Remarks: Shows error messages and information about the installation process

19.1. Use SNAPSHOT versions for building

SNAPSHOT versions are no official releases and might be unstable.

We recommend to only use SNAPSHOT versions if we asked you to do so because we added a feature you requested. You might experience unexpected behavior due to it not being a stable release.

If you want to use a SNAPSHOT version configure your build.gradle file as follows: Delete the following line, which applies a release version of the plugin:

id "de.abas.esdk" version "0.12.14"

Enter the following lines at the very beginning of your build.gradle file:

buildscript {
        repositories {
                mavenLocal()
                mavenCentral()
                maven {
                        credentials {
                                username nexusUser
                                password nexusPassword
                        }
                        url esdkReleaseURL
                }
                maven {
                        credentials {
                                username nexusUser
                                password nexusPassword
                        }
                        url esdkSnapshotURL
                }
        }
        dependencies {
                classpath 'de.abas.esdk:gradlePlugin:0.12.14-SNAPSHOT'
        }
}

Then add the following line after the plugins { … } block:

apply plugin: 'de.abas.esdk'

You also need to have the nexusUser and nexusPassword properties set in your gradle.properties file. To do so, just add them at the bottom of the gradle.properties file in your project:

nexusUser=yourUser
nexusPassword=C0mpl1c4t3d!

The username and password will be provided by us if we ask you to test a SNAPSHOT version or upon your demand.

20. Submitting your ESDK App

20.1. Submitting your ESDK App for abas Marketplace Approval

You can submit your ESDK App for abas Marketplace Approval by raising a request for App Submittal.

Your ESDK App has to meet the following requirements:

Group Name Requirement

Formal Requirements

Version

Valid semantic version number, which is not a SNAPSHOT version (ending in -SNAPSHOT) and defined in gradle.properties.template.

Gradle Wrapper

A Gradle Wrapper compatible with the ESDK Gradle Plugin must be available.

App ID

The App ID must be valid and registered via the ESDK Developer Portal. Refer to Register your App ID.

Size

The packed ESDK App ZIP file cannot exceed 50MB.

Programming Language

Any JVM-based programming language that can be tested automatically and is runnable in the JFOP server.

Documentation

Documentation must be available for the ESDK App in Asciidoc format. Refer to Writing ESDK App documentation.

abas ERP Version

abas ERP Versions, provided for this app, must still be supported by abas.

Static Code Metrics

Cyclomatic Complexity

Must be less than 21.

Maximum Method Length

Max LOC/functions must be less than 31.

Dynamic Code Metrics

Tests

Test types are not restricted. You are free to use Unit Tests, Integration Tests and/or End-to-End Tests. All tests must pass.

Test Coverage

Test Coverage must be greater than or equal to 80%.

Test Execution

Test execution cannot exceed 1 hour.

You can check if your ESDK App meets the code metrics by executing the codeCoverageVerification task.

We reserve the right to do manual spot checks on submitted ESDK Apps.

20.2. Submitting your ESDK App for Support

You have the possibility to report any requests for missing features, or get help on any issues you are experiencing with abas Essentials SDK by raising a request for support. You will contact the ESDK development team directly and we will get back to you as soon as possible.

Glossary

This glossary is meant to clarify the naming of the components that relate to abas Essentials SDK.

abas Essentials SDK

The Software Development Kit (SDK) for customizing abas Essentials (also known as abas ERP).

App ID

Short for ESDK App ID.

ESDK

Short for abas Essentials SDK. Please use only upper case letters, not eSDK.

ESDK App

The result of an ESDK App Project. The finished and automatically installable customizing for abas Essentials developed using abas Essentials SDK.

Please do not use any other names, not ESDKs, ESDK package, etc.

ESDK App ID

The ESDK App's unique name space.

ESDK App Installer

The installation tool to install an ESDK App in an abas Essentials client.

ESDK App Project

The project structure to develop an ESDK App.

About

Version: 0.12.14

https://abas-essentials-sdk.com/