What is an Automation App?​

An automation app in PIPEFORCE is like an app for mobile phones. Such an app groups together resources like scripts, templates, configurations and others to solve a certain business task. Any automation pipeline, form or , workflow etc. is part of exactly one app. Such an app is the logical unit of an automation solution having a unique name.

An automation app can be shared with others on the marketplace and installed, updated or uninstalled using commands.

For each automation app, certain access rules can be specified. Furthermore, it is also possible to use staging and versioning for automation apps. They can be developed online using the workbench or offline using source files and the CLI. You can think of automation apps also like “plug-ins” for PIPEFORCE which can be installed and updated at runtime.

Also see this tutorial to learn how to create an automation app in PIPEFORCE.​

App

...

home folder

Typically, all properties (resources) of an app reside in the property store and having a property path with a prefix like this:

...

The path always starts with prefix global/app, followed by the name of the app <NAME>, whereas <NAME> must be a fully qualified, unique name as described below.

This path is called the app home folder.

Qualified app naming​

In order to avoid a naming clash with other apps from other users which could probably have the same naming as your app, as best practise, you should give the app always a name which follows the reversed domain name package conventions from the Java package specification, which works like this:

...

App folders and resources​

Inside of an app path, there is a certain " folder " structure at top app home folder level which defines the main resource types of an app. Depending on in which folders properties are stored inside an app, auto-backend tasks could be fired. The typical folder structure looks like this (the folders could vary, depending on your setup):

Naming convention

Any resource inside an app should follow this naming convention:

The property name is always in lower case, sections are separated with dashes and the name can start with an optional prefix, followed by a verb (if applicable):
<prefix>-<verb>-section1-section2-sectionN

The <prefix> is optional and is the only part which may contain upper case letters (for example A001). This can be used to define the order of properties or to link them to workflow tasks.

Examples:

global/app/tld.domain.myapp/pipeline/001-send-invite-email
global/app/tld.domain.myapp/pipeline/A1-upload-invoice
global/app/tld.domain.myapp/pipeline/add-to-sap
global/app/tld.domain.myapp/pipeline/inform-hr

/config

This optional folder contains all app specific configuration properties.

/app

The default configuration property for an app is the app property. This is automatically created if you create an app via CLI or the online property wizard. It is a JSON document of this basic format:

{
  "title": "My App",
  "description": "The description of the app",
  "icon": "some_icon_id",
  "color": "teal-8",
  "hidden": false,
  "tags": [
    "admin"
  ],
  "permissions": {
    "read": [
      "CAN_APP_io.pipeforce.myapp",
      "ROLE_ADMIN",
      "ROLE_DEVELOPER"
    ],
    "write": [
      "CAN_APP_io.pipeforce.myapp",
      "ROLE_ADMIN",
      "ROLE_DEVELOPER"
    ],
    "view": [
      "CAN_APP_io.pipeforce.myapp",
      "ROLE_ADMIN",
      "ROLE_DEVELOPER"
    ]
  }
}

"title"

The short title of the app. Can optionally be a $uri:i18n key for translations.

"description"

The description of the app. Can optionally be a $uri:i18n key for translations. Can be empty.

"icon"

The id of the Google Material icon to be used for this app. See here for listing of all available icons: https://fonts.google.com/icons . Note: Make sure to use the id of the icon not its name. If no icon is set, the system default icon will be used.

"color"

The color to be used for the app icon. If not set, the default color will be used. Also see here: Colors for more details about supported color codes.

"hidden"

An optional flag. If true, the app wont be shown in the apps listing in the portal. The default value is false.

"tags"

A list of optional search keywords. This improves finding this app via UI search.

"permissions"

Defines the required permissions for this app.

• read = A list of ROLES, the logged-in user must be member of (at least in one of it) to be able to read values in this app (for example list properties / data stored in this app).

• write = A list of ROLES, the logged-in user must be member of (at least in one of it) to be able to write values in this app (for example properties / data to the property store, submit forms).

• view = A list of ROLES, the logged-in user must be member of (at least in one of it) to be able to see the app tiles, forms and lists in the web UI.

