...
In most locations where a URI is accepted as an argument, for example in commands or utils, you can apply such a PIPEFORCE URI.
Here are some examples of such common PIPEFORCE URIs:
URI | Description |
---|---|
| Loads a file from the |
| Loads a property from the property store |
...
and returns the |
...
the property |
...
plus all metadata such as | |
| Executes the persisted pipeline at given location and returns the final body content as result. |
| Executes the persisted pipeline at given location, passes the given parameters |
| Returns the information object of the given user with given username. |
|
...
|
Here is an example to apply a custom URI on a command:
...
Code Block | ||
---|---|---|
| ||
{ "checksum": "sha-256=38334e50687bc68125e3b66121311a0bd1b848b8fa36c85dfe189d84313c5582", "path": "/pipeforce/ns/global/app/myapp/config/app", "uuid": "cc059f6e-fa6a-4ad8-bc51-04a85e33b965", "locked": false, "trashed": false, "value": "{ \"title\": \"My App\", ...}", "defaultValue": null, "type": "application/json", "created": 1669907722095, "updated": 1671171893712, "timeToLive": null } |
In order to And if you would like return only the value title
text of a the JSON property , add a property filter with @
at the end (see below for more details about this)value, you can use the #
symbol which let you query the content of the returned JSON value by applying a PEL on it. For example:
Code Block | ||
---|---|---|
| ||
pipeline: - resolve: uri: $uri:property:gloabl/app/myapp/config/app@valueapp#title |
This will the return only the value part of the property as JSONwould return:
Code Block | |
---|---|
json | { "title": "My App", "description": "This is my app", "icon": "assignment", "tags": [ "myapp" ], ... } |
And if you would like return only the title
text of the property value, you can use the #
symbol which filters the value of a property, in case it is a JSON document (more about this in the description for Property URI below). For example:
Code Block | ||
---|---|---|
| ||
pipeline:
- resolve |
Info |
---|
In case you use the |
Here is an example how to use this command with curl
on the terminal with URI encoded parameter (the symbol #
is encoded to %23
):
Code Block |
---|
curl -X GET -u username:password 'https://hub-ns.pipeforce.net/api/v3/command/resolve?uri=$uri:property:gloabl/app/myapp/config/app%23title' |
By the @resolve.uri
util
Another possibility inside a pipeline is to use the @resolve.uri
function:
Code Block |
---|
pipeline: - body.set: value: "Content uriis: ${@resolve.uri('$uri:property:gloabl/app/myapp/config/app#title |
This would return:
Code Block |
---|
My App |
Info |
---|
In case you use the |
Here is an example how to use this command with curl
on the terminal with URI encoded parameter (the symbol #
is encoded to %23
):
Code Block |
---|
curl -X GET -u username:password 'https://hub-ns.pipeforce.net/api/v3/command/resolve?uri=$uri:property:gloabl/app/myapp/config/app%23title' |
By the @resolve.uri
util
Another possibility inside a pipeline is to use the @resolve.uri
function:
Code Block |
---|
app')}" |
PIPEFORCE URI Types
$uri:drive
This custom URI points to a file on the data room service drive
.
Code Block |
---|
$uri:drive:<PATH_TO_FILE_OR_FOLDER_ON_DRIVE> |
Example:
Code Block | ||
---|---|---|
| ||
pipeline:
- mail.send:
attachments: $uri:drive:/contracts/contract1.pdf |
$uri:pipeline
This URI can be used to execute a persisted pipeline, and return the final body output of this pipeline as a result.
Code Block |
---|
$uri:pipeline:<PATH_TO_PERSISTED_PIPELINE> |
Let's assume you have a pipeline like this stored at global/app/myapp/pipeline/hello
:
Code Block | ||
---|---|---|
| ||
vars: name: null pipeline: - body.set: value"HELLO: "Content is:+ ${@resolve.uri('$uri:property:gloablvars.name}" |
To execute this pipeline and to output this hello world example, you could execute a URI like this:
Code Block | ||
---|---|---|
| ||
pipeline: - resolve: $uri:pipeline:global/app/myapp/config/app@value')}" |
PIPEFORCE URI Types
$uri:drive
This custom URI points to a file on the data room service drive
.
Code Block |
---|
$uri:drive:<PATH_TO_FILE_OR_FOLDER_ON_DRIVE> |
Example:
Code Block | ||
---|---|---|
| ||
pipeline:
- mail.send:
attachments: $uri:drive:/contracts/contract1.pdf |
$uri:pipeline
This URI can be used to execute a persisted pipeline, and return the final body output of this pipeline as a result.
Code Block |
---|
$uri:pipeline:<PATH_TO_PERSISTED_PIPELINE> |
Let's assume you have a pipeline like this stored at global/app/myapp/pipeline/hello
:
Code Block | ||
---|---|---|
| ||
vars:
name: null
pipeline:
- body.set: "HELLO: + ${vars.name}" |
To execute this pipeline and to output this hello world example, you could execute a URI like this:
Code Block | ||
---|---|---|
| ||
pipeline:
- resolve: $uri:pipeline:global/app/myapp/pipeline/hello?name=Sam |
In this example the URI parameter name
is used inside the pipeline as variable name
.
This will create a log-entry like this:
Code Block |
---|
Output: HELLO: Sam |
Adhoc Pipeline URI
You can use the $uri:pipeline
scheme also in order to execute an adhoc pipeline. This is an adhoc combination of commands to be executed in serial. The format is like this:
Code Block |
---|
$uri:pipeline:?commandA="param1:value1;param2:value2"&commandB |
This approach is handy in case you would like to call one or more commands in serial.
The Path part is empty and only the query string is given, starting with ?
whereas the name of a query param is the name of the command. The optional query param value contains the parameters to the command whereas name and value is separated by a colon :
and multiple params are separated by by a semicolon ;
.
In case a command parameter is a default command parameter, it can be used without any parameter name prefix in the URI. For example:
Code Block |
---|
$uri:pipeline:?uri.get="http://host/path"&data.filter.jmespath="[?id=12]" |
Since uri
of command uri.get
and query
of command data.filter.jmespath
are default parameters, these parameter names can be skipped. But this must be then the only parameter given to the command. If you need more parameters per command, the pipeline must be written including the parameter names in the query like this:
Code Block |
---|
$uri:pipeline:?uri.get="uri:http://host/path;body=abc"&data.filter.jmespath="query:[?id=12]" |
$uri:property
This custom URI points to a property in the property store.
Code Block |
---|
$uri:property:<PATH_OF_PROPERTY_IN_PROPERTY_STORE> |
Example:
Code Block |
---|
pipeline:
- body.set:
value: "${@resolve.uri('$uri:property:global/app/myapp/object/person')}" |
Property Filter
It is also possible to further filter the property using a PE, which gets applied to the property before its result will be returned.
Code Block |
---|
$uri:property:<PATH>@<PROPERTY_FILTER> |
As you might already know, a property has a structure like this (envelope + value):
Code Block | ||
---|---|---|
| ||
{
"path": "/unique/path/of/the/property",
"uuid": "unique id",
"type": "mime type of this property",
"created": createdTimeStampInMillis,
"value": "The payload of the property",
"attachments": [
{
"uuid": "unique id",
"name": "file name of the attachment",
"size": bytes,
"contentType": "content type of this attachment",
"chunks": [
{
"size": bytes,
"content": byteArray
},
...
]
},
...
]
...
} |
For a full list of the attributes of a property, please refer to Property Store.
With a property URI filter, you can now select the part you would like to return in your URI:
Code Block | ||
---|---|---|
| ||
pipeline:
- body.set:
value: "Num. of attachments: ${@resolve.uri('$uri:property:global/app/myapp/object/person@created')}" |
Value Filter (JSON)
In case the value of a property is of type application/json
, you can apply a filter on the value in order to return just a subset from the JSON value.
Code Block |
---|
$uri:property:<PATH>#<VALUE_FILTER> |
Info |
---|
This filter only works in case the value of the property is of the type: |
Let's assume we have a property in the property store like this:
Code Block | ||
---|---|---|
| ||
{
"path": "path/to/person",
"type": "application/json",
"value": {
"name": "Max Master",
"age": 35,
"hobbies": [
"swimming",
"hiking"
]
}
} |
We can use a Value Filter in the property URI in order to directly return the name of the person, like this:
Code Block |
---|
pipeline:
- body.set:
value: "Name: #{@resolve.uri('$uri:property:path/to/person#name')}" |
Which will log a message like this:
Code Block |
---|
Name: Max Master |
It's possible to use the full power of the PEL to filter, for example:
Code Block |
---|
pipeline:
- body.set:
value: "Number of hobbies: ${@resolve.uri('$uri:property:path/to/person#@list.size(hobbies)')}" |
Which will log a message like this:
Code Block |
---|
Number of hobbies: 3 |
The value filter will be applied on the fully loaded properties value attribute: It will be converted to JSON and then the expression will be applied, then the resulting value is returned.
Info |
---|
In case you have a huge JSON and you have to avoid fully loading this JSON into memory first, consider to use deep JSON querying instead in order to filter out the required value directly in the database. For more details see: JSON Property Querying. pipeline/hello?name=Sam |
In this example the URI parameter name
is used inside the pipeline as variable name
.
This will create a log-entry like this:
Code Block |
---|
Output: HELLO: Sam |
Adhoc Pipeline URI
You can use the $uri:pipeline
scheme also in order to execute an adhoc pipeline. This is a combination of commands to be executed in serial, one after another from left to right. The format is like this:
Code Block |
---|
$uri:pipeline:?commandA="param1:value1;param2:value2"&commandB |
This approach is handy in case you would like to call one or more commands in serial without persisting a pipeline for this.
The path part of the URI is empty and only the query string is given, starting with ?
whereas the name of a query param is the name of the command. The optional query param value contains the parameters to the command whereas name and value is separated by a colon :
and multiple params are separated by by a semicolon ;
. For example:
Code Block |
---|
$uri:pipeline:?uri.get="uri:http://host/path;body=abc"&data.filter.jmespath="query:[?id=12]" |
In case a command parameter is a default command parameter, it can be used without any parameter name prefix in the URI. So the example from above can be simplified to this:
Code Block |
---|
$uri:pipeline:?uri.get="http://host/path"&data.filter.jmespath="[?id=12]" |
Since uri
of command uri.get
and query
of command data.filter.jmespath
are default parameters, these parameter names can be skipped. But this must be then the only parameter given to the command. If you need more than one parameter per command, the pipeline must be written including the parameter names.
$uri:property
This custom URI points to a property in the property store.
Code Block |
---|
$uri:property:<PATH_OF_PROPERTY_IN_PROPERTY_STORE> |
Example:
Code Block |
---|
pipeline:
- body.set:
value: "${@resolve.uri('$uri:property:global/app/myapp/config')}" |
Will return the property including metadata and value like this example:
Code Block | ||
---|---|---|
| ||
{
"checksum": "sha-256=38334e50687bc68125e3b66121311a0bd1b848b8fa36c85dfe189d84313c5582",
"path": "/pipeforce/ns/global/app/myapp/config/app",
"uuid": "cc059f6e-fa6a-4ad8-bc51-04a85e33b965",
"locked": false,
"trashed": false,
"value": "{ \"title\": \"My App\", ...}",
"defaultValue": null,
"type": "application/json",
"created": 1669907722095,
"updated": 1671171893712,
"timeToLive": null
} |
$uri:user
This uri is handy to load a user object given by a username or uuid.
...