Property Store
Licenses | COMMUNITY, ENTERPRISE, CORPORATE |
Since | VERSION 6.0 |
- 1 Introduction
- 2 What is a Property?
- 3 How to work with the Property Store?
- 3.1 Create a new property
- 3.1.1 Documentation reference
- 3.1.2 Using a pipeline
- 3.1.3 Using the CLI
- 3.1.4 Using a Restful HTTP POST
- 3.2 Change the value of a property
- 3.2.1 Documentation reference
- 3.2.2 Using a pipeline
- 3.2.3 Using the CLI
- 3.2.4 Using a Restful HTTP POST
- 3.3 Delete a property
- 3.3.1 Documentation reference
- 3.3.2 Using a pipeline
- 3.3.3 Using the CLI
- 3.3.3.1 Deleting multiple properties
- 3.3.4 Using a Restful HTTP POST
- 3.3.5 Using a Restful HTTP GET
- 3.4 Listing and filtering existing properties
- 3.4.1 Documentation reference
- 3.4.2 Using a pipeline
- 3.4.2.1 Filtering
- 3.4.3 Using the CLI
- 3.4.4 Using a Restful HTTP POST
- 3.4.5 Using a Restful HTTP GET
- 3.1 Create a new property
- 4 The top-level folders
- 5 The app folder
- 6 Setting up a customization workspace
- 7 Working with Visual Studio Code
Introduction
The property store is a data repository in PIPEFORCE to save all your application data. You can upload, download and delete resources from the property store using pipeline commands or the online low-code workbench.
What is a Property?
Each entry stored in the property store is called a property. It has a unique key.
Properties in the property store are structured in an hierarchical way whereas the key of a property is also its path in the tree structure. Here is an example of such a key of a property:
global/app/myapp/settings
Each property contains certain attributes. The most important ones are:
uuid = A unqiue identificator of the property. Differently to the key, once created this will never change.
key = The unique key of the property. This value can change over time. For example if a property was moved to another virtual location.
value = This attribute contains the payload of the property.
type = This attribute contains the mime type of the value. If type is null, it is expected that the mime type of the value is of the default type t
ext/plain
.created = A unix epoch timestamp in MS when this property was created.
updated = A unix epoch timestamp in MS when this property was updated last.
timeToLive = The time to live (ttl) in minutes of this property since creation. If the time to live has been expired, the property is eligable to be deleted. Usually one of the next cleanup jobs will then delete this property. If the value of timeToLive is 0 or null, the property will never be deleted
To query a property with all of its attributes you can use the CLI and the property.list
command:
pi command property.list filter=global/app/myapp/pipeline/helloworld
This command will return a result similar to this which describes all important attributes of the property:
key: "/pipeforce/enterprise/global/app/myapp/pipeline/helloworld"
uuid: "529a38e7-9188-4135-b87b-3d890f6764f3"
value: "pipeline:\n - log: \n message: \"Hello World\""
defaultValue: null
type: "application/yaml;type=pipeline"
created: 1613397114448
updated: null
timeToLive: null
Binary property values
Typically the value
of a property is a string (text) value. Which type of text value is defined by the type
attribute which could be of any supported mime type.
Furthermore, the value
attribute can also contain binary data. In this case the field is base64
encoded. This is marked in the type
attribute as such using the mime type parameter encoding=base64
as this example implies:
How to work with the Property Store?
Typically the property store is managed using one of the property.*
commands. This is handy, if you want to manage the property store programmatically.
To get an overview of all available commands to manage the property store, you could type in this command in your terminal using the PIPEFORCE CLI:
This will show you all available property.*
pipeline commands and their description in the terminal.
Another possibility (only: ENTERPRISE, CORPORATE) to see the documentation of available commands is to go to this url:
and go to Commands (replace NAMESPACE by your real namespace). In the search box type-in property.
This will list all available commands to manage properties in the property store. Click on such a command to get details about it or to execute it online.
Create a new property
To create a new property, you need to use the command property.schema.put
.
Whenever you create a new a property, an event with key property.created
is fired which can be used in other pipelines to listen for it.
Documentation reference
See this link of your instance for details about this command (only: ENTERPRISE, CORPORATE): https://portal-NAMESPACE.pipeforce.net/#/pipeform?pipe=property.schema.put
Or use the CLI to get the documentation of this command listed:
Using a pipeline
Here is an example using a simple pipeline to create a new property:
Using the CLI
Here is an example to use the CLI to create a new property:
Using a Restful HTTP POST
In this example, a new property is created sending a HTTP POST request with the pipeline in JSON format:
Change the value of a property
To change the value of the property, you can use the command property.put
.
Whenever you change the value of a property, an event with key property.changed
is fired which can be used in pipelines to listen for it.
Note: The property must already exist before you set its value. So use property.schema.put
to define the property and then property.put
to set its value.
Documentation reference
See this link of your instance for details about this command (only: ENTERPRISE, CORPORATE): https://portal-NAMESPACE.pipeforce.net/#/pipeform?pipe=property.put
Or use the CLI to list the documentation:
Using a pipeline
Here is an example of using a pipeline to set the value of a property:
You can also combine two commands to create a property and set its value right after:
Using the CLI
Here is an example using the CLI to set the value of a property manually:
Uploading multiple files as properties
If you did setup a local low-code workspace with an app with multiple files in it and you want to upload those resources to the property store, you can use the CLI:
This CLI call with automatically “convert” all of your local files stored inside thy myapp
folder to properties and uploads them to the server afterwards. The content of the files will become the value field of the property. Furthermore the type (mime type) field is automatically detected by inspecting the extension and the content of the file.
This can save you a lot of effort compared to do manual uploads.
See the CLI documentation for more information about the publish action Command Line Interface (CLI)
Using a Restful HTTP POST
In this example, a value of a property is changed by sending a HTTP POST request with the pipeline in JSON format:
Delete a property
In order to delete a property from the property store, you can use the command property.schema.delete
which deletes the property value and all meta data that belong to this property.
Documentation reference
See this link of your instance for details about this command (only: ENTERPRISE, CORPORATE): https://portal-NAMESPACE.pipeforce.net/#/pipeform?pipe=property.schema.delete
Or make this call in your terminal using the CLI:
Using a pipeline
Here is an example using a pipeline to delete a property:
Using the CLI
Here is a call using the CLI to delete a property manually:
This approach allows to delete a property at any location as long as you have the permission to do so.
Deleting multiple properties
With the CLI it is also possible to delete multiple properties with one call:
This will delete all properties below the path somename recursively.
This will delete only properties inside the “folder” somename
but will leave all sub folders of it untouched.
Using a Restful HTTP POST
In this example, the property will be deleted by sending a HTTP POST request with the pipeline in JSON format:
Using a Restful HTTP GET
In this example, the property will be deleted by sending a HTTP GET request :
Listing and filtering existing properties
If you want to list all existing properties and their metadata, you can use the command property.list
.
Documentation reference
See this link of your instance for details about this command: https://portal-NAMESPACE.pipeforce.net/#/pipeform?pipe=property.list
Or use the CLI to display the documentation in the command line:
Using a pipeline
Here is an example using a pipeline to list all properties:
This will return you all properties from the property store in case you have the permission to do so.
Filtering
If you want to list only properties from a certain sub-path, you can use the filter
parameter.
For example, if you want to see only the properties of your app myapp
, then use this filter:
The double asterisk **
means any sub-path.
The single asterisk *
means a single folder.
The wildcards (asterisks) can also be used inside a key. If you want to list for example all object schemas of your app myapp
, you could use this list filter:
Using the CLI
You can use this CLI to list all properties:
And for sure, you can also use the CLI with a filter:
Using a Restful HTTP POST
In this example, the properties will be listed by sending a HTTP POST request with the pipeline in JSON format:
Using a Restful HTTP GET
In this example, the properties will be listed by sending a HTTP GET request:
The top-level folders
The top-level level folders inside your property store define the access rules for a certain group or users of your instance.
global
The global root folder contains all data and configuration accessible by any user by default.
group
The resources inside this folder are accessible by the defined groups. Any group has its own sub folder here whereas the name of the folder is the uuid of the group.
tenant
This root folder contains any resources and application data for tenants. Any tenant has its own sub folder here whereas the name of the folder is the uuid of the tenant.
user
This root folder contains user specific resources and application data. Any user has its own sub folder here whereas the name of the folder is the uuid of the user.
The app folder
The app folder contains all resource folders which are required to define a single app. The name of the sub folder of the app folder is the unique name of the app. Here is an example how such a folder structure typically looks like:
The key of your application would be this:
Since the app myApp
is stored inside the global app
folder, it is globally accessible. That means it can be potentially loaded by any user of the system. Whether this is possible additionally depends on the app itself since each app can have its own access rules set in IAM.
In order to make an app available only to a certain tenant, one could move it to the tenant folder as this example shows:
There is a bunch of built-in global apps which cannot be removed or changed by customizers. These names are reserved:
The app folder structure
Inside of an app
folder there is a certain folder structure which defines the resources of an app. The typical folder structure looks like this:
form
This folder contains all form configuration properties for any form of the app whereas the name of the property is the name of the form. For example:
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:
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:
Whereas <NAME>
is the name of the object.
<VERSION>
is the version of the object schema.
For example:
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:
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:
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:
Each instance property will contain as value the data of the object instance which matches the object schema, for example:
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 here more about pipelines: https://logabit.atlassian.net/wiki/spaces/DEVEX/pages/785088596
Each property name corresponds with the name of the pipeline and contains as value the pipeline configuration. For example:
Such a pipeline configuration could look like this:
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:
Such a script could look like this example:
You can call such a script from a pipeline, like this example shows:
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:
The property contains the test pipeline as value. Such a test pipeline could look like this:
workflow
This folder contains any BPMN workflow files defining a business process.
For example:
Setting up a customization workspace
In its simple case you can manage all properties in the property store with the property.*
commands and the CLI using pi pipeline
.
But if you want to develop applications with forms, pipelines or workflows inside, we recommend you to use a local development & customization workspace. This workspace contain the properties of such an app stored as files inside your local path $USER_HOME/pipeforce/app/myapp. Any file created inside the myapp folder can then easily be synced with the property store with a single command line call using the CLI:
This scans the your local myapp
folder and uploads only those resources which have been changed since last upload or have been created since then.
See here how to setup such a customization workspace: Low-Code Workspace (local)
See here for a getting started guide how to setup the CLI and use the local workspace: https://logabit.atlassian.netnull/pages/createpage.action?spaceKey=DEVEX&title=Getting%20Started%20-%20Basics&linkCreation=true&fromPageId=988807265 .
Working with Visual Studio Code
We recommend you to work with the Visual Studio Code editor to manage your local resources in the customization editor.
Learn more about using VS Code for this here: https://logabit.atlassian.net/wiki/pages/resumedraft.action?draftId=1008336990