Triggers

Type	Base Path	Trigger Name
REST resource	~{realm}/users/{user-id}/triggers/	triggers

This resource holds the user's triggers. A trigger is a condition and action that can fire whenever a entity in a resource is updated.

See also Event Streams for more an alternative way to receive notifications when entities are updates.

Endpoints

Name	Method	Relative Path	Payload	Response	Description
addTrigger	POST	~{realm}/users/{user-id}/triggers/	Trigger	Stored_Trigger	Adds a new trigger to the list.
listTriggers	GET	~{realm}/users/{user-id}/triggers/	N/A	Stored_Trigger[]	Retrieves a list of triggers.
getTrigger	GET	~{realm}/users/{user-id}/triggers/{id}	N/A	Stored_Trigger	Retrieves a trigger.
putTrigger	PUT	~{realm}/users/{user-id}/triggers/{id}	Trigger	Stored_Trigger	Replaces a trigger.
updateTrigger	PATCH	~{realm}/users/{user-id}/triggers/{id}	Partial_Trigger	Stored_Trigger	Updates specified trigger fields.
removeTrigger	DELETE	~{realm}/users/{user-id}/triggers/{id}	N/A	N/A	Deletes a trigger.

Permissions

Permission	Description
edit-triggers	Client is allowed to add new triggers and to modify or delete existing triggers (for any user).
show-triggers	Client is allowed to query the trigger list and to fetch individual triggers (for any user).
use-triggers	Client is allowed to use and modify the user's own triggers.

Note that in addition to the permissions above, for query triggers, you also need read access to the actual resource the trigger refers to.

Entities

Interface Trigger

namespace Trigger {
    type Type = 'cron' | 'query';
}

interface Trigger {
    'type': Trigger.Type;
    'user': number;
    'start-date'?: DateTime;
    'schedules'?: string[];
    'end-date'?: DateTime;
    'query'?: QueryTrigger;
    'action': TriggerAction;
    'id'?: number;
    'created'?: DateTime;
    'updated'?: DateTime;
    'deleted'?: DateTime;
    'updated-by'?: number;
    'updated-from'?: number;
    'tags'?: string[];
    'labels'?: number[];
}

Property	Data Type	Description
type	Trigger.Type?	Type of trigger.
user	Int64	The ID of the user that owns this trigger.
start-date	DateTime?	A starting date when this trigger becomes active.
schedules	CronExpr[]?	A schedule that specifies at what time this trigger is active (applicable only between start-date and end-date). Required for cron triggers and optional for query triggers.
end-date	DateTime?	An ending date when this trigger becomes inactive.
query	QueryTrigger?	If type is query, an object that specifies the trigger conditions.
action	TriggerAction	The action that should happen when the trigger fires.
id	Int64?	The resource ID of this entity.
created	DateTime?	Date and time when this entity was first created.
updated	DateTime?	Date and time when this entity was last modified.
deleted	DateTime?	Date and time when this entity was deleted.
updated-by	Int64?	ID of User who last modified this entity.
updated-from	Int64?	ID of Till (trusted device) which last modified this entity.
labels	Int64[]?	A list of Label IDs associated with this entity.

Interface QueryTrigger

interface QueryTrigger {
    'resource': string;
    'query': string;
    'operations'?: DataObjectOperation.Operation[];
}

Property	Data Type	Description
resource	String	The resource the query should be evaluated against. The value of this property is documented as Trigger Name for each resource in this chapter.
query	String	The query to check entities that are being modified against. See Query Language.
operations	DataObjectOperation.Operation[]?	An optional list of operations that must match the current op. Defaults to all operations (i.e. create, update, and delete).

Interface TriggerAction

namespace TriggerAction {
    type LogLevel = 'errors' | 'warnings' | 'results' | 'progress' | 'all';
    type Type = 'auto-close-batch' | 'erp-integration' | 'report' | 'webhook' | 'digital-receipt' | 'dm-campaign' | 'email';
}

interface TriggerAction {
    'type': TriggerAction.Type;
    'name': string;
    'description'?: string;
    'log-level'?: TriggerAction.LogLevel;
    'notification-uri'?: string;
    'auto-close-batch'?: AutoCloseBatchAction;
    'erp-integration'?: ERPAction;
    'report'?: ReportAction;
    'webhook'?: WebhookAction;
    'digital-receipt-action'?: DigitalReceiptAction;
    'dm-campaign'?: DMCampaignAction;
    'send-email-action'?: SendEmailAction;
}