/data

In case there are data objects (JSON documents), typically based on a schema, they should be stored inside this path structure:

global/app/tld.domain.myapp/data/<NAME>/<UUID>

Whereas <NAME> is the name of the data object.

<UUID> is the unique id of a single data object.

For example:

global/app/tld.domain.myapp/data/person/fa471958-fdb7-4bf6-a0a3-c5e8c782893e

Each instance property will contain as value the data of the object instance which typically matches the schema, for example:

{
  "firstName": "Homer",
  "lastName": "Simpson",
  "age":

...

 48,
  "gender": "male"
}

/form​

This optional folder contains all form configurations for any form of the app, whereas the name of the property is the name of the form. For example:

global/app/myApptld.domain.myapp/form/createUsercreate-user
global/app/myApptld.domain.myapp/form/deleteUserdelete-user

See here for more details: Forms Framework

/function

This optional folder contains all Python FaaS functions which will be automatically deployed when such a property of this app is stored in the property store in this folder.

For more information see: Python Functions

/i18n

This optional folder contains all internationalization (i18n) files like message files and other resources.
Also see: Internationalization (i18n).

/install

This optional folder can also contain pipeline YAML scripts. These pipelines will be executed only in case the app will be installed using the app.install or app.update command.

This is handy in case you would like to do some preparation on the install or update phase of an app like migrations for example.

The pipelines will be executed in their natural naming order. So if you would like to make sure a pipeline gets executed the very first, make sure it is at the very top of the naming order by using prefixes like 001-, 002- and so on.

/list​

This optional folder contains all list configuration properties for any list of the app, whereas the name of the property is the name of the list. For example:

global/app/myApptld.domain.myapp/list/all-users
global/app/myApptld.domain.myapp/list/all-employees

See here for more details: List Framework

/object​ (deprecated)

This optional folder contains any application model (schema) and its instances (if there are any).

/schema​ (deprecated)

The schema of an object is stored in a property having this path:

global/app/myApptld.domain.myapp/object/<NAME>/<VERSION>/schema

Whereas <NAME> is the name of the object.

...

object/person/v1/schema

The schema property typically contains as value a JSON schema, which describes this object. For the person object, the schema could, for example, look like this:

{
  "type": "object",

  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "age": {
      "type": "number"
    },
    "gender": {
      "type": "string",
      "enum": ["male", "female", "neutral"]
    }
  }
}

See the JSON schema specification for a description how to define JSON schema documents: https://json-schema.org/

...

section for more details: JSON Schema

/instance​ (deprecated)

In case there are object instances (JSON documents) based on a schema, they should be typically stored inside this path structure:

global/app/myApptld.domain.myapp/object/<NAME>/<VERSION>/instance/<UUID>

Whereas <NAME> is the name of the object.

...

For example:

global/app/myApptld.domain.myapp/object/person/v1/instance/fa471958-fdb7-4bf6-a0a3-c5e8c782893e

Each instance property will contain as value the data of the object instance which matches the object schema, for example:

{
  "firstName": "Homer",
  "lastName": "Simpson",
  "age": 48,
  "gender": "male"
}

/pipeline​

This optional folder contains all persisted pipeline configurations YAML scripts for the given app. A pipeline can be seen as the business logic or data integration part of an application.

Find more about pipelines here

Each property name corresponds with the name of the pipeline and contains as value the pipeline configuration. For exampleYAML script.

Examples:

global/app/myApptld.domain.myapp/pipeline/informHR001-send-invite-email
global/app/myApptld.domain.myapp/pipeline/addToSAPadd-to-sap
global/app/myApptld.domain.myapp/pipeline/addToActiveDirectory
inform-hr

Such a pipeline configuration YAML script could look like this:

pipeline:
  - mail.send:
      to: hr@company.de
      subject: "A new employee was addded!"

/setup​

This optional folder can contain pipelines. These pipelines will be executed in case the app will be installed using the app.install command.

This is handy in case you would like to do some preparation on setup phase of an app.

Note: The pipelines in this folder wont be auto-executed on save in the web UI or publish using the CLI.

/script​

...

Also see Automation Pipeline for more details how to create persisted pipelines.

/report

This optional folder can contain all report configurations.

See here for more details: Reporting Framework

/resource

This optional folder can contain any resource required inside the app. For example images, CSS files or similar.

/schema

The schema of an data object is stored in a property having this path:

global/app/tld.domain.myapp/schema/<NAME>

Whereas <NAME> is the name of the data object this schema stands for.

For example:

global/app/myApp/script/helloworld

Such a script could look like this example:

function command() {

    pi.message.headers["foo"] = "bar";
    pi.message.body = "HELLO WORLD IN THE BODY";

    var timestamp = pi.util.timestamp();
    pi.log.debug("Command script executed at: " + timestamp);
}

You can call such a script from a pipeline, like this example shows:

pipeline:
  - script.run:
      path: "global/app/myApp/script/helloworld"

/test​

...

tld.domain.myapp/schema/person

The schema property typically contains as value a JSON schema, which describes this object. For the person object, the schema could, for example, look like this:

{
  "type": "object",

  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "age": {
      "type": "number"
    },
    "gender": {
      "type": "string",
      "enum": ["male", "female", "neutral"]
    }
  }
}

See the JSON schema section for more details: JSON Schema

/setup​ (deprecated)

This optional folder can also contain pipeline YAML scripts. These pipelines will be executed only in case the app will be installed using the app.install command.

This is handy in case you would like to do some preparation on setup phase of an app.

The pipelines will be executed in their natural naming order. So if you would like to make sure a pipeline gets executed the very first, make sure it is at the very top of the naming order by using prefixes like 001-, 002- and so on.

/script​ (deprecated)

/system

This folder contains all system related backend data of this specific app. For example tmp data, workflow or form data. It is not meant for manual handling and you should not be required to touch or change content in it. It is fully managed by the platform.

/template

This optional folder should contains all templates like FreeMarker templates an others.

See here for more details: Template Transformation

/test​

This optional folder typically contains pipelines for tests only. Whenever necessary, PIPEFORCE automatically executes the test pipelines inside this folder to make sure the app is working as expected. Therefore you have to make sure that these tests can be executed at any time and are fully reentrant (once a test has been finished it can be executed again as often as necessary).

For example:

global/app/myApptld.domain.myapp/test/createUserTestcreate-user

The property contains the test pipeline as value. Such a test pipeline could look like this:

pipeline:
  - testassert:
      assertTrue(false)true: ${someTestExpression}

See here for more details: Testing Automation Apps

/uninstall

This optional folder can also contain pipeline YAML scripts. These pipelines will be executed only in case the app will be uninstalled using the app.uninstall command.

This is handy in case you would like to do some preparation before uninstall.

The pipelines will be executed in their natural naming order. So if you would like to make sure a pipeline gets executed the very first, make sure it is at the very top of the naming order by using prefixes like 001-, 002- and so on.

/update

This folder is optional and contains all migration pipeline YAML scripts in order to migrate from one app version to another. These pipelines will be executed only in case the app will be installed using the app.update command.

The pipelines will be executed in their natural naming order. So if you would like to make sure a pipeline gets executed the very first, make sure it is at the very top of the naming order by using prefixes like 001-, 002- and so on.

/workflow​

This optional folder contains any BPMN workflow files defining a business process.

For example:

global/app/myApptld.domain.myapp/workflow/approveNewEmployee

...

approve-new-employee

See here for more details: BPMN Workflows

Developing an automation app​

In its simple case you can manage all properties of an app in the property store with the property.* commands and the CLI using pi pipelinepublish or using the online workbench.

But if you want to develop complex apps with forms, pipelines or workflows inside, we recommend you to use a local development & customization workspace. This workspace contains the properties of such an app stored as files inside a local folder. Any file created inside this folder can then easily be uploaded to the property store with a single command line call using the CLI. For example:

pi publish

This CLI command scans your local folder and uploads only those resources which have been changed since the last upload or have been created since then. See here how to setup the CLI and how to create a local worskspaceworkspace: Local Low-Code Workspace