What is an App?​

An 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 pipeline, form or workflow etc. is part of exactly one app.

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

For each app, certain access rules can be specified. Furthermore, it is also possible to use staging and versioning for apps. They can be developed online using the workbench or offline using source files and the CLI. You can think of 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 app in PIPEFORCE.

App structure​

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

global/app/<NAME>

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.

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:

1. The app name is written in lower case and may not contain any space or special character.

2. Use the reversed internet domain name of your company, project or organisation to begin the app name. For example if your domain name is myproject.org, then you should prefix your app name with org.myproject (reversed, in order to start from most generic to more specific parts).

3. Append your app name after the reversed domain name. For example: org.myproject.myapp.

Here is an example of a property path to a resource inside an app with fully qualified name:

global/app/com.logabit.myapp/data/helloworld

App folders​

Inside of an app path, there is a certain "folder" structure at top app level which defines the main resource types of an app. The typical folder structure looks like this (the folders could vary, depending on your setup):

/form​

This 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/myApp/form/createUser
global/app/myApp/form/deleteUser

/function

This 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 (FaaS)

/list​

This 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/myApp/list/users
global/app/myApp/list/employees

/object​

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

/schema​

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

global/app/myApp/object/<NAME>/<VERSION>/schema

Whereas <NAME> is the name of the object.

<VERSION> is the version of the object schema.

For example:

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/

/instance​

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

global/app/myApp/object/<NAME>/<VERSION>/instance/<UUID>

Whereas <NAME> is the name of the object.

<VERSION> is the version of the object schema.

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

For example:

global/app/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 folder contains all pipeline configurations for the given app. A pipeline can be seen as the business logic 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 example:

global/app/myApp/pipeline/informHR
global/app/myApp/pipeline/addToSAP
global/app/myApp/pipeline/addToActiveDirectory

Such a pipeline configuration 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​

Inside of the optional script folder, scripts can be placed which can contain more complex business logic if required. By default, such scripts are written in JavaScript. Optionally also Python or Groovy are available (ask support@pipeforce.io if required). 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​

This 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/myApp/test/createUserTest

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

pipeline:
  - test:
      assertTrue(false)

/workflow​

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

For example:

global/app/myApp/workflow/approveNewEmployee

App development​

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 pipeline 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 worskspace: Local Low-Code Workspace