Property	Data Type	Description
type	Type	Trigger action type. Should be set to webhook.
name	String	The name of the trigger action.
description	String?	An optional description of the trigger action.
log-level	LogLevel?	If present, events with higher or equal log level will be stored in the trigger event log.
notification-uri	URI?	A notification URI. If present, and the trigger action produces a result, the result will be sent/uploaded to this URI.
auto-close-batch	AutoCloseBatchAction?	Auto-close batch parameters. Only applicable if type is auto-close-batch.
erp-integration	ERPAction?	ERP integration parameters. Only applicable if type is erp-integration.
report	ReportAction?	Report parameters. Only applicable if type is report.
webhook	WebhookAction?	Web hook parameters. Only applicable if type is webhook.
digital-receipt-action	DigitalReceiptAction?	Digital receipt parameters. Only applicable if type is digital-receipt.
dm-campaign	DMCampaignAction?	Direct marketing campaign parameters. Only applicable if type is dm-campaign.
send-email-action	SendEmailAction?	E-mail parameters. Only applicable if type is send-email.

The following log levels are defined. If no log level is set, no entry in the trigger event log will ever be created by this action.

Log level	Description
errors	Only final failures will be logged. All retries failed and the system will no longer try to process the action.
warnings	All failures will be logged, even if the action will be automatically by the system retried later.
results	If an action produces a result, an event will be created and the result will be attached to the event.
progress	All action progress will be logged; however, results will not be attached to the event in the trigger event log.
all	All action progress will be logged, and results, if there are any, will be attached to the event.

Only actions with log level results or all will store results in the trigger event log. Note that results may still be sent/uploaded via the notification-uri mechanism, regardless of the log level. For instance, a report action that is used to send reports by e-mail could use log-level warnings or progress if the report should not also be stored in the system, but results or all if it should.

Interface WebhookAction

This interface describes the web-hook (endpoint URI, message content-type and, optionally, authentication).

interface WebhookAction {
    'endpoint-uri': string;
    'content-type': string;
    'access-token'?: number;
}

Property	Data Type	Description
endpoint-uri	URI	The (HTTP/HTTPS/FTP/MAILTO) endpoint where the web hook payload will be posted.
content-type	String	What format the web hook payload will be delivered in. Supported content types are application/json, application/xml or text/csv.
access-token	Int64?	An optional reference to an access-token to be used for request authentication.

Webhook authentication is supported in two ways. First, it's possible to include username/password credentials within the endpoint URI itself (example: https://username:password@hostname/path), which will be used if the remote server requests Basic or Digest authentication.

Another way to provide the credentials is to add an access-token reference. All three access token types are supported.

Access Token Type	Description
access-token	The key property holds an UTF-8-encoded password, which will be used in the same way as an URI-embedded password (i.e., for Basic and Digest authentication).
hawk-key	The key will be used to calculate a Hawk signature. Both internal and external AccessTokens are allowed, so it's possible to reuse an API key, if desired.
pkcs12	The PKCS #12 archive in key should include a certificate (and private key) with alias cert, that will be used for client TLS authentication.

When using an access token as credential source, the username or Hawk ID will be set to {user-alias}+{token-alias}@{realm}, unless a custom username is provided in the endpoint URI (example: https://username@hostname/path).

Referencing an API access token (i.e., a hawk-key token) in the webhook is the preferred way to provide authentication, since you most probably already have such a token, and there is no way for the secret to leak. Client TLS authentication is an equally good authentication method, but it requires extra setup steps.

However, using URI-embedded credentials or an access-token of type access-token implies that the secret is not really a secret anymore: the URI itself is fully visible and even if the access tokens key property is never revealed by the server, it will still be transmitted in the clear to any webhook endpoint the account owner wishes.

Interface WebhookMessage

When the server executes a web hook, this is the payload that will be POSTed to the endpoint-uri.

interface WebhookMessage {
    'service-endpoint-uri': string;
    'company-alias': string;
    'user-alias': string;
    'trigger': number;
    'trigger-event'?: number;
    'data-object'?: DataObjectOperation;
}

Property	Data Type	Description
service-endpoint-uri	URI	An API URI where the Onslip 360 server is available. Use this URI if you need to fetch more data or perform server operations as part of the web hook processing.
company-alias	String	The realm where the firing trigger is defined.
user-alias	String	The user alias that owns the firing trigger.
trigger	Int64	The ID of the firing trigger.
trigger-event	Int64	The ID, if present, of the trigger event that tracks the progress of this trigger execution.
data-object	DataObjectOperation	A description of the data operation that caused the trigger to fire.

service-endpoint-uri is provided so you can easily recognize what Onslip 360 environment (staging, production etc.) the web hook comes from. company-alias, user-alias and trigger uniquely identifies the trigger that fired within this environment.

Interface DataObjectOperation

namespace DataObjectOperation {
    type Operation = 'create' | 'update' | 'delete';
}

interface DataObjectOperation {
    'operation': DataObjectOperation.Operation;
    'resource': string;
    'payload': DomainObject;
}

Property	Data Type	Description
operation	DataObjectOperation.Operation	What operation caused the trigger to fire.
resource	String	The resource where the entity is located.
payload	Object	The entity itself.