catalog layer notification
The OLP CLI supports the following:
- create subscriptions to notifications for a layer
- delete subscriptions to notifications for a layer
- list subscriptions to notifications for a layer
Layer-level notifications allow you to get a notification whenever changes occur in a particular layer. You can choose which changes you wish to receive notifications for:
- All changes in the layer.
- Changes to a geographic area.
- Changes to specific partitions.
Notifications are essentially a data stream. Notifications are written as messages to a stream layer, and you receive notifications by subscribing to the layer and consuming the messages as you would consume data from any stream layer in the HERE platform.
Note
Layer-level notifications are currently available only for versioned
layers with HERE Tile partitioning.
catalog layer notification create
Creates subscriptions to notifications for a layer. Subscriptions allow you to get a notification whenever changes occur in a particular layer.
olp catalog layer notification create \
<notification catalog HRN> <notification stream layer ID> [command options]
olp catalog layer notification create ^
<notification catalog HRN> <notification stream layer ID> [command options]
Required parameters:
-
<notification catalog HRN>
The HRN of the catalog that contains the stream layer with notification messages. -
<notification stream layer ID>
The ID of the stream layer with notification messages. You must either have created the stream layer with the olp catalog layer add
command or you must have the READ
and WRITE
permissions for this layer. The stream layer can be in the same catalog as the layer for which you want to receive notifications. A stream layer can be reused for multiple subscriptions. For more info on stream layers, see catalog layer stream commands. -
--source-catalog <source catalog HRN>
The HRN of the catalog that contains the layer for which you want to receive notifications. -
--source-layers <sourceLayerID1 sourceLayerID2 ...>
The space-separated list of the IDs of the layers for which you want to receive notifications.
Optional parameters:
-
--subscription-area <all|wkt[:"WKT Geometry Object"]|partitions[:"partitionID1 partitionID2 ..."]>
Enables notifications for different parts of a layer. The default value is all
. Possible values are: -
all
Enables notifications in the entire layer. -
wkt
Enables notifications in a geographic area. This subscription area type accepts Well-Known Text (WKT) geometry object in a string format. -
partitions
Enables notifications for specific partitions.
Examples: all|wkt:"POINT (30 10)"|partitions:"partitionID1 partitionID2 ...".
-
--subscription-type <short|list|full>
Specifies the level of detail included in notification messages. The default value is full
. For more info about subscription types, see Contents of notifications. -
--credentials <path to credentials file>
The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal. -
--profile <profile name>
The name of the credentials profile to use from the olpcli.ini
file. -
--json
Displays the command result in JSON format. -
--quiet
Displays the ID of the subscription that was created. -
--scope <project HRN>
Specifies the project HRN to use as the scope in the request. The value specified with --scope
overrides any value for here.token.scope
provided in the credentials file used for the command.
Example:
The following command creates a subscription that allows you to get notifications whenever changes occur in specific partitions in the source-layer
of the catalog hrn:here:data::org:source-catalog
.
Notifications are written to the notification-layer
of the hrn:here:data::org:notification-catalog
. The content of notification messages is set to full
response.
olp catalog layer notification create \
hrn:here:data::org:notification-catalog notification-layer \
--source-catalog hrn:here:data::org:source-catalog \
--source-layers source-layer \
--subscription-area partitions:"partition-id" \
--subscription-type full
olp catalog layer notification create ^
hrn:here:data::org:notification-catalog notification-layer ^
--source-catalog hrn:here:data::org:source-catalog ^
--source-layers source-layer ^
--subscription-area partitions:"partition-id" ^
--subscription-type full
Output:
Subscription 46d1ca2b-cad0-44d1-8a67-099dc08a0d40 has been created
Notification message example:
Execute the following command to get notification messages: olp catalog layer stream get <notification catalog HRN> <notification layer ID>
. After the subscription is created, the following notification message is written to the notification-layer
when the source-layer
changes:
{
"catalogHRN":"hrn:here:data::org:source-catalog",
"catalogVersion":35,
"layerId":"source-layer",
"partitions":[
{
"version":35,
"partition":"partition-id",
"layer":"source-layer",
"dataHandle":"cf5325f3-fe68-413b-a94c-e1s616d54fc5",
"deleted":false
}
],
"timestamp":1637233214447,
"subscriptionResultType":"FULL"
}
catalog layer notification delete
Deletes subscriptions to notifications for a layer.
olp catalog layer notification delete \
<notification catalog HRN> <notification stream layer ID> [command options]
olp catalog layer notification delete ^
<notification catalog HRN> <notification stream layer ID> [command options]
Required parameters:
-
<notification catalog HRN>
The HRN of the catalog that contains the stream layer to which the notification messages are written. -
<notification stream layer ID>
The ID of the stream layer to which the notification messages are written.
Note
Be sure to specify the catalog and the layer containing the notification stream, not the catalog whose changes trigger notifications.
Optional parameters:
-
--subscription-ids <subscriptionID1 subscriptionID2 ...>
List of specific subscriptions to delete. If this parameter is not specified, all subscriptions for the specified layer will be deleted. -
--credentials <path to credentials file>
The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal. -
--profile <profile name>
The name of the credentials profile to use from the olpcli.ini
file. -
--json
Displays the command result in JSON format. -
--quiet
Displays the ID of the subscription that was created. -
--scope <project HRN>
Specifies the project HRN to use as the scope in the request. The value specified with --scope
overrides any value for here.token.scope
provided in the credentials file used for the command.
Example:
The command below deletes the subscription with the ID 46d1ca2b-cad0-44d1-8a67-099dc08a0d40
that is stored in the layer notification-layer
of the catalog hrn:here:data::org:notification-catalog
.
olp catalog layer notification delete \
hrn:here:data::org:notification-catalog notification-layer \
--subscription-ids 46d1ca2b-cad0-44d1-8a67-099dc08a0d40
olp catalog layer notification delete ^
hrn:here:data::org:notification-catalog notification-layer ^
--subscription-ids 46d1ca2b-cad0-44d1-8a67-099dc08a0d40
Output:
Subscription 46d1ca2b-cad0-44d1-8a67-099dc08a0d40 has been deleted
catalog layer notification list
Lists subscriptions to notifications for a layer.
olp catalog layer notification list \
<notification catalog HRN> <notification stream layer ID> [command options]
olp catalog layer notification list ^
<notification catalog HRN> <notification stream layer ID> [command options]
Required parameters:
-
<notification catalog HRN>
The HRN of the catalog that contains the stream layer to which the notification messages are written. -
<notification stream layer ID>
The ID of the stream layer to which the notification messages are written.
Note
Be sure to specify the catalog and the layer containing the notification stream, not the catalog whose changes trigger notifications.
Optional parameters:
-
--credentials <path to credentials file>
The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal. -
--profile <profile name>
The name of the credentials profile to use from the olpcli.ini
file. -
--json
Displays the command result in JSON format. -
--quiet
Displays the ID of the subscription that was created. -
--scope <project HRN>
Specifies the project HRN to use as the scope in the request. The value specified with --scope
overrides any value for here.token.scope
provided in the credentials file used for the command.
Example:
The command below returns a list of subscription IDs that were created for the layer notification-layer
of the catalog hrn:here:data::org:notification-catalog
.
olp catalog layer notification list \
hrn:here:data::org:notification-catalog notification-layer
olp catalog layer notification list ^
hrn:here:data::org:notification-catalog notification-layer
Output:
46d1ws2b-cad0-44d1-8a67-099dc08a04f7
12w1ar0h-gec4-60c0-7d36-164wm11y43d1