Pre-development setup

Java 8 installation

Linux installation

OpenJDK installation guide: https://openjdk.java.net/install/.

You can find Oracle's Java installation here: https://www.digitalocean.com/community/tutorials/how-to-install-java-with-apt-on-ubuntu-18-04. (In the installation guide is selection of more Linux distrubtions)

Windows installation

Original windows java installation guide: https://www.java.com/en/download/help/windows_manual_download.xml#download

Installation of databases

Linux installation

MongoDB 4.2

Installation of MongoDB v 4.2 is complexly described on their official website: https://docs.mongodb.com/v4.2/tutorial/install-mongodb-on-ubuntu/.

You can also download a software package of MongoDB v 4.2 on their official website: https://docs.mongodb.com/v4.2/administration/production-notes/#prod-notes-supported-platforms-arm64.

Redis 4+

If you want to see the whole original installation guide, please visit linode.com.

In the first steps, Redis PPA repository is added and the local package database is updated.

In the second step, the Redis server is installed.

Step three is about Redis configuration.

In the last step auto-start of Redis service with the server is set to settings.

MySQL 5.7

Installation of MySQL 5.7 is complexly described on their official website: https://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/. 

For installation automation, is necessary to set the default login for access to databases. Please replace <heslo> by root password of your choice (e.g. root)

In step number two installation of MySQL is realized.

Next step is all about the creation of a new MySQL user. In our case, we create user netgrif_nae (please replace <heslo> by root password).

Neo4j

If you want to see the whole original installation guide, please visit: https://neo4j.com/docs/operations-manual/current/installation/linux/debian/#debian-add-repository.

In the beginning, you need to import the key for key orchestration. Afterwards, the file list for Neo4j is created.

In step two update local database of packages and install Neo4j.

Step three enables and starts Neo4j service.

The last step takes place after the start of Neo4j service. Change of neo4juser is realized by curl command.

Elasticsearch 6.6+

For the whole original installation guide, please visit: https://www.elastic.co/downloads/elasticsearch

Windows installation

For almost all services is necessary to install the Windows Subsystem for Linux. Please follow this tutorial to install WSL: https://docs.microsoft.com/en-us/windows/wsl/install-win10.

MongoDB 4.2

Installation of MongoDB v 4.2 is complexly described on their official website  https://docs.mongodb.com/v4.2/tutorial/install-mongodb-on-windows/.

Redis 4+

Follow the instructions in section Linux installation but in WSL.

MySQL 5.7

Follow the instructions in section Linux installation but in WSL.

Neo4j

Follow the instructions in section Linux installation but in WSL.

Elasticsearch 6.6+

Follow the instructions in section Linux installation but in WSL.

Nexus setup (NAE Backend)

1. Open a new or existing Maven project.

2. Open locally Maven settings

   1. Linux: ~/.m2/

   2. Windows: C:\Users\<local user>\.m2\

3. Copy text below into file settings.xml

   <?xml version="1.0" encoding="UTF-8"?> <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"> <servers> <server> <id>netgrif-nexus-releases</id> <username>[!your username!]</username> <password>[!your password!]</password> </server> </servers> <mirrors> <mirror> <id>netgrif-nexus-releases</id> <name>netgrif-nexus-releases</name> <url>https://nexus.netgrif.com/repository/maven-public/</url> <mirrorOf>netgrif-nexus-releases</mirrorOf> </mirror> </mirrors> </settings>

4. Save settings.xml file and return back to Maven project

5. Copy text bellow into pom.xml file in Maven project

   <repositories> <repository> <id>netgrif-nexus-releases</id> <url>https://nexus.netgrif.com/repository/maven-public/</url> </repository> </repositories>

6. After pom.xml is updated, please reimport maven project

7. To check if everything went ok, please run mvn clean package.

If you want to encrypt your password (recommended): https://maven.apache.org/guides/mini/guide-encryption.html

NPM setup (NAE Frontend)

1. Open new or existing npm project

2. If npm project already contains folder node_modules, delete this folder

3. Generate Bash64 token from your name and password for Nexus OSS. You can generate for example by command echo -n 'username: password' | openssl base64

4. Into your root project, right next to your package.json file create .npmrc file with text. Text is right bellow

   registry= https://nexus.netgrif.com/repository/npm-group/ email=<!!> always-auth=true _auth=Generated Bash64 token

5. Now you can use command npm install in your project. All dependencies should be now downloaded right from Nexus Server

New project setup

JAR/ZIP setup

Repository setup

First steps

Backend

Project structure

Cloned repository or unpacked project of the backend is Netgrif Demo Application (NDA). Backend NDA is a Spring Boot based application project.

Structure of NDA Spring Boot project is:

• .git

  • files and folders generated by Git

• .idea

  • files and folders generated by your idea

• log

  • generated logs

• src

  • main

    • groovy

      • 'package name'

        • DemoRunnerController.groovy

        • DemoActionDelegate.groovy

    • java

      • ‘package name’

        • NetgrifDemoApp

    • resources

      • petriNets

        • test_model.xml

      • static

      • application.properties

      • application-dev.properties

      • logback.xml

• storage

  • files generated by NDA while an application is active

• target

  • generated classes and sources by NDA project

• pom.xml

  • Spring Boot configuration file and dependency loader

Good practice

• All XML models that you have created or you are going to create in Netgrif Builder (NAB) has to be stored in src → main → resources → petriNets.

• Right after your project is initialized, create a folder startup in src → main → groovy → 'package name'

  • in this folder, you can create new Groovy classes that can be initialized in DemoRunnerController

  • example of AbstractOrderedCommandLineRunner class is PetriNetsImportRunner that can be created in folder startup

    package demo.startup import com.netgrif.workflow.auth.domain.LoggedUser import com.netgrif.workflow.auth.service.UserService import com.netgrif.workflow.petrinet.service.interfaces.IPetriNetService import com.netgrif.workflow.startup.AbstractOrderedCommandLineRunner import com.netgrif.workflow.startup.ImportHelper import com.netgrif.workflow.startup.SuperCreator import org.slf4j.Logger import org.slf4j.LoggerFactory import org.springframework.beans.factory.annotation.Autowired import org.springframework.stereotype.Component @Component class PetriNetsImportRunner extends AbstractOrderedCommandLineRunner { public static final Logger log = LoggerFactory.getLogger(PetriNetsImportRunner) static class SSA { public static final String NET_NAME = "SSA" public static final String NET_FILE = "ssa.xml" public static final String NET_IDENTIFIER = "SSA" public static final String NET_INITIALS = "SSA" } @Autowired private ImportHelper importHelper @Autowired private SuperCreator superCreator @Autowired private UserService userService @Autowired private IPetriNetService petriNetService @Override void run(String... strings) throws Exception { log.info("Begining to import PetriNets") def ssa = ImportUtils.getOrImport(SSA.NET_FILE, SSA.NET_IDENTIFIER, SSA.NET_NAME, SSA.NET_INITIALS, petriNetService, importHelper, userService.getLoggedOrSystem().transformToLoggedUser()) assert ssa != null //superCreator.setAllProcessRoles() log.info("PetriNets imported succesfully!") } }

  • if you want to use PetriNetsImportRunner, you also need to create Groovy class ImportUtils, which offers functions to create new Petri nets

    package demo.startup import com.netgrif.workflow.auth.domain.LoggedUser import com.netgrif.workflow.petrinet.domain.PetriNet import com.netgrif.workflow.petrinet.service.interfaces.IPetriNetService import com.netgrif.workflow.startup.ImportHelper import org.apache.poi.ss.usermodel.* import org.apache.poi.ss.util.CellReference import java.time.LocalDate import java.time.format.DateTimeFormatter class ImportUtils { static PetriNet getOrImport(String file, String identifier, String name, String initials, IPetriNetService petriNetService, ImportHelper helper, LoggedUser user) { def net = petriNetService.getNewestVersionByIdentifier(identifier) if (!net) net = helper.createNet(file, "major", user).get() return net } static LocalDate parseDate(String string) { return LocalDate.parse(string.trim(), DateTimeFormatter.ofPattern("d.M.yyyy")) } static Double parseDouble(String str) { return Double.parseDouble(str.trim().replace(" ", "")) } static def parse(path) { InputStream inp = new FileInputStream(path) Workbook wb = WorkbookFactory.create(inp); Sheet sheet = wb.getSheetAt(0); Iterator<Row> rowIt = sheet.rowIterator() Row row = rowIt.next() def headers = getRowData(row) def rows = [] while(rowIt.hasNext()) { row = rowIt.next() rows << getRowData(row) } [headers, rows] } static def getRowData(Row row) { def data = [] for (Cell cell : row) { getValue(row, cell, data) } data } static def getRowReference(Row row, Cell cell) { def rowIndex = row.getRowNum() def colIndex = cell.getColumnIndex() CellReference ref = new CellReference(rowIndex, colIndex) ref.getRichStringCellValue().getString() } static def getValue(Row row, Cell cell, List data) { def rowIndex = row.getRowNum() def colIndex = cell.getColumnIndex() def value = "" switch (cell.getCellType()) { case Cell.CELL_TYPE_STRING: value = cell.getRichStringCellValue().getString(); break; case Cell.CELL_TYPE_NUMERIC: if (DateUtil.isCellDateFormatted(cell)) { value = cell.getDateCellValue(); } else { value = cell.getNumericCellValue(); } break; case Cell.CELL_TYPE_BOOLEAN: value = cell.getBooleanCellValue(); break; case Cell.CELL_TYPE_FORMULA: value = cell.getCellFormula(); break; default: value = "" } data[colIndex] = value data } static def toXml(header, row) { def obj = "<object> " row.eachWithIndex { datum, i -> def headerName = header[i] obj += " <$headerName>$datum</$headerName> " } obj += "</object>" } }

• Other useful classes that you can implement in a startup could be:

  • ElasticMappingRunner: mapper of case and task properties of specific Petri Nets

  • DemoFinisherRunner: extension of FinisherRunner

  • UserImportRunner: runner for creation of new users, in this runner you can also add specific roles to specific users

  • etc.

Frontend

Project structure

Cloned repository or unpacked project of the frontend is Netgrif Demo Application (NDA). Frontend NDA is an Angular 9 based application project.

Structure of NDA Angular 9 project is:

• e2e

  • is generated folder for an end to end integration testing

• node_modules

  • the package.json file in the app root defines what libraries will be installed into node_modules when you run npm install

• src

  • app

    • contains all .html, .css, .ts files

  • assets

    • folder for all assets (logos, pictures, …) in app

  • environments

    • contains the base configuration file

  • styles

    • basic application template theme

  • index.html, etc.

• nae.json, package.json, .npmrc, etc.

Good practice

New view creation

1. In file nae.json, you have to add new children into selected view (e.g. portal)

   "newModel": { "component": { "class": "NewModelComponent", "from": "./views/new-model/new-model.component" }, "layout": { "name": "tabView", "componentName": "NewModel", "params": { "tabs": [ { "view": { "name": "caseView" }, "label": { "icon": "storage", "text": "New model" }, "canBeClosed": false, "order": -1 } ], "allowedNets": [ "new_model" ], "defaultTaskView": { "view": { "name": "taskView" } } } }, "access": "private", "navigation": { "title": "Console", "icon": "settings" }, "routing": { "path": "newModel" } } } }

2. Your new view component is not created, yet. You need to use Angular schematics to generate all new components or update old ones. Command for view generation: ng generate @netgrif/components:create-view .

New filter creation

1. Now we do have a component named NewModel. Path to this component file where you can change filters is src → app → views → portal → newModel → content → 0/1 → …-task-view.component.ts

2. In this file is searchServiceFactory const, where you can add for example: new SimpleFilter

   const searchServiceFactory = () => { return new SearchService(new SimpleFilter('new_model', FilterType.CASE, { petriNet: [{ identifier : 'new_model'}] })); };

3. Alternatively you can use one of the many available static factory methods of the SimpleFilter class

   const searchServiceFactory = () => { return new SearchService(SimpleFilter.fromCaseQuery({ petriNet: [{ identifier : 'new_model'}] }); };

Documentations

https://developer.netgrif.com/
Frontend: 

https://developer.netgrif.com/projects/engine-frontend/latest/docs/

Backend: 

Java: https://developer.netgrif.com/projects/engine-backend/latest/javadoc/

Groovy: https://developer.netgrif.com/projects/engine-backend/latest/javadoc/

Petriflow:

XML scheme for Petriflow: https://developer.netgrif.com/projects/engine-backend/latest/schema/petriflow_schema.xsd

Petriflow object documentation: https://developer.netgrif.com/docs/Process-Objects.pdf

Petriflow API documentation: https://developer.netgrif.com/docs/Actions-API.pdf

Extra materials:

Angular Basics tutorial: https://developer.netgrif.com/docs/Angular-Basics.pdf

Installation and work with NAE Angular library: https://developer.netgrif.com/docs/Praca-s-NAE-angular_kniznicou.pdf

Tutorial on how to test frontend application: https://developer.netgrif.com/docs/Unit-Testing.pdf

Examples of Petri Nets (It is possible to open them in the NAB) and backend configuration file:

Example of the backend configuration file: https://developer.netgrif.com/example/application.properties

Example of Petri Net with all data types: https://developer.netgrif.com/example/all_data.xml

Example of Petri Net with different types of od modelling decision structures: https://developer.netgrif.com/example/routing.xml

Links to Angular and Spring Boot tutorials:

Angular: https://angular.io/guide/router-tutorial-toh

Spring Boot: https://spring.io/guides https://www.baeldung.com/