Zetapush API reference

Your connected application is made of several software components :
  • a back-end (we call that a sandbox), itself made of
    • One or more Zetapush authentications
    • Several Zetapush services
    • Your ZMS server-side scripts, a.k.a. Macros
  • a front-end, itself made of
    • Your client app code and UI (JS, Android, iOS, C)
    • A matching Zetapush client SDK

A Zetapush Authentication is a means for an end-user to log into a Zetapush application with some credentials : deploying at least an authentication is an absolute requirement for end-users to be able to connect.
You can deploy as many authentications as you want inside a sandbox. They will all be available at the same time : users can log in through any of your configured authentications.

Do not confuse the primary key within an authentication realm that your end-user uses to log in with his or her user key inside the sandbox : credentials used to log in need only be unique inside the context of their authentication realm whereas a user key is more global.
Whenever an API verb mentions the owner field, we are talking about the unique user key within a sandbox, i.e. the value of the implicit __userKey pseudo-constant within macroscripts.

A Zetapush Service is a configurable set of real-time APIs.
You can deploy as many services as you want inside a sandbox; you can even deploy several services of the same type, should the need arise.
You choose which APIs are deployed, and whether they are publicly exposed or not.
Any time you configure an authentication or a service, you get a deployment ID. That ID, along with your sandbox ID, is needed by the SDKs to call your deployed Zetapush APIs.
When deploying, you can configure some options to precise the behavior of your service, and choose if the APIs should be publicly available or hidden for exclusive use by your server-side scripts.
When any one of these statements is true
  • You're deploying your application on different client technologies (HTML, Android...)
  • You do not want to embed business logic in client code
  • You need some APIs that are not directly accessible to SDKs (such as sending emails)
  • You need some off-line and/or server-triggered business logic
... you need Macros.
Macros are the glue that bind your services together.
Macros seem fine to code inject some business logic into your application, but what about ...
  • re-using code from others, or from one project to another ?
  • continuous integration ?
  • instantly deploying whole applications on a new sandbox with just one command ?
Here come the Recipes.
Creating a basic working app requires just a few steps :
  • Create a Zetapush account
  • Configure at least one authentication
  • Configure your services
  • Deploy your sandbox
  • Grab an SDK and code some UI
A worthwhile addition to these steps : also grab the ZMS Editor (based upon Eclipse), read the Macros section of this documentation, and deploy your scripts with one click.

Alternatively to an SDK, you can make direct calls to your macro scripts using HTTP POST.
Here's an example using wget :
wget --header='Content-Type: application/json' \
 --header='X-Authorization: {"data":{"password":"password", "login":"toto3"}, "resource":"MY_ARDUINO", "type":"eH1O_PpN.y9zK.simple"}' \
 --post-data '{"name":"test", "parameters":{}}' \
 'http://node1.zetapush.local/str/restd/eH1O_PpN/iszT/call'

This example calls a macro named 'test' with no parameters. Some explanations :
  • eH1O_PpN is a sandbox identifier, a.k.a. 'businessId'
  • y9zK is the deployment identifier, a.k.a. 'deploymentId' of a 'simple' authentication
  • toto3 is the login of some user you created in this 'simple' authentication
  • MY_ARDUINO is an arbitrary string that identifies one device (possibly amongst many) belonging to user toto3.
  • the post data follows the syntax for macro.call (see the documentation below)
  • the URL (that's not an actual production URL) too follows the syntax of this documentation.
All the APIs share some common functionnality and behavior.
publish/subscribe paradigm
There is no direct programmatic correlation between the messages that you send and the ones that you receive. There is no request/response paradigm, even if some api verbs are designed to look like requests (and they can used as such to some extent).
This means that your client code will not use per-request promises, but stateless callbacks. API verbs that fit a traditional request/response approach will output enough context for you to find out which input request they match.
strictness
When a field is documented as mandatory and you omit it, the API call will fail. It might even, depending on the verb, fail with a pure syntax error: BAD_FIELD_FORMAT when the server can pinpoint the location(s) of the problem(s), or BAD_FORMAT otherwise.
null fields
Passing a null value from a client to the server or not passing the field at all have the same effect. Nulls do not survive the serialization/deserialization processes. They do not survive the storage process inside a GDA or Stack service either. They can still be used inside and across macros.
This means that you cannot even test client supplied input data for null safely inside a macroscript : if (foo.bar != null) will fail (ending the script execution) at run-time if foo.bar does not exist. But you can still test with the existence check operator : if (foo.bar??)
character set
The only supported character set is UTF-8 for all input to client SDKs and for ZMS source files.
reported errors
In addition to the errors explicitly described in the corresponding section, API calls can cause a variety of generic errors.
CodeDescription
BAD_FIELD_FORMATYour API call did not respect the expected format. The error message should contain a specific and detailed explanation of the problem.
BAD_FORMATYour API call did not respect the expected format.
ACCESS_FORBIDDENThe current user is not authorized to make that API call.
You might need
  • either properly configured rights in a group service
  • or a sudo call in your macro code
VERB_FORBIDDENYou tried to call a server verb from a client.
A server verb is
  • either marked as such in this documentation
  • or disabled (by you) for clients by listing it in a forbiddenVerb clause in your recipe
PARSE_ERRORYour API call was not parseable. This will not happen if you use the client SDKs.
Some errors are related to some hard limit on usable resources.
CodeDescription
CAPACITY_EXCEEDEDA macro service can only serve a maximum number of concurrent requests.
The value of this limit depends on your plan. On dedicated or on premise clusters, arbitrary limits can be set.
TIME_EXCEEDEDMacroscripts can only run for a maximum number of seconds. This is a per run limit.
The value of this limit depends on your plan. On dedicated or on premise clusters, arbitrary limits can be set.
QUOTA_EXCEEDEDFree sandboxes can only serve a monthly maximum of API requests, have a limited number of end-users, and a limited number of deployed services.
RATE_EXCEEDEDDeprecated. The checks associated with this limit have been permanently disabled.
RAM_EXCEEDEDAn API call can only consume a maximum number of bytes. This is a per run limit.
The value of this limit depends on your plan. On dedicated or on premise clusters, arbitrary limits can be set.
CYCLES_EXCEEDEDA macro call can only consume a maximum number of CPU cycles. This is a per run limit.
The value of this limit depends on your plan. On dedicated or on premise clusters, arbitrary limits can be set.
Fatal errors are errors that immediately terminate the execution of your running macro, ignoring whatever 'hardFail' behavior you requested. Note that quota errors are not recoverable either.
CodeDescription
STACK_OVERFLOWYour code is probably too recursive.
NO_SUCH_FUNCTIONYour code dynamically calls a run-time a non existing macrofunction. This is a coding error.
BAD_COMPARATOR_VALUEYour comparator callback does not respect the expected prototype. This is a coding error.
This authentication delegates authentication to an external auth provider.
When a zetapush client handshakes with a delegated authentication, the 'token' field given by the client is sent to the configured remote server as part of the URL.
The response must be in JSON format. Each key of the response will be considered a user information field name.
The handshake from the server will return the primary key in a field named 'login' (regardless of the actual key name you might have chosen)
Configuration options
DescriptionValueNameType
URL template. Parameter {0} is the token. Example http://myserver.com/check?token={0} mandatory
 
delegating_url STRING
user field considered as the primary key. The response from the remote server must contain this key. Modifying this value is not supported (it will lead to unpredictable results) default is login
 
delegating_uniqueKeyName STRING
custom mapping function to map inbound data to your format. takes one parameter (a map of input fields) and must return a map of translated fields. The mapping is applied before looking for the primary key. The name is macroService:functionName. Example : 'macro_0:myFunction' default is empty
 
delegating_mappingFunction STRING
Cache duration(minutes). 30 days by default default is 43200
 
delegating_cache_duration LONG
Whether the user should be logged without checks when the auth server is down default is false
 
delegating_down_ok BOOLEAN
Publish/Subscribe Services
End-user API for the delegating authentication
Provisioning verbs.
server
userInfo
Get user info
Implementation notes
Retrieves cached user info or (if missing) eagerly creates a zetapush key for the user.
The returned field 'zetapushKey' is a unique and permanent ID identifying a user in a sandbox.
Parameter
The parameter has the type ExistingUser
ExistingUser
NameDescriptionTypeRequired
key User key within the realm String required
Primary output
The response has the type Map[String,Object].
The result is only sent to the user session who made the call.
Zetapush local authentication. The configurer can choose the primary key and mandatory user fields for account creation. The field 'zetapushKey' is generated by the server and MUST not be used : it contains the unique key of the user inside a sandbox (it can be obtained from inside a macro with the __userKey pseudo-constant)
Configuration options
DescriptionValueNameType
user field considered as the primary key default is login
 
simpleauth_uniqueKeyName STRING
mandatory user fields, separated by commas. primary key and password are always mandatory, you don't need to add them here default is password
 
simpleauth_mandatoryFields STRING
Authentication token expiration delay (minutes) default is 43200
 
simpleauth_authTokenExpiry LONG
Reset password token expiration delay (minutes) default is 1440
 
simpleauth_resetTokenExpiry LONG
public user fields, separated by commas. these fields will be publicly available default is login
 
simpleauth_publicFields STRING
HTTP Controllers
Administrative API for the simple local authentication
These API verbs allow the developer to manage user accounts.
POST
/memauth/createUser
Creates a user
Audience
The API /memauth/createUser is reserved to developers
Use in recipes
The API /memauth/createUser is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Creates a new user in this 'simple' authentication realm.
Errors
No documented error codes.
Request body
The request body has the type BasicUserCreation
BasicUserCreation
NameDescriptionTypeRequired
additionalProperties You can pass any number of arbitrary properties in the enclosing object (there is no field actually named additionalProperties). Map[String,Object] optional
idempotence Specify the behavior when the user already exists. The default value is IGNORE_IDENTICAL Idempotence optional
Idempotence
String enumeration. Possible values are :
NameDescription
IGNORE_DIFFERENT The operation will not fail if the entity already exists in a different and compatible form.
FAIL_IF_EXISTING The operation will fail if the entity already exists
IGNORE_IDENTICAL The operation will not fail if the entity already exists in a similar form.
Response
The response body has the type BasicAuthenticatedUser
BasicAuthenticatedUser
NameDescriptionType
additionalProperties You can pass any number of arbitrary properties in the enclosing object (there is no field actually named additionalProperties). Map[String,Object]
POST
/memauth/deleteUser
Deletes a user
Audience
The API /memauth/deleteUser is reserved to developers
Use in recipes
The API /memauth/deleteUser is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Deletes a user by locally unique key in this 'simple' authentication realm.
Errors
No documented error codes.
Request body
The request body has the type ExistenceCheck
ExistenceCheck
NameDescriptionTypeRequired
key User key within the realm String required
softFail Whether to fail is the user does not exist. When true, fails silently. boolean optional
Response
The response body has the type void
GET
/memauth/listUsers
Lists users
Audience
The API /memauth/listUsers is reserved to developers
Implementation notes
Returns a paginated list of the users present in this 'simple' authentication realm.
Errors
No documented error codes.
Response
The response body has the type PageContent[BasicAuthenticatedUser]
BasicAuthenticatedUser
NameDescriptionType
additionalProperties You can pass any number of arbitrary properties in the enclosing object (there is no field actually named additionalProperties). Map[String,Object]
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
Publish/Subscribe Services
End-user API for the simple local authentication
These API verbs allow end-users to manage their account(s).
server
changePassword
Changes a password
Implementation notes
Changes a user password for this authentication realm.
The user can be either explicit, implicit (one of the current user's accounts) or deduced from the token.
You should provide at least one of 'key' and 'token'. If you do not, the server will try and find any key for the current user.
The change is effective immediately. However, already logged in users might stay connected.
The password and token fields are always null in the output.
Parameter
The parameter has the type ChangePasswordRequest
ChangePasswordRequest
NameDescriptionTypeRequired
token Server-provided temporary token to reset a password String optional
key account key in the realm. (configured 'unique key' used for authentication). String optional
password New password String required
Primary output
The response has the type ChangePasswordRequest.
The result is only sent to the user session who made the call.
ChangePasswordRequest
NameDescriptionType
token Server-provided temporary token to reset a password String
key account key in the realm. (configured 'unique key' used for authentication) String
password New password String
Error codes
CodeDescription
NO_ACCOUNTThe given account key in this realm (login) does not match an existing account.
server
checkPassword
Checks the password for the given account
Implementation notes
Parameter
The parameter has the type CheckPasswordRequest
CheckPasswordRequest
NameDescriptionTypeRequired
key account key in the realm. (configured 'unique key' used for authentication). String required
password Password to be checked String required
Primary output
The response has the type CheckPasswordResult.
The result is only sent to the user session who made the call.
CheckPasswordResult
NameDescriptionType
matches Whether the password matches boolean
key account key in the realm. (configured 'unique key' used for authentication) String
server
checkUser
Checks some account's existence
Implementation notes
Checks whether the given account already exists in this 'simple' authentication realm.
This verb returns all the information about the user, including non public fields.
Parameter
The parameter has the type ExistenceCheck
ExistenceCheck
NameDescriptionTypeRequired
key User key within the realm String required
softFail Whether to fail is the user does not exist. When true, fails silently. boolean optional
Primary output
The response has the type Map[String,Object].
The result is only sent to the user session who made the call.
Error codes
CodeDescription
NO_ACCOUNTThe given account key in this realm (login) does not match an existing account.
server
createUser
Creates an account
Implementation notes
Creates a new account in this 'simple' authentication realm.
Returns a map of account fields, including a field named zetapushKey containing the global user key of the user (value of the __userKey pseudo-constant when this new account will be used)
Parameter
The parameter has the type BasicAuthenticatedUser
BasicAuthenticatedUser
NameDescriptionTypeRequired
additionalProperties You can pass any number of arbitrary properties in the enclosing object (there is no field actually named additionalProperties). Map[String,Object] optional
Primary output
The response has the type Map[String,Object].
The result is only sent to the user session who made the call.
Error codes
CodeDescription
MISSING_MANDATORY_FIELDHappens when the caller does not fill a mandatory field (defined by the developer).
ACCOUNT_EXISTSHappens when the user account already exists with the given unique account key (login).
KEY_BADCHARThe given unique account key contains the forbidden character ':'.
server
credentials
Lists an account's credentials
Implementation notes
Returns the list of account credentials in this service for the asking user.
Might return an empty list.
Parameter
The parameter has the type ImpersonatedRequest
ImpersonatedRequest
NameDescriptionTypeRequired
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type AllCredentials.
The result is only sent to the user session who made the call.
AllCredentials
NameDescriptionType
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
credentials List of account information for the asking user. empty if the user does not have credentials in the service. One item in this list is a map of account fields. List[Map[String,Object]]
server
deleteUser
Deletes an account
Implementation notes
Deletes an existing account in this 'simple' authentication realm.
Parameter
The parameter has the type ExistenceCheck
ExistenceCheck
NameDescriptionTypeRequired
key User key within the realm String required
softFail Whether to fail is the user does not exist. When true, fails silently. boolean optional
Primary output
The response has the type ExistenceCheck.
The result is only sent to the user session who made the call.
ExistenceCheck
NameDescriptionType
key User key within the realm String
softFail Whether to fail is the user does not exist. When true, fails silently. boolean
Error codes
CodeDescription
NO_ACCOUNTThe given account key in this realm (login) does not match an existing account.
server
requestReset
Requests a password reset
Implementation notes
Requests a password reset for the given unique account key.
The account key must exist and must be given, as it cannot obviously be deduced from the currently logged in user.
The returned token needs to be sent to the intended recipient only. The typical use case is to define a macro that requests a reset, generates a email template and emails the user. The macro can then be safely called by a weakly authenticated user.
Requesting a reset does not invalidate the password.
Requesting a reset again invalidates previous reset requests (only the last token is usable)
Parameter
The parameter has the type ResetRequest
ResetRequest
NameDescriptionTypeRequired
key account key in the realm. (configured 'unique key' used for authentication). String required
Primary output
The response has the type ResetInfo.
The result is only sent to the user session who made the call.
ResetInfo
NameDescriptionType
token Server-provided temporary token to reset a password String
key account key in the realm. (configured 'unique key' used for authentication) String
Error codes
CodeDescription
NO_ACCOUNTThe given account key in this realm (login) does not match an existing account.
server
updateKey
Updates an account key
Implementation notes
Updates an existing account primary key (login, NOT __userKey) in this 'simple' authentication realm.
The updated account MUST belong to the user making the call.
The configured login field MUST be given, as a user (identified by his zetapush userKey) might possess several accounts.
Returns a map of account fields
Parameter
The parameter has the type UserLoginchange
UserLoginchange
NameDescriptionTypeRequired
newKey New account key within this realm. Must not be already in use. String required
oldKey Existing account key within this realm (login). Will be free for use upon successful completion. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type Map[String,Object].
The result is only sent to the user session who made the call.
Error codes
CodeDescription
ACCOUNT_EXISTSHappens when the user account already exists with the given unique account key (login).
NO_ACCOUNTThe given account key in this realm (login) does not match an existing account.
server
updateUser
Updates an account
Implementation notes
Updates an existing account in this 'simple' authentication realm.
The updated account MUST belong to the user making the call.
The configured login field MUST be given, as a user (identified by his zetapush userKey) might possess several accounts.
Returns a map of account fields
Parameter
The parameter has the type BasicAuthenticatedUser
BasicAuthenticatedUser
NameDescriptionTypeRequired
additionalProperties You can pass any number of arbitrary properties in the enclosing object (there is no field actually named additionalProperties). Map[String,Object] optional
Primary output
The response has the type Map[String,Object].
The result is only sent to the user session who made the call.
Error codes
CodeDescription
NO_ACCOUNTThe given account key in this realm (login) does not match an existing account.
The weak authentication allows for anonymous authentication of devices. Such devices can display a qrcode to allow regular users to take control of them
Configuration options
DescriptionValueNameType
qrcode generation template. Parameter {0} is the weak token default is {0}
 
weak_qrcode_format STRING
HTTP Controllers
Public HTTP API for weak users qrcode generation
This API can be called for example by a weakly authenticated device to display a qrcode image containing the public token of the weak authentication of that device.
Other users scanning that qrcode will be able to call the 'control' verb of the real-time API to take control of the device.
GET
/weak/qrcode/{publicToken}
Returns a qrCode for a token
Audience
The API /weak/qrcode/{publicToken} is publicly accessible
Implementation notes
Returns a PNG image containing a qrCode for the given public token.
The qrCode is generated with the deployment-configured format.
Errors
No documented error codes.
Response
The response body has the type ResponseEntity[byte[]]
Path parameters
DescriptionNameType
Public token of the device. The public token is given by the server to the device upon a successful handshakepublicTokenString
Publish/Subscribe Services
User API for weak devices control
User API for control and release of weakly authenticated user sessions.
pub
control
Controls a session
Implementation notes
Takes control of a weak user session, identified by the given public token.
The public token has been previously made available by the controlled device, for example by displaying a QRCode.
Upon control notification, the client SDK of the controlled session is expected to re-handshake.
Parameter
The parameter has the type UserControlRequest
UserControlRequest
NameDescriptionTypeRequired
publicToken Public token of the weak you want to control String optional
fullRights Whether the controlled user/device fully impersonates its controller boolean optional
Primary output
The response has the type UserControlStatus.
The result is sent to a list of users : the controlled user and the controlling user.
UserControlStatus
NameDescriptionType
controller User key of the controlling user String
publicToken Public token of the weak you want to control String
fullRights Whether the controlled user/device fully impersonates its controller boolean
Error codes
CodeDescription
TOKEN_ALREADY_CONTROLLEDWhen trying to control a device already controlled.
pub
getToken
Returns the current token
Implementation notes
Returns your current session's private token. The token field may be null, if you did not log in with this authentication.
The token can be used to log in as the same weak user another time.
Primary output
The response has the type UserToken.
The result is only sent to the user session who made the call.
UserToken
NameDescriptionType
token private token String
userKey userKey for this user String
publicToken public token String
server
provision
Provisions accounts
Implementation notes
Provisions an arbitrary number of accounts.
The maximum number of accounts that you can create in one single call is configured per server.
Parameter
The parameter has the type ProvisioningRequest
ProvisioningRequest
NameDescriptionTypeRequired
n Number of accounts to create int optional
Primary output
The response has the type ProvisioningResult.
The result is only sent to the user session who made the call.
ProvisioningResult
NameDescriptionType
users List of provisioned tokens List[UserToken]
UserToken
NameDescriptionType
token private token String
userKey userKey for this user String
publicToken public token String
Error codes
CodeDescription
CAPACITY_EXCEEDEDWhen trying to allocate more accounts than the server maximum.
pub
release
Releases a session
Implementation notes
Releases control of a weak user session, identified by the given public token.
The weak user session must have been previously controlled by a call to 'control'.
Parameter
The parameter has the type UserControlRequest
UserControlRequest
NameDescriptionTypeRequired
publicToken Public token of the weak you want to control String optional
fullRights Whether the controlled user/device fully impersonates its controller boolean optional
Primary output
The response has the type UserControlStatus.
The result is only sent to the user session who made the call.
UserControlStatus
NameDescriptionType
controller User key of the controlling user String
publicToken Public token of the weak you want to control String
fullRights Whether the controlled user/device fully impersonates its controller boolean
Error codes
CodeDescription
TOKEN_NOT_MINEWhen trying to release a session you do not control.
Provides data aggregation over time and across different items. User devices push items data on developer-defined categories. This service automatically aggregates the data.Raw data is not available for reading, only the generated aggregation result.
HTTP Controllers
Administrative API for aggregation items
Manage your items here.
Create, delete and list aggregation items.
POST
/aggreg/create
Creates an item
Audience
The API /aggreg/create is reserved to developers
Use in recipes
The API /aggreg/create is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Creates or updates an item category definition.
Items are aggregated based upon their category configuration.
When configuring a category, you specify the aggregation output via a callback. That callback can be configured to make use of the given 'item', 'type', 'category', 'value', 'timestamp' passed at run-time by this aggregation service.
  • 'type' and 'category' are defined by a call to this administrative verb (create).
  • 'item' is given in each AggregationPush instance by the caller of the run-time 'push' verb.
  • 'value' is computed by this service from various values given by the caller of the run-time 'push' verb.
  • 'timestamp' is the number of milliseconds from the epoch, aligned to the start of the current period.

Warning : when you update the configuration of an item, only new data are aggregated with the new configuration.
Errors
No documented error codes.
Request body
The request body has the type AggregationItemCategory
AggregationItemCategory
NameDescriptionTypeRequired
type Item type (aggregation behavior). AggregationItemType required
periods Item periods, in minutes. Automatic aggregation by this service ensures that these will be the minimum visible granularities. Although you can specify arbitrary values, it is recommended, for easier auto-alignment of period boundaries, to use divisors of well known values : for example 30 (half an hour) is a lot better than 29. List[Integer] required
parameter Parameter that will be passed to the target verb when called. The format is the format accepted by the target. Map[String,Object] optional
category Item category. Arbitrary developer-defined name. String required
deploymentId DeploymentId of the target service. String required
verb Verb to be called within the target service. String required
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
AggregationItemType
String enumeration. Possible values are :
NameDescription
MEAN Averages the item over the period (floating point values).
TOTAL Sums the item over the period (integral values only).
Response
The response body has the type void
Publish/Subscribe Services
User API for item aggregation
Users can push data and be notified of aggregated data.
This service does not allow you to read the data. To achieve that kind of behavior, you could configure a callback to store the data.
pub
push
Pushes some data
Implementation notes
Pushes the given data.
All the items are processed according to the defined rules.
At least one push for a given item is needed during a time period to trigger processing and calling of the corresponding callback verb/macro.
Parameter
The parameter has the type AggregationPushes
AggregationPushes
NameDescriptionTypeRequired
items List of items List[AggregationPush] required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
AggregationPush
NameDescriptionTypeRequired
value Numerical value : long for totals, floating point (double precision IEEE 754) for means Number required
name Item name. Any item name, unique for the user. An item more or less matches an actual device or sensor, but it can also be for example a virtual sensor name if you are averaging temperatures from several physical sensors. String required
category Item category. Must match a defined category. String required
Stacks are a per-user named persistent queue of data. An administrator creates a stack service. End-users can push data on an arbitrary number of their own arbitrary named stacks
Configuration options
DescriptionValueNameType
stack type (fifo, lifo). Determines which pushed items will be fetched first default is lifo
allowed values are lifo fifo
stack_order STRING
Publish/Subscribe Services
Data stack user API
Data is stored on a per user basis. However, notifications can be sent to a configurable set of listeners.
Stack names are arbitrary and do not need to be explicitly initialized.
Access control
Impersonation is possible : use the owner field for each eligible request.
Impersonating users need to be granted rights on resources with this syntax : deploymentId:owner:stack
pub
getListeners
Lists the listeners
Implementation notes
Returns the whole list of listeners for the given stack.
Access control
Impersonating users need to be granted rights on action 'getListeners'
Parameter
The parameter has the type StackRequest
StackRequest
NameDescriptionTypeRequired
stack Stack name. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type StackListeners.
The result is only sent to the user session who made the call.
StackListeners
NameDescriptionType
listeners List of userKeys (as in the value of __userKey) or fully qualified group names (the syntax is groupServiceDeploymentId:userKey:group) that will be notified of modifying stack operations Set[String]
stack Stack name. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
list
Lists content
Implementation notes
Returns a paginated list of contents for the given stack.
Content is sorted according to the statically configured order.
Access control
Impersonating users need to be granted rights on action 'list'
Parameter
The parameter has the type StackListRequest
StackListRequest
NameDescriptionTypeRequired
stack Stack name. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
page Pagination information Pagination optional
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionTypeRequired
pageSize Page size (minimum 1) int optional
pageNumber Page number (zero-based) int optional
direction Sort direction. Default is ASC when not specified. PageDirection optional
Primary output
The response has the type StackListResponse.
The result is only sent to the user session who made the call.
StackListResponse
NameDescriptionType
request Request leading to the result StackListRequest
result Result for the specified request PageContent[StackItem]
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
StackItem
NameDescriptionType
guid Server-generated GUID byte[]
ts Insertion timestamp long
data Stored data Map[String,Object]
StackListRequest
NameDescriptionType
stack Stack name. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
page Pagination information Pagination
pub
purge
Empties a stack
Implementation notes
Removes all items from the given stack.
Access control
Impersonating users need to be granted rights on action 'purge'
Parameter
The parameter has the type StackRequest
StackRequest
NameDescriptionTypeRequired
stack Stack name. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type StackRequest.
The result is sent to a list of users : the defined listeners, or the owner of the stack if no listeners are defined.
StackRequest
NameDescriptionType
stack Stack name. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
push
Pushes an item
Implementation notes
Pushes an item onto the given stack.
The stack does not need to be created.
Access control
Impersonating users need to be granted rights on action 'push'
Parameter
The parameter has the type StackItemAdd
StackItemAdd
NameDescriptionTypeRequired
stack Stack name. String required
data Stored data Map[String,Object] required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type StackItemAdd.
The result is sent to a list of users : the defined listeners, or the owner of the stack if no listeners are defined.
StackItemAdd
NameDescriptionType
guid Key of this stack item byte[]
stack Stack name. String
data Stored data Map[String,Object]
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
remove
Removes items
Implementation notes
Removes the item with the given guid from the given stack.
Access control
Impersonating users need to be granted rights on action 'remove'
Parameter
The parameter has the type StackItemRemove
StackItemRemove
NameDescriptionTypeRequired
guids List of keys of the items to be removed List[byte[]] required
stack Stack name. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type StackItemRemove.
The result is sent to a list of users : the defined listeners, or the owner of the stack if no listeners are defined.
StackItemRemove
NameDescriptionType
guids List of keys of the items to be removed List[byte[]]
stack Stack name. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
setListeners
Sets the listeners
Implementation notes
Sets the listeners for the given stack.
Access control
Impersonating users need to be granted rights on action 'setListeners'
Parameter
The parameter has the type StackListeners
StackListeners
NameDescriptionTypeRequired
listeners List of userKeys (as in the value of __userKey) or fully qualified group names (the syntax is groupServiceDeploymentId:userKey:group) that will be notified of modifying stack operations Set[String] optional
stack Stack name. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type StackListeners.
The result is only sent to the user session who made the call.
StackListeners
NameDescriptionType
listeners List of userKeys (as in the value of __userKey) or fully qualified group names (the syntax is groupServiceDeploymentId:userKey:group) that will be notified of modifying stack operations Set[String]
stack Stack name. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
update
Updates an item
Implementation notes
Updates an existing item of the given stack.
The item MUST exist prior to the call.
Access control
Impersonating users need to be granted rights on action 'update'
Parameter
The parameter has the type StackItemAdd
StackItemAdd
NameDescriptionTypeRequired
guid Key of this stack item. byte[] required
stack Stack name. String required
data Stored data Map[String,Object] required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type StackItemAdd.
The result is sent to a list of users : the defined listeners, or the owner of the stack if no listeners are defined.
StackItemAdd
NameDescriptionType
guid Key of this stack item byte[]
stack Stack name. String
data Stored data Map[String,Object]
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Echo
Configuration options
DescriptionValueNameType
boolean indicating whether the service should be deployed as rest also default is false
 
echo_rest_enabled BOOLEAN
Publish/Subscribe Services
Echo service
Simple echo service, for development purposes.
pub
echo
Echoes an object
Implementation notes
Echoes an object: the server will echo that object on channel 'echo' for the current user.
Parameter
The parameter has the type Map[String,Object]
Primary output
The response has the type Map[String,Object].
The result is only sent to the user session who made the call.
Abstract Game Engine. Concrete game engines are remote cometd clients or internal macros
HTTP Controllers
Experimental API for administrative game engine macros registration.
EXPERIMENTAL. DO NOT actually use in production.
POST
/game/registerGame
Registers a game engine
Audience
The API /game/registerGame is reserved to developers
Implementation notes
Registers the coordinates of a game engine.
Errors
No documented error codes.
Request body
The request body has the type GameRunnerRegistration
GameRunnerRegistration
NameDescriptionTypeRequired
maxGames Maximum number of simultaneous games that the registering runner can handle int optional
gameInfo Game Type information GameInfo required
location Location of the engine. The server will fill it if left null. GameRunnerFullLocation optional
GameInfo
NameDescriptionTypeRequired
description Game description String optional
commands Available commands when playing Map[String,String] optional
name Game type identifier String optional
options Available options whan creating Map[String,String] optional
GameRunnerFullLocation
NameDescriptionTypeRequired
sessionId Session identifier of the game engine. Server-attributed String optional
requestChannel Reserved for future use String optional
responseChannel Reserved for future use String optional
setiId Seti identifier of the game engine. Server-attributed String optional
Response
The response body has the type void
Publish/Subscribe Services
Game Engine API
The Game Engine API is for game engine clients, not end-users.
pub
join_result
Notify the result for a join request
Implementation notes
A Game Engine notifies the STR of the result of a join request that it received on join_callback
Parameter
The parameter has the type GameJoinResponse
GameJoinResponse
NameDescriptionTypeRequired
msgId unique ID for this message, matching the request ID String optional
payload response payload GameJoin optional
error error message String optional
callerId caller ID from the original request String optional
GameJoin
NameDescriptionTypeRequired
role Optional role for the player. Meaning is game specific String optional
gameId Server attributed game identifier String optional
userId User unique key String optional
userName Player name inside the game String optional
pub
organize_result
Notify the result for an organization request
Implementation notes
A Game Engine notifies the STR of the result of an organization request that it received on organize_callback
Parameter
The parameter has the type GameOrganizationResponse
GameOrganizationResponse
NameDescriptionTypeRequired
msgId unique ID for this message, matching the request ID String optional
payload response payload GameOrganization optional
error error message String optional
callerId caller ID from the original request String optional
GameOrganization
NameDescriptionTypeRequired
type Game type GameType required
gameId Game identifier String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
options Game creation options Map[String,Object] optional
GameType
NameDescriptionTypeRequired
description Game description String optional
name Game type identifier String optional
pub
register
Registers a game engine
Implementation notes
A client registers itself to the STR as a Game Engine.
The STR may, from now on, dispatch game of the given game type to said client.
Unregistration is done automatically on logoff.
Parameter
The parameter has the type GameRunnerRegistration
GameRunnerRegistration
NameDescriptionTypeRequired
maxGames Maximum number of simultaneous games that the registering runner can handle int optional
gameInfo Game Type information GameInfo required
location Location of the engine. The server will fill it if left null. GameRunnerFullLocation optional
GameInfo
NameDescriptionTypeRequired
description Game description String optional
commands Available commands when playing Map[String,String] optional
name Game type identifier String optional
options Available options whan creating Map[String,String] optional
GameRunnerFullLocation
NameDescriptionTypeRequired
sessionId Session identifier of the game engine. Server-attributed String optional
requestChannel Reserved for future use String optional
responseChannel Reserved for future use String optional
setiId Seti identifier of the game engine. Server-attributed String optional
pub
start_result
Notify the result for a start request
Implementation notes
A Game Engine notifies the STR of the result of a start request that it received on start_callback
Parameter
The parameter has the type GameStart
GameStart
NameDescriptionTypeRequired
gameId Server attributed game identifier String optional
pub
state
Notify a game event
Implementation notes
A Game Engine notifies the STR of some arbitrary game event.
Parameter
The parameter has the type GameState
GameState
NameDescriptionTypeRequired
status Current game status GameStatus optional
gameId Server attributed game identifier String optional
data Game specific data Map[String,Object] optional
GameStatus
String enumeration. Possible values are :
NameDescription
RUNNING The game is running
FINISHED The game is finished
CREATED The game has been created
STARTING The game is starting
pub
unjoin_result
Notify the result for an unjoin request
Implementation notes
A Game Engine notifies the STR of the result of an unjoin request that it received on unjoin_callback
Parameter
The parameter has the type GameJoinResponse
GameJoinResponse
NameDescriptionTypeRequired
msgId unique ID for this message, matching the request ID String optional
payload response payload GameJoin optional
error error message String optional
callerId caller ID from the original request String optional
GameJoin
NameDescriptionTypeRequired
role Optional role for the player. Meaning is game specific String optional
gameId Server attributed game identifier String optional
userId User unique key String optional
userName Player name inside the game String optional
notif
organize_callback
STR notifies the game engine to provide result to an organization request
Notification
The output
  • is on channel organize_callback
  • has the type GameOrganizationWithCallback
  • is for the current user
STR notifies the game engine to provide result to an organization request
GameOrganizationWithCallback
NameDescriptionType
msgId unique ID for this message String
payload message payload GameOrganization
callerId callback info String
GameOrganization
NameDescriptionType
type Game type GameType
gameId Game identifier String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
options Game creation options Map[String,Object]
GameType
NameDescriptionType
description Game description String
name Game type identifier String

notif
join_callback
STR notifies the game engine to provide result to a join request
Notification
The output
  • is on channel join_callback
  • has the type GameJoinWithCallback
  • is for the current user
STR notifies the game engine to provide result to a join request
GameJoinWithCallback
NameDescriptionType
msgId unique ID for this message String
payload message payload GameJoin
callerId callback info String
GameJoin
NameDescriptionType
role Optional role for the player. Meaning is game specific String
gameId Server attributed game identifier String
userId User unique key String
userName Player name inside the game String

notif
unjoin_callback
STR notifies the game engine to provide result to an unjoin request
Notification
The output
  • is on channel unjoin_callback
  • has the type GameJoinWithCallback
  • is for the current user
STR notifies the game engine to provide result to an unjoin request
GameJoinWithCallback
NameDescriptionType
msgId unique ID for this message String
payload message payload GameJoin
callerId callback info String
GameJoin
NameDescriptionType
role Optional role for the player. Meaning is game specific String
gameId Server attributed game identifier String
userId User unique key String
userName Player name inside the game String

notif
start_callback
STR notifies the game engine to provide result to a start request
Notification
The output
  • is on channel start_callback
  • has the type GameStart
  • is for the current user
STR notifies the game engine to provide result to a start request
GameStart
NameDescriptionType
gameId Server attributed game identifier String

notif
play_callback
STR notifies the game engine to provide result to a play request
Notification
The output
  • is on channel play_callback
  • has the type GamePlay
  • is for the current user
STR notifies the game engine to provide result to a play request
GamePlay
NameDescriptionType
gameId Server attributed game identifier String
userId User unique key String
data Game-specific data Map[String,Object]

User API for games
Users can list, start, join games, and play.
pub
available
Lists game types
Implementation notes
Returns the list of game types supported by the server and the currently registered game engines.
Primary output
The response has the type List[GameInfo].
The result is only sent to the user session who made the call.
GameInfo
NameDescriptionType
description Game description String
commands Available commands when playing Map[String,String]
name Game type identifier String
options Available options whan creating Map[String,String]
pub
join
A user joins a game
Implementation notes
Parameter
The parameter has the type GameJoin
GameJoin
NameDescriptionTypeRequired
role Optional role for the player. Meaning is game specific String optional
gameId Server attributed game identifier String optional
userId User unique key String optional
userName Player name inside the game String optional
Outputs
The output
  • is on channel join
  • has the type GameJoin
  • is for the current user
A user has joined a game
GameJoin
NameDescriptionType
role Optional role for the player. Meaning is game specific String
gameId Server attributed game identifier String
userId User unique key String
userName Player name inside the game String

pub
organize
Organizes a game
Implementation notes
Parameter
The parameter has the type GameOrganization
GameOrganization
NameDescriptionTypeRequired
type Game type GameType required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
options Game creation options Map[String,Object] optional
GameType
NameDescriptionTypeRequired
description Game description String optional
name Game type identifier String optional
Outputs
The output
  • is on channel organize
  • has the type GameOrganization
  • is for the current user
Game is organized
GameOrganization
NameDescriptionType
type Game type GameType
gameId Game identifier String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
options Game creation options Map[String,Object]
GameType
NameDescriptionType
description Game description String
name Game type identifier String

Error codes
CodeDescription
NOT_FOUNDGame type not found
pub
play
Gives some command to the game engine
Implementation notes
Parameter
The parameter has the type GamePlay
GamePlay
NameDescriptionTypeRequired
gameId Server attributed game identifier String optional
userId User unique key String optional
data Game-specific data Map[String,Object] optional
Outputs
The output
  • is on channel play
  • has the type GamePlay
  • is for the current user
A command has been played by the game engine
GamePlay
NameDescriptionType
gameId Server attributed game identifier String
userId User unique key String
data Game-specific data Map[String,Object]

pub
start
Starts a game
Implementation notes
Parameter
The parameter has the type GameStart
GameStart
NameDescriptionTypeRequired
gameId Server attributed game identifier String optional
Outputs
The output
  • is on channel start
  • has the type GameStart
  • is for the current user
A game has started
GameStart
NameDescriptionType
gameId Server attributed game identifier String

pub
unjoin
A user cancels joining a game
Implementation notes
Parameter
The parameter has the type GameJoin
GameJoin
NameDescriptionTypeRequired
role Optional role for the player. Meaning is game specific String optional
gameId Server attributed game identifier String optional
userId User unique key String optional
userName Player name inside the game String optional
Outputs
The output
  • is on channel unjoin
  • has the type GameJoin
  • is for the current user
A user leaved a game
GameJoin
NameDescriptionType
role Optional role for the player. Meaning is game specific String
gameId Server attributed game identifier String
userId User unique key String
userName Player name inside the game String

notif
state
Notify a game event
Notification
The output
  • is on channel state
  • has the type GameState
  • is for the current user
Notify a game event
GameState
NameDescriptionType
status Current game status GameStatus
gameId Server attributed game identifier String
data Game specific data Map[String,Object]
GameStatus
String enumeration. Possible values are :
NameDescription
RUNNING The game is running
FINISHED The game is finished
CREATED The game has been created
STARTING The game is starting

Generic Data Access Service : NoSQL storage
HTTP Controllers
Administrative API for data access management.
You can create and list tables
At the moment, no admin API is provided for data provisionning, but you can always use an initialization macro in your recipe.
POST
/gda/addColumns
Alters a table (adds columns)
Audience
The API /gda/addColumns is reserved to developers
Use in recipes
The API /gda/addColumns is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Alters an existing table, with the given columns.
The given columns are added to the existing list of columns.
The given columns MUST NOT exist.
Adding non existing columns WILL cause the whole table to be unavailable for up to one minute.
This API never deletes columns.
Errors
No documented error codes.
Request body
The request body has the type GdaTableModification
GdaTableModification
NameDescriptionTypeRequired
columns List of column specifications List[GdaTableColumn] required
name Table name String required
idempotence Specify the behavior when the table already exists. The default value is IGNORE_DIFFERENT.IGNORE_IDENTICAL ignores all pre-existing (identical or additional) columns, but does not allow to change or add columns.IGNORE_DIFFERENT ignores all pre-existing (identical or additional) columns, can add columns, but does not allow to change column types. Idempotence optional
GdaDataType
String enumeration. Possible values are :
NameDescription
LONG 64-bit signed integer. This is the only eligible type for the 'inc' API call
STRING Character String
BOOLEAN Boolean value : true or false
DOUBLE Floating point number
OBJECT Complex object
GdaTableColumn
NameDescriptionTypeRequired
type Column type GdaDataType required
name Column name String required
map False if the column contains a single piece of data or true when it can contain several data, mapped by (sub-)keys. Defaults to 'false' boolean optional
Idempotence
String enumeration. Possible values are :
NameDescription
IGNORE_DIFFERENT The operation will not fail if the entity already exists in a different and compatible form.
FAIL_IF_EXISTING The operation will fail if the entity already exists
IGNORE_IDENTICAL The operation will not fail if the entity already exists in a similar form.
Response
The response body has the type void
POST
/gda/createTable
Creates a new table
Audience
The API /gda/createTable is reserved to developers
Use in recipes
The API /gda/createTable is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Creates a table, with the given structure.
A table consists of a name and column definitions. You can provide as many columns as you wish.
This API never deletes columns.
Errors
No documented error codes.
Request body
The request body has the type GdaTableModification
GdaTableModification
NameDescriptionTypeRequired
columns List of column specifications List[GdaTableColumn] required
name Table name String required
idempotence Specify the behavior when the table already exists. The default value is IGNORE_DIFFERENT.IGNORE_IDENTICAL ignores all pre-existing (identical or additional) columns, but does not allow to change or add columns.IGNORE_DIFFERENT ignores all pre-existing (identical or additional) columns, can add columns, but does not allow to change column types. Idempotence optional
GdaDataType
String enumeration. Possible values are :
NameDescription
LONG 64-bit signed integer. This is the only eligible type for the 'inc' API call
STRING Character String
BOOLEAN Boolean value : true or false
DOUBLE Floating point number
OBJECT Complex object
GdaTableColumn
NameDescriptionTypeRequired
type Column type GdaDataType required
name Column name String required
map False if the column contains a single piece of data or true when it can contain several data, mapped by (sub-)keys. Defaults to 'false' boolean optional
Idempotence
String enumeration. Possible values are :
NameDescription
IGNORE_DIFFERENT The operation will not fail if the entity already exists in a different and compatible form.
FAIL_IF_EXISTING The operation will fail if the entity already exists
IGNORE_IDENTICAL The operation will not fail if the entity already exists in a similar form.
Response
The response body has the type void
GET
/gda/listTables
Lists tables
Audience
The API /gda/listTables is reserved to developers
Implementation notes
Returns a non paginated list of all defined tables.
You can use this for a bulk export of your table definitions.
Errors
No documented error codes.
Response
The response body has the type Collection[GdaTableStructure]
GdaDataType
String enumeration. Possible values are :
NameDescription
LONG 64-bit signed integer. This is the only eligible type for the 'inc' API call
STRING Character String
BOOLEAN Boolean value : true or false
DOUBLE Floating point number
OBJECT Complex object
GdaTableColumn
NameDescriptionType
type Column type GdaDataType
name Column name String
map False if the column contains a single piece of data or true when it can contain several data, mapped by (sub-)keys. Defaults to 'false' boolean
GdaTableStructure
NameDescriptionType
columns List of column specifications List[GdaTableColumn]
name Table name String
POST
/gda/removeColumns
Alters a table (removes columns)
Audience
The API /gda/removeColumns is reserved to developers
Implementation notes
Alters an existing table, with the given removed columns.
The given columns are removed from the existing list of columns.
The given columns MUST exist.
Errors
No documented error codes.
Request body
The request body has the type GdaRemoveColumns
GdaRemoveColumns
NameDescriptionTypeRequired
columns List of column names Set[String] required
name Table name String required
Response
The response body has the type void
POST
/gda/removeTable
Removes a table
Audience
The API /gda/removeTable is reserved to developers
Implementation notes
Removes an existing table.
Errors
No documented error codes.
Request body
The request body has the type GdaTableRemoval
GdaTableRemoval
NameDescriptionTypeRequired
name Table name String required
Response
The response body has the type void
Publish/Subscribe Services
GDA User API
User API for Generic Data Access.
The data are stored on a per-user basis.
Users can put, get, list their data.
HTTP Access
This service's verbs are also exposed via HTTP for convenience during development and testing.
  • http:///str/restd/BU_ID/depId5/get
  • http:///str/restd/BU_ID/depId5/getCells
  • http:///str/restd/BU_ID/depId5/inc
  • http:///str/restd/BU_ID/depId5/list
  • http:///str/restd/BU_ID/depId5/mget
  • http:///str/restd/BU_ID/depId5/put
  • http:///str/restd/BU_ID/depId5/puts
  • http:///str/restd/BU_ID/depId5/range
  • http:///str/restd/BU_ID/depId5/removeCell
  • http:///str/restd/BU_ID/depId5/removeColumn
  • http:///str/restd/BU_ID/depId5/removeRange
  • http:///str/restd/BU_ID/depId5/removeRow
Access control
Impersonation is possible : use the owner field for each eligible request.
Impersonating users need to be granted rights on resources with this syntax : deploymentId:owner:table
server
filter
Filters a range of rows
Implementation notes
Similar to range, but rows can be filtered out according to a developer-supplied predicate.
A range consists of consecutive rows from the start key (inclusive) to the stop key (exclusive).
You can specify partial keys for the start and stop fields.
Access control
Impersonating users need to be granted rights on action 'filter'
Parameter
The parameter has the type GdaFilterRequest
GdaFilterRequest
NameDescriptionTypeRequired
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec] optional
start Start row key (inclusive) String required
table Table name String required
stop Stop row key (exclusive) String required
function Boolean predicate. The function must accept one parameter : the current row. The return value must be a boolean. When true, the row is retained, otherwise it is filtered out. Object optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
page Pagination information Pagination optional
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionTypeRequired
key2 Optional list of cell names List[String] optional
column Mandatory column name String required
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionTypeRequired
pageSize Page size (minimum 1) int optional
pageNumber Page number (zero-based) int optional
direction Sort direction. Default is ASC when not specified. PageDirection optional
Primary output
The response has the type GdaFilterResult.
The result is only sent to the user session who made the call.
GdaFilterResult
NameDescriptionType
request Request leading to the result GdaFilterRequest
result Result for the specified request PageContent[Map[String,Object]]
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionType
key2 Optional list of cell names List[String]
column Mandatory column name String
GdaFilterRequest
NameDescriptionType
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec]
start Start row key (inclusive) String
table Table name String
stop Stop row key (exclusive) String
function Boolean predicate. The function must accept one parameter : the current row. The return value must be a boolean. When true, the row is retained, otherwise it is filtered out. Object
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
page Pagination information Pagination
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
get
Asks for a data row
Implementation notes
Returns a full data row.
Access control
Impersonating users need to be granted rights on action 'get'
Parameter
The parameter has the type GdaGet
GdaGet
NameDescriptionTypeRequired
table Table name String required
key Row key String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GdaGetResult.
The result is only sent to the user session who made the call.
GdaGetResult
NameDescriptionType
request Request leading to the result GdaGet
result Result for the specified request Map[String,Object]
GdaGet
NameDescriptionType
table Table name String
key Row key String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
getCells
Asks for a data cell
Implementation notes
Returns a precise list of cells from a column in a data row.
Access control
Impersonating users need to be granted rights on action 'getCells'
Parameter
The parameter has the type GdaCellsRequest
GdaCellsRequest
NameDescriptionTypeRequired
table Table name String required
key Row key String required
key2 cell keys inside the column List[String] required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
column column name inside the row String required
Primary output
The response has the type GdaCellsResult.
The result is only sent to the user session who made the call.
GdaCellsResult
NameDescriptionType
request Request leading to the result GdaCellsRequest
result Result for the specified request Object
GdaCellsRequest
NameDescriptionType
table Table name String
key Row key String
key2 cell keys inside the column List[String]
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
column column name inside the row String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
inc
Increments an integer value
Implementation notes
Increments a cell 64-bit signed integer value and returns the result in the data field.
The increment is atomic : if you concurrently increment 10 times a value by 1, the final result will be the initial value plus 10. The actual individual resulting values seen by the 10 concurrent callers may vary discontinuously, with duplicates : at least one of them will see the final (+10) result.
Access control
Impersonating users need to be granted rights on action 'inc'
Parameter
The parameter has the type GdaPut
GdaPut
NameDescriptionTypeRequired
table Table name String required
data stored data. 64-bit signed integer value interpreted as a delta. This delta increments the specified field. Object required
key Row key String required
key2 optional cell key inside the column String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
column column name inside the row String required
Primary output
The response has the type GdaPut.
The result is sent to all live connections of the user.
GdaPut
NameDescriptionType
table Table name String
data stored data Object
key Row key String
key2 optional cell key inside the column String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
column column name inside the row String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
NO_SUCH_COLUMNHappens when the specified column does not exist (columns are defined by a createTable or addColumns call).
BAD_COLUMNHappens when the input data is incorrect for the specified column
pub
list
Asks for a list of rows
Implementation notes
Returns a paginated list of rows from the given table.
Access control
Impersonating users need to be granted rights on action 'list'
Parameter
The parameter has the type GdaList
GdaList
NameDescriptionTypeRequired
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec] optional
table Table name String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
page Pagination information Pagination optional
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionTypeRequired
key2 Optional list of cell names List[String] optional
column Mandatory column name String required
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionTypeRequired
pageSize Page size (minimum 1) int optional
pageNumber Page number (zero-based) int optional
direction Sort direction. Default is ASC when not specified. PageDirection optional
Primary output
The response has the type GdaListResult.
The result is only sent to the user session who made the call.
GdaListResult
NameDescriptionType
request Request leading to the result GdaList
result Result for the specified request PageContent[Map[String,Object]]
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionType
key2 Optional list of cell names List[String]
column Mandatory column name String
GdaList
NameDescriptionType
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec]
table Table name String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
page Pagination information Pagination
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
mget
Asks for several data rows
Implementation notes
Returns full data rows, in the order they were asked.
Access control
Impersonating users need to be granted rights on action 'mget'
Parameter
The parameter has the type GdaMultiGetRequest
GdaMultiGetRequest
NameDescriptionTypeRequired
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec] optional
table Table name String required
keys List of wanted row keys List[String] required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionTypeRequired
key2 Optional list of cell names List[String] optional
column Mandatory column name String required
Primary output
The response has the type GdaMultiGetResult.
The result is only sent to the user session who made the call.
GdaMultiGetResult
NameDescriptionType
request Request leading to the result GdaMultiGetRequest
result Result for the specified request List[Map[String,Object]]
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionType
key2 Optional list of cell names List[String]
column Mandatory column name String
GdaMultiGetRequest
NameDescriptionType
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec]
table Table name String
keys List of wanted row keys List[String]
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
put
Puts some data into a cell
Implementation notes
Creates or replaces the contents of a particular cell.
Access control
Impersonating users need to be granted rights on action 'put'
Parameter
The parameter has the type GdaPut
GdaPut
NameDescriptionTypeRequired
table Table name String required
data stored data Object required
key Row key String required
key2 optional cell key inside the column String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
column column name inside the row String required
Primary output
The response has the type GdaPut.
The result is sent to all live connections of the user.
GdaPut
NameDescriptionType
table Table name String
data stored data Object
key Row key String
key2 optional cell key inside the column String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
column column name inside the row String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
NO_SUCH_COLUMNHappens when the specified column does not exist (columns are defined by a createTable or addColumns call).
pub
puts
Puts several rows
Implementation notes
Creates or replaces the (maybe partial) contents of a collection of rows.
This method only creates or replaces cells for non-null input values.
Access control
Impersonating users need to be granted rights on action 'puts'
Parameter
The parameter has the type GdaPuts
GdaPuts
NameDescriptionTypeRequired
rows Rows to be inserted List[GdaPutsRow] required
table Table name String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
GdaPutsRow
NameDescriptionTypeRequired
data Stored data, as a map of columns to values Map[String,Object] required
key Row key String required
Primary output
The response has the type GdaPutsResult.
The result is sent to all live connections of the user.
GdaPutsResult
NameDescriptionType
inserted Number of inserted rows long
table Table name String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
NO_SUCH_COLUMNHappens when the specified column does not exist (columns are defined by a createTable or addColumns call).
pub
range
Asks for a range of rows
Implementation notes
Returns a paginated range of rows from the given table.
A range consists of consecutive rows from the start key (inclusive) to the stop key (exclusive).
You can specify partial keys for the start and stop fields.
Access control
Impersonating users need to be granted rights on action 'range'
Parameter
The parameter has the type GdaRange
GdaRange
NameDescriptionTypeRequired
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec] optional
start Start row key (inclusive) String required
table Table name String required
stop Stop row key (exclusive) String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
page Pagination information Pagination optional
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionTypeRequired
key2 Optional list of cell names List[String] optional
column Mandatory column name String required
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionTypeRequired
pageSize Page size (minimum 1) int optional
pageNumber Page number (zero-based) int optional
direction Sort direction. Default is ASC when not specified. PageDirection optional
Primary output
The response has the type GdaRangeResult.
The result is only sent to the user session who made the call.
GdaRangeResult
NameDescriptionType
request Request leading to the result GdaRange
result Result for the specified request PageContent[Map[String,Object]]
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionType
key2 Optional list of cell names List[String]
column Mandatory column name String
GdaRange
NameDescriptionType
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec]
start Start row key (inclusive) String
table Table name String
stop Stop row key (exclusive) String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
page Pagination information Pagination
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
server
reduce
Reduces a range of rows
Implementation notes
Returns a computed single reduced result from a range of rows from the given table.
A range consists of consecutive rows from the start key (inclusive) to the stop key (exclusive).
You can specify partial keys for the start and stop fields.
Access control
Impersonating users need to be granted rights on action 'reduce'
Parameter
The parameter has the type GdaReduceRequest
GdaReduceRequest
NameDescriptionTypeRequired
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec] optional
start Start row key (inclusive) String required
initialValue Initial value for the computation function. Example : {sum:0, mean:null} Map[String,Object] optional
table Table name String required
stop Stop row key (exclusive) String required
function Computation function. The function must accept two parameters : the current value and the current row. The return value is ignored : the current value must be updated instead. Object optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
page Pagination information Pagination optional
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionTypeRequired
key2 Optional list of cell names List[String] optional
column Mandatory column name String required
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionTypeRequired
pageSize Page size (minimum 1) int optional
pageNumber Page number (zero-based) int optional
direction Sort direction. Default is ASC when not specified. PageDirection optional
Primary output
The response has the type GdaReduceResult.
The result is only sent to the user session who made the call.
GdaReduceResult
NameDescriptionType
request Request leading to the result GdaReduceRequest
result Result for the specified request Map[String,Object]
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionType
key2 Optional list of cell names List[String]
column Mandatory column name String
GdaReduceRequest
NameDescriptionType
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec]
start Start row key (inclusive) String
initialValue Initial value for the computation function. Example : {sum:0, mean:null} Map[String,Object]
table Table name String
stop Stop row key (exclusive) String
function Computation function. The function must accept two parameters : the current value and the current row. The return value is ignored : the current value must be updated instead. Object
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
removeCell
Removes one cell inside a column of a row
Implementation notes
Removes only one cell of the given column of the given row from the given table.
Access control
Impersonating users need to be granted rights on action 'removeCell'
Parameter
The parameter has the type GdaCellRequest
GdaCellRequest
NameDescriptionTypeRequired
table Table name String required
key Row key String required
key2 cell key inside the column String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
column column name inside the row String required
Primary output
The response has the type GdaCellRequest.
The result is sent to all live connections of the user.
GdaCellRequest
NameDescriptionType
table Table name String
key Row key String
key2 cell key inside the column String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
column column name inside the row String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
removeColumn
Removes one full column of a row
Implementation notes
Removes all cells of the given column of the given row from the given table.
Access control
Impersonating users need to be granted rights on action 'removeColumn'
Parameter
The parameter has the type GdaColumnRequest
GdaColumnRequest
NameDescriptionTypeRequired
table Table name String required
key Row key String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
column column name inside the row String required
Primary output
The response has the type GdaColumnRequest.
The result is sent to all live connections of the user.
GdaColumnRequest
NameDescriptionType
table Table name String
key Row key String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
column column name inside the row String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
removeRange
Removes a range of rows
Implementation notes
Removes the specified columns of the given range of rows from the given table.
Access control
Impersonating users need to be granted rights on action 'removeRange'
Parameter
The parameter has the type GdaRemoveRange
GdaRemoveRange
NameDescriptionTypeRequired
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec] optional
start Start row key String required
table Table name String required
stop Stop row key String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionTypeRequired
key2 Optional list of cell names List[String] optional
column Mandatory column name String required
Primary output
The response has the type GdaRemoveRange.
The result is sent to all live connections of the user.
GdaRemoveRange
NameDescriptionType
columns Optional column/cell specifications of the columns/cells to retrieve List[GdaColumnSpec]
start Start row key String
table Table name String
stop Stop row key String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
GdaColumnSpec
When you fill only the 'column' field, instead of giving an actual full object, you can directly use the value of the field itself, without an object or a field name.
Instead of {"column": "foo"}, you can write "foo"
NameDescriptionType
key2 Optional list of cell names List[String]
column Mandatory column name String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
pub
removeRow
Removes one full row
Implementation notes
Removes all columns of the given row from the given table.
Access control
Impersonating users need to be granted rights on action 'removeRow'
Parameter
The parameter has the type GdaRowRequest
GdaRowRequest
NameDescriptionTypeRequired
table Table name String required
key Row key String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GdaRowRequest.
The result is sent to all live connections of the user.
GdaRowRequest
NameDescriptionType
table Table name String
key Row key String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Error codes
CodeDescription
NO_TABLEHappens when the specified table does not exist (tables are created by a createTable call).
Groups management for users, grants on resources, remote commands on devices. This is where you can configure rights for any resource.
Configuration options
DescriptionValueNameType
Notify group owner of presence of members when they log in or out default is false
 
groups_presence_owner BOOLEAN
Notify group members of presence of members when they log in or out default is false
 
groups_presence_group BOOLEAN
HTTP Controllers
Administrative Group Management
You can manage all the groups of all your users from here: create, delete, add users, grant or revoke rights.
When using the administrative API, the 'owner' field is mandatory and MUST NOT be null.
You also can configure additional things: grants on global groups, using the wildcard '*' as the group's owner.
POST
/groups/addUser
Adds a user to a group
Audience
The API /groups/addUser is reserved to developers
Use in recipes
The API /groups/addUser is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Adds the given user to given group for the given owner, or for a global group.
Addition may fail if the group does not exist.
Errors
No documented error codes.
Request body
The request body has the type UserGroup
UserGroup
NameDescriptionTypeRequired
user The user's key (as in __userKey). String required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user. String required
Response
The response body has the type UserGroup
UserGroup
NameDescriptionType
user The user's key (as in __userKey) String
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
GET
/groups/allGroups
Lists all the groups
Audience
The API /groups/allGroups is reserved to developers
Implementation notes
Returns the paginated list of all groups.
Errors
No documented error codes.
Response
The response body has the type PageContent[GroupInfo]
GroupInfo
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
POST
/groups/create
Creates a group
Audience
The API /groups/create is reserved to developers
Use in recipes
The API /groups/create is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Creates a new group for the given owner, or a global group.
Creation may fail if the group already exists or if the group id does not follow the naming rules
Errors
No documented error codes.
Request body
The request body has the type GroupInfo
GroupInfo
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
groupName Group name, as displayed to the user String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user. String required
Response
The response body has the type GroupInfo
GroupInfo
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
POST
/groups/delUser
Removes a user from a group
Audience
The API /groups/delUser is reserved to developers
Implementation notes
Removes the given user from the given group for the given owner, or for a global group.
Errors
No documented error codes.
Request body
The request body has the type UserGroup
UserGroup
NameDescriptionTypeRequired
user The user's key (as in __userKey) String optional
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Response
The response body has the type void
POST
/groups/deleteGroup
Removes a group
Audience
The API /groups/deleteGroup is reserved to developers
Implementation notes
Removes an existing group for the given owner, or a global group.
Errors
No documented error codes.
Request body
The request body has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Response
The response body has the type void
POST
/groups/grant
Grants rights to a group
Audience
The API /groups/grant is reserved to developers
Use in recipes
The API /groups/grant is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Grants the given rights to the given group for the given owner, or for a global group.
Errors
No documented error codes.
Request body
The request body has the type Grants
Grants
NameDescriptionTypeRequired
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String required
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String] required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user. String required
Response
The response body has the type Grants
Grants
NameDescriptionType
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
POST
/groups/grants
Lists the grants for a group
Audience
The API /groups/grants is reserved to developers
Implementation notes
Lists all the grants that have been previously given by 'grant' to the given group for the given owner, or for a global group.
Listing may fail if the group does not exist.
Errors
No documented error codes.
Request body
The request body has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Response
The response body has the type GrantList
GrantList
NameDescriptionType
grants List of granted rights List[GrantListItem]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
GrantListItem
NameDescriptionType
resource Configured authorized resource String
action Configured authorized action String
POST
/groups/groupUsers
Lists the users of a group
Audience
The API /groups/groupUsers is reserved to developers
Implementation notes
Lists all the users of the given group for the given owner, or for a global group.
Listing may fail if the group does not exist.
Errors
No documented error codes.
Request body
The request body has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Response
The response body has the type GroupUsers
GroupUsers
NameDescriptionType
users User keys of the group members List[String]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
GET
/groups/groups/{owner}
Lists the groups of a user
Audience
The API /groups/groups/{owner} is reserved to developers
Implementation notes
Returns the whole list of groups for the given owner.
Errors
No documented error codes.
Response
The response body has the type List[GroupInfo]
GroupInfo
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Path parameters
DescriptionNameType
Owner of the groups to be listedownerString
POST
/groups/revoke
Revokes a right for a group
Audience
The API /groups/revoke is reserved to developers
Implementation notes
Revokes the given rights, previously given with 'grant' to the given group for the given owner, or for a global group.
Errors
No documented error codes.
Request body
The request body has the type Grants
Grants
NameDescriptionTypeRequired
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String required
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String] required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Response
The response body has the type Grants
Grants
NameDescriptionType
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Publish/Subscribe Services
User API for remote control
pub
addListener
Adds a listener
Implementation notes
A user requests notifications from a device owned by anyone who granted him the right authorizations.
Whenever the device calls 'notify', notifications will be sent to the caller of this verb.
Parameter
The parameter has the type RemoteCommand
RemoteCommand
NameDescriptionTypeRequired
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String optional
fromResource Resource of the user issuing the command String optional
cmd Command to be executed. This is an arbitrary identifier string whose semantics are left to the developer. String required
from User issuing the command String optional
data Optional data payload for the command. This is an arbitrary object whose semantics are left to the developer. Map[String,Object] optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
pub
capabilities
Response to 'getCapabilities'
Implementation notes
Parameter
The parameter has the type DeviceCapabilities
DeviceCapabilities
NameDescriptionTypeRequired
askingResource Resource name of the asking device String optional
capabilities List of capabilities. Capabilities are developer-defined strings List[String] optional
answeringResource Resource name of the answering device String optional
Outputs
The output
  • is on channel capabilities
  • has the type DeviceCapabilities
  • is for the current user
Response to 'getCapabilities'
DeviceCapabilities
NameDescriptionType
askingResource Resource name of the asking device String
capabilities List of capabilities. Capabilities are developer-defined strings List[String]
answeringResource Resource name of the answering device String

pub
execute
Executes a command
Implementation notes
A user executes a command on a device owned by anyone who granted him the right authorizations.
The command is issued on channel 'command'
Parameter
The parameter has the type RemoteCommand
RemoteCommand
NameDescriptionTypeRequired
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String optional
cmd Command to be executed. This is an arbitrary identifier string whose semantics are left to the developer. String required
data Optional data payload for the command. This is an arbitrary object whose semantics are left to the developer. Map[String,Object] optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user. Target device's user key String optional
Outputs
The output
  • is on channel execute
  • has the type RemoteCommand
  • is for the current user
Notifies when a command has been executed
RemoteCommand
NameDescriptionType
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String
fromResource Resource of the user issuing the command String
cmd Command to be executed. This is an arbitrary identifier string whose semantics are left to the developer. String
from User issuing the command String
data Optional data payload for the command. This is an arbitrary object whose semantics are left to the developer. Map[String,Object]
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String

pub
getCapabilities
Requests capabilities
Implementation notes
A user requests all his devices for the whole list of their capabilities.
Devices are expected to answer on channel 'capabilities'
Outputs
The output
  • is on channel getCapabilities
  • has the type DeviceCapabilities
  • is for the current user
Notifies with all device capabilities for the user
DeviceCapabilities
NameDescriptionType
askingResource Resource name of the asking device String
capabilities List of capabilities. Capabilities are developer-defined strings List[String]
answeringResource Resource name of the answering device String

pub
notify
Notifies of some event
Implementation notes
A device notifies the registered users/devices on this channel.
The server forwards the notification to said users.
Parameter
The parameter has the type RemoteCommand
RemoteCommand
NameDescriptionTypeRequired
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String optional
fromResource Resource of the user issuing the command String optional
cmd Command to be executed. This is an arbitrary identifier string whose semantics are left to the developer. String required
from User issuing the command String optional
data Optional data payload for the command. This is an arbitrary object whose semantics are left to the developer. Map[String,Object] optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Outputs
The output
  • is on channel notify
  • has the type RemoteCommand
  • is for the current user
Notifies of some event
RemoteCommand
NameDescriptionType
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String
fromResource Resource of the user issuing the command String
cmd Command to be executed. This is an arbitrary identifier string whose semantics are left to the developer. String
from User issuing the command String
data Optional data payload for the command. This is an arbitrary object whose semantics are left to the developer. Map[String,Object]
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String

pub
ping
Pings devices
Implementation notes
A user requests all devices (of all owners) on which he has authorizations to respond on channel 'pong'
Parameter
The parameter has the type PingRequest
PingRequest
NameDescriptionTypeRequired
action The action to probe String required
Outputs
The output
  • is on channel ping
  • has the type DeviceAvailability
  • is for the current user
Notifies of ping
DeviceAvailability
NameDescriptionType
user User inquiring about availability String
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String
available Whether the device is available or not boolean
uid Session id of the answering device String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
action Action for which the device's availability is tested String

pub
pong
Response to ping
Implementation notes
Parameter
The parameter has the type DeviceAvailability
DeviceAvailability
NameDescriptionTypeRequired
user User inquiring about availability String optional
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String optional
available Whether the device is available or not boolean optional
uid Session id of the answering device String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
action Action for which the device's availability is tested String optional
Outputs
The output
  • is on channel pong
  • has the type DeviceAvailability
  • is for the current user
Response to ping
DeviceAvailability
NameDescriptionType
user User inquiring about availability String
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String
available Whether the device is available or not boolean
uid Session id of the answering device String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
action Action for which the device's availability is tested String

pub
removeListener
Removes a listener
Implementation notes
A user stops requesting notifications from a device owned by anyone who granted him the right authorizations
Parameter
The parameter has the type RemoteCommand
RemoteCommand
NameDescriptionTypeRequired
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String optional
fromResource Resource of the user issuing the command String optional
cmd Command to be executed. This is an arbitrary identifier string whose semantics are left to the developer. String required
from User issuing the command String optional
data Optional data payload for the command. This is an arbitrary object whose semantics are left to the developer. Map[String,Object] optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
User API for groups and rights.
Groups are stored per user.
This means that two users can own a group with the same identifier. A couple (owner, group) is needed to uniquely identify a group inside a group management service.
The triplet (deploymentId, owner, group) is actually needed to fully qualify a group outside of the scope of this service.
Access control
Impersonation is possible : use the owner field for each eligible request.
Impersonating users need to be granted rights on resources with this syntax : owner:group
pub
addMe
Adds me to a group
Implementation notes
Adds me (the caller) to a group.
This verb exists so that group owners may grant the right to join their groups without granting the right to add other users to those groups.
The 'user' field is implicitly set to the current user's key.
Access control
Impersonating users need to be granted rights on action 'ADDMYSELF'
Parameter
The parameter has the type UserGroup
UserGroup
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type UserGroup.
The result is sent to all live connections of the user.
UserGroup
NameDescriptionType
user The user's key (as in __userKey) String
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
addUser
Adds a user to a group
Implementation notes
Adds the given user to the given group.
Addition may fail if the given group does not already exist.
Access control
Impersonating users need to be granted rights on action 'WRITE'
Parameter
The parameter has the type UserGroup
UserGroup
NameDescriptionTypeRequired
user The user's key (as in __userKey). String required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type UserGroup.
The result is sent to all live connections of the user.
UserGroup
NameDescriptionType
user The user's key (as in __userKey) String
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
addUsers
Adds users to a group
Implementation notes
Users are processed in the given order
In case of failure in the middle of a user list, this verb may have succeeded to add the first users, but will not continue processing the end of the list.
Access control
Impersonating users need to be granted rights on action 'WRITE'
Parameter
The parameter has the type GroupUsers
GroupUsers
NameDescriptionTypeRequired
users User keys of the group members List[String] optional
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Outputs
The output
  • is on channel addUser
  • has the type UserGroup
  • is for the current user
UserGroup
NameDescriptionType
user The user's key (as in __userKey) String
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String

pub
allGroups
Lists my owned groups, with details
Implementation notes
Returns the whole list of groups owned by the current user, with their members
Access control
Impersonating users need to be granted rights on action 'LIST'
Parameter
The parameter has the type ImpersonatedRequest
ImpersonatedRequest
NameDescriptionTypeRequired
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type List[GroupUsers].
The result is only sent to the user session who made the call.
GroupUsers
NameDescriptionType
users User keys of the group members List[String]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
server
check
Checks an authorization
Implementation notes
This API checks if the given user has the proper authorizations to perform the given action on the owner's resource.
If you give the same value for 'user' and 'owner', the check always passes.
Parameter
The parameter has the type GrantCheckRequest
GrantCheckRequest
NameDescriptionTypeRequired
user The user needing authorization String optional
resource The resource to check String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
action The action to check String optional
Primary output
The response has the type GrantCheckResult.
The result is only sent to the user session who made the call.
GrantCheckResult
NameDescriptionType
request The request GrantCheckRequest
ok True when the check passed boolean
GrantCheckRequest
NameDescriptionType
user The user needing authorization String
resource The resource to check String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
action The action to check String
pub
createGroup
Creates a group
Implementation notes
Creates a group owned by the current user.
Group creation may fail if the group already exists.
Access control
Impersonating users need to be granted rights on action 'WRITE'
Parameter
The parameter has the type GroupInfo
GroupInfo
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
groupName Group name, as displayed to the user String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GroupInfo.
The result is sent to all live connections of the user.
GroupInfo
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Error codes
CodeDescription
BAD_INPUT_DATAMissing group id.
BAD_NAMEGroup id must be alphanumerical.
pub
delGroup
Removes a group
Implementation notes
Removes the given group owned by the current user or the given owner.
Also removes all grants to that group.
Access control
Impersonating users need to be granted rights on action 'WRITE'
Parameter
The parameter has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GroupRelated.
The result is sent to all live connections of the user.
GroupRelated
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
delUser
Removes a user from a group
Implementation notes
Access control
Impersonating users need to be granted rights on action 'WRITE'
Parameter
The parameter has the type UserGroup
UserGroup
NameDescriptionTypeRequired
user The user's key (as in __userKey) String optional
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type UserGroup.
The result is sent to all live connections of the user.
UserGroup
NameDescriptionType
user The user's key (as in __userKey) String
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
delUsers
Removes users from a group
Implementation notes
Access control
Impersonating users need to be granted rights on action 'WRITE'
Parameter
The parameter has the type GroupUsers
GroupUsers
NameDescriptionTypeRequired
users User keys of the group members List[String] optional
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
groupName Group name, as displayed to the user String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
pub
exists
Tests for a group's existence
Implementation notes
Returns whether a group exists or not.
Access control
Impersonating users need to be granted rights on action 'LIST'
Parameter
The parameter has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GroupExistence.
The result is only sent to the user session who made the call.
GroupExistence
NameDescriptionType
exists Existence of the group boolean
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
grant
Grants a right to a group
Implementation notes
The granting API does not do any check when storing permissions.
In particular when granting rights on a verb and resource of another API, the existence of said verb and resource is not checked.
Access control
Impersonating users need to be granted rights on action 'GRANT'
Parameter
The parameter has the type Grant
Grant
NameDescriptionTypeRequired
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
action Action which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' String required
Primary output
The response has the type Grant.
The result is sent to all live connections of the user.
Grant
NameDescriptionType
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
action Action which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' String
pub
groupUsers
Lists the group users
Implementation notes
Returns the whole list of users configured inside the given group.
Access control
Impersonating users need to be granted rights on action 'LIST'
Parameter
The parameter has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GroupUsers.
The result is only sent to the user session who made the call.
GroupUsers
NameDescriptionType
users User keys of the group members List[String]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
groups
Lists my owned groups
Implementation notes
Returns the whole list of groups owned by the current user
Access control
Impersonating users need to be granted rights on action 'LIST'
Parameter
The parameter has the type ImpersonatedRequest
ImpersonatedRequest
NameDescriptionTypeRequired
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type List[GroupInfo].
The result is only sent to the user session who made the call.
GroupInfo
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
listGrants
Lists rights for a group
Implementation notes
This API lists explicitly configured rights.
Effective rights include configured rights, implicit rights and inherited rights.
Access control
Impersonating users need to be granted rights on action 'LIST'
Parameter
The parameter has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GrantList.
The result is only sent to the user session who made the call.
GrantList
NameDescriptionType
grants List of granted rights List[GrantListItem]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
GrantListItem
NameDescriptionType
resource Configured authorized resource String
action Configured authorized action String
pub
listPresences
Lists presences for a group
Implementation notes
Returns the list of members of the given groups, along with their actual and current presence on the zetapush server.
The current implementation does not include information about the particular devices users are connected with.
If a user is connected twice with two different devices, two identical entries will be returned.
Access control
Impersonating users need to be granted rights on action 'LIST'
Parameter
The parameter has the type GroupRelated
GroupRelated
NameDescriptionTypeRequired
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type GroupPresence.
The result is only sent to the user session who made the call.
GroupPresence
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
presences List of group users, with their presence information. List[Presence]
GroupRelated
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
OwnerResource
NameDescriptionType
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
Presence
NameDescriptionType
user User information OwnerResource
presence Presence status. OFF or ON String
group Group information GroupRelated
pub
memberOf
Tests membership
Implementation notes
Tests whether I (the caller) am a member of the given group.
This verb exists so that users can determine if they are part of a group without being granted particular rights.
The 'user' field is implicitly set to the current user's key.
Parameter
The parameter has the type UserMembership
UserMembership
NameDescriptionTypeRequired
hardFail True if lack of effective membership should be treated as an error. False to return the information as a boolean in the response. boolean optional
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type UserGroupMembership.
The result is sent to all live connections of the user.
UserGroupMembership
NameDescriptionType
user The user's key (as in __userKey) String
member Whether the user is member of the group boolean
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
mgrant
Grants rights to a group
Implementation notes
Grant several rights at once.
Access control
Impersonating users need to be granted rights on action 'GRANT'
Parameter
The parameter has the type Grants
Grants
NameDescriptionTypeRequired
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String required
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String] required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type Grants.
The result is sent to all live connections of the user.
Grants
NameDescriptionType
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
mrevoke
Revokes rights for a group
Implementation notes
Access control
Impersonating users need to be granted rights on action 'GRANT'
Parameter
The parameter has the type Grants
Grants
NameDescriptionTypeRequired
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String required
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String] required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type Grants.
The result is sent to all live connections of the user.
Grants
NameDescriptionType
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String
actions Actions which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' List[String]
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
myGroups
Lists the groups I am part of
Implementation notes
Returns the whole list of groups the current user is part of.
Groups may be owned by anyone, including the current user.
Access control
Impersonating users need to be granted rights on action 'LIST'
Parameter
The parameter has the type ImpersonatedRequest
ImpersonatedRequest
NameDescriptionTypeRequired
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type List[GroupInfo].
The result is only sent to the user session who made the call.
GroupInfo
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
groupName Group name, as displayed to the user String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
pub
revoke
Revokes a right for a group
Implementation notes
Access control
Impersonating users need to be granted rights on action 'GRANT'
Parameter
The parameter has the type Grant
Grant
NameDescriptionTypeRequired
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String required
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
action Action which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' String required
Primary output
The response has the type Grant.
The result is sent to all live connections of the user.
Grant
NameDescriptionType
resource Resource on which the grant applies. For API defined resources, it often has the syntax deploymentId:owner:preciseResource. For example to give access to a gda table, it may look like 'WxzV:wshwWSDOJSD:myTable' , WxzV being the gda deploymentId, wshwWSDOJSD the data owner, and myTable the table to be shared. For grants on user devices, it can match the resource field used during authentication. You can use the wildcard '*' String
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
action Action which will be authorized. For built-in API verbs, it is often the verb itself. You can use the wildcard '*' String
notif
presence
Notification
The output
  • is on channel presence
  • has the type Presence
  • is for either a group's members or a group owner, or both, depending on the configuration of this service
This notification is automatically sent each time a user connects.
It will be sent to the members of the groups the user is member of, and to the owners of those groups (depending on service configuration).
One notification per group is sent.
Presence
NameDescriptionType
user User information OwnerResource
presence Presence status. OFF or ON String
group Group information GroupRelated
GroupRelated
NameDescriptionType
group Group id. Must be alphanumerical. You MAY use the wildcard '*' when granting rights. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
OwnerResource
NameDescriptionType
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String

Web-service client. An admin records URL templates that can be called by users. Calls are not configurable by end-users. However an admin may leverage the macro service to achieve URL, headers and body configurability
Configuration options
DescriptionValueNameType
HTTP timeout (milliseconds). 5000 ms by default default is 5000
 
http_client_timeout LONG
HTTP Controllers
Administrative API for the http client
Here you can manage predefined http requests.
POST
/http/create
Stores a request
Audience
The API /http/create is reserved to developers
Implementation notes
Stores an http request template.
This API can only be used for static requests ; use the real-time API for dynamic behaviour.
Errors
No documented error codes.
Request body
The request body has the type HttpClientTemplate
HttpClientTemplate
NameDescriptionTypeRequired
content Request body. String (passed as is) or complex object (serialized to json) Object optional
name Name of the request template (primary key) String required
headers Headers to be sent List[HttpClientHeader] optional
method HTTP method String required
parseMode How to parse the response content HttpClientParseMode required
url Remote URL. a literal string String required
HttpClientHeader
NameDescriptionTypeRequired
value Header value String optional
name Header name String required
HttpClientParseMode
String enumeration. Possible values are :
NameDescription
STRING Content is interpreted as a UTF8 character string
OBJECT Content is parsed as UTF8 JSON
BYTES Content is not interpreted, but available as a raw array of bytes
Response
The response body has the type void
GET
/http/delete/{name}
Deletes a request
Audience
The API /http/delete/{name} is reserved to developers
Implementation notes
Deletes an existing request template with the given 'name'.
Errors
No documented error codes.
Response
The response body has the type void
Path parameters
DescriptionNameType
no descriptionnameString
GET
/http/list
Lists the requests
Audience
The API /http/list is reserved to developers
Implementation notes
Returns a paginated list of defined request templates.
Errors
No documented error codes.
Response
The response body has the type PageContent[HttpClientTemplate]
HttpClientHeader
NameDescriptionType
value Header value String
name Header name String
HttpClientParseMode
String enumeration. Possible values are :
NameDescription
STRING Content is interpreted as a UTF8 character string
OBJECT Content is parsed as UTF8 JSON
BYTES Content is not interpreted, but available as a raw array of bytes
HttpClientTemplate
NameDescriptionType
content Request body. String (passed as is) or complex object (serialized to json) Object
name Name of the request template (primary key) String
headers Headers to be sent List[HttpClientHeader]
method HTTP method String
parseMode How to parse the response content HttpClientParseMode
url Remote URL. a literal string String
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
Publish/Subscribe Services
User API for http requests
HTTP Access
This service's verbs are also exposed via HTTP for convenience during development and testing.
  • http:///str/restd/BU_ID/depId17/call
pub
call
Makes a predefined request
Implementation notes
Lookups a predefined request by name, and executes it.
Parameter
The parameter has the type HttpClientCall
HttpClientCall
NameDescriptionTypeRequired
name name of the configured template String required
requestId optional client generated call ID to identify responses String optional
Primary output
The response has the type HttpClientResponse.
The result is only sent to the user session who made the call.
HttpClientResponse
NameDescriptionType
content received content Object
headers received headers List[HttpClientHeader]
httpStatus response http status code int
requestId optional client generated call ID to identify responses String
HttpClientHeader
NameDescriptionType
value Header value String
name Header name String
Error codes
CodeDescription
NOT_FOUNDThe predefined request was not found.
BAD_FORMATThe given body could not be converted to a stream of bytes.
server
request
Makes a parameterized request
Implementation notes
Executes an HTTP request with the given url, method, headers and body.
Parameter
The parameter has the type HttpClientRequest
HttpClientRequest
NameDescriptionTypeRequired
content Request body. String (passed as is) or complex object (serialized to json) Object optional
headers Headers to be sent List[HttpClientHeader] optional
method HTTP method String required
requestId optional client generated call ID to identify responses String optional
parseMode How to parse the response content HttpClientParseMode required
url Remote URL. a literal string String required
HttpClientHeader
NameDescriptionTypeRequired
value Header value String optional
name Header name String required
HttpClientParseMode
String enumeration. Possible values are :
NameDescription
STRING Content is interpreted as a UTF8 character string
OBJECT Content is parsed as UTF8 JSON
BYTES Content is not interpreted, but available as a raw array of bytes
Primary output
The response has the type HttpClientResponse.
The result is only sent to the user session who made the call.
HttpClientResponse
NameDescriptionType
content received content Object
headers received headers List[HttpClientHeader]
httpStatus response http status code int
requestId optional client generated call ID to identify responses String
HttpClientHeader
NameDescriptionType
value Header value String
name Header name String
Error codes
CodeDescription
NOT_FOUNDThe predefined request was not found.
BAD_FORMATThe given body could not be converted to a stream of bytes.
server
soap
Makes a soap request
Implementation notes
Executes an HTTP SOAP request with the given url, method, headers and body.
Parameter
The parameter has the type HttpClientSOAPRequest
HttpClientSOAPRequest
NameDescriptionTypeRequired
soapHeaders Soap headers : the content of <soapenv:Header> List[Object] optional
soapFaults List of possible soap fault classes for this request List[SoapFaultDefinition] optional
content Request body. String (passed as is) or complex object (serialized to json) Object optional
typeDefinition Type reference, as returned in ZMS by 'YourClassName.class' MacroTypeDefinition optional
headers Headers to be sent List[HttpClientHeader] optional
soapAction SOAP action, as defined in the WSDL, for inclusion in the generated request headers String optional
url Remote URL. a literal string String required
requestWrapperNamespace Use when the xml root type does not declare any namespace, but does need it String optional
HttpClientHeader
NameDescriptionTypeRequired
value Header value String optional
name Header name String required
MacroScriptParam
NameDescriptionTypeRequired
name Parameter name String optional
constraints Optional parameter constraints List[MacroScriptParamConstraint] optional
MacroScriptParamConstraint
NameDescriptionTypeRequired
config Constraint configuration Map[String,Object] optional
name Constraint name String optional
MacroTypeDefinition
NameDescriptionTypeRequired
fields List of field definitions List[MacroScriptParam] optional
name Type name String optional
thisObject Initializer. contains class common fields, copied into each new instance Map[String,Object] optional
SoapFaultDefinition
NameDescriptionTypeRequired
type missing field desc MacroTypeDefinition required
targetNamespace missing field desc String optional
Primary output
The response has the type HttpClientSOAPResponse.
The result is only sent to the user session who made the call.
HttpClientSOAPResponse
NameDescriptionType
content received content Object
fault missing field desc SoapFault
headers received headers List[HttpClientHeader]
httpStatus response http status code int
requestId optional client generated call ID to identify responses String
HttpClientHeader
NameDescriptionType
value Header value String
name Header name String
SoapFault
NameDescriptionType
detail missing field desc List[Object]
faultcode missing field desc String
faultstring missing field desc String
Error codes
CodeDescription
NOT_FOUNDThe predefined request was not found.
BAD_FORMATThe given body could not be converted to a stream of bytes.
server
test
TEST soap marshalling
Implementation notes
Parameter
The parameter has the type HttpClientSOAPRequest
HttpClientSOAPRequest
NameDescriptionTypeRequired
soapHeaders Soap headers : the content of <soapenv:Header> List[Object] optional
soapFaults List of possible soap fault classes for this request List[SoapFaultDefinition] optional
content Request body. String (passed as is) or complex object (serialized to json) Object optional
typeDefinition Type reference, as returned in ZMS by 'YourClassName.class' MacroTypeDefinition optional
headers Headers to be sent List[HttpClientHeader] optional
soapAction SOAP action, as defined in the WSDL, for inclusion in the generated request headers String optional
url Remote URL. a literal string String required
requestWrapperNamespace Use when the xml root type does not declare any namespace, but does need it String optional
HttpClientHeader
NameDescriptionTypeRequired
value Header value String optional
name Header name String required
MacroScriptParam
NameDescriptionTypeRequired
name Parameter name String optional
constraints Optional parameter constraints List[MacroScriptParamConstraint] optional
MacroScriptParamConstraint
NameDescriptionTypeRequired
config Constraint configuration Map[String,Object] optional
name Constraint name String optional
MacroTypeDefinition
NameDescriptionTypeRequired
fields List of field definitions List[MacroScriptParam] optional
name Type name String optional
thisObject Initializer. contains class common fields, copied into each new instance Map[String,Object] optional
SoapFaultDefinition
NameDescriptionTypeRequired
type missing field desc MacroTypeDefinition required
targetNamespace missing field desc String optional
Primary output
The response has the type SoapTest.
The result is only sent to the user session who made the call.
SoapTest
NameDescriptionType
content missing field desc String
Macro-command service. An admin defines macro-commands that can sequentially call any number of other api verbs, loop on collections of data, make decisions, etc... End-users play them, with contextual parameters
HTTP Controllers
Administrative API for macros
Manage your macro definitions here.
Create, validate, delete and list macros.
These APIs are used by the eclipse plugin and the CLI : most users will never use them directly.
POST
/macro/create
Creates a macro
Audience
The API /macro/create is reserved to developers
Implementation notes
Creates or updates a macro definition.
Errors
No documented error codes.
Request body
The request body has the type MacroInfo
MacroInfo
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
target Target for the response (the syntax is the same as in messaging.send). Overrides 'broadcast' when set. Object optional
channel Optional return channel. Defaults to completed String optional
name Macro name String required
result Optional macro result Map[String,Object] optional
userKey Setting this field effectively overrides the __userKey pseudo-constant for the duration of the macro. All non-sudoed internal calls will behave as if sudoed with the given user key. When this field is set, there is not point in calling this macro with sudo String optional
source source file (for debug) String optional
steps Sub steps, sequentially executed List[MacroStep] required
returned Optional output field specifications List[MacroScriptParam] optional
params Optional parameter specifications List[MacroScriptParam] optional
broadcast Whether to broadcast to all the user's sessions, or just to the asking session. Defaults to false (request-response paradigm). boolean optional
line Line number in source file int optional
MacroBlock
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroCall
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
suKey Key of the impersonated user String optional
noExpand Specifies whether parameter expansion should be avoided. The server will of course set this to true automatically if no refs are present. Defaults to false boolean optional
resultName Name of the result, for future reference String optional
parameter Parameter that will be passed to the verb. The format is the format expected by the target verb, with the following exception : any field can be replaced by a placeholder. A placeholder is an object with a '__ref' field. The value of the ref field follows java EL syntax with some pre-defined objects and functions (see the documentation on macros) Map[String,Object] optional
deploymentId DeploymentId of the service to be called String required
line Line number in source file int optional
verb Verb to be called inside the specified service String required
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
MacroFunction
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
parameters Function parameters List[MacroFunctionParam] optional
name Function name String required
result Function result Object required
source source file String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroFunctionParam
NameDescriptionTypeRequired
name Parameter name String optional
MacroJump
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
type jump type Type required
line Line number in source file int optional
MacroLocalFunction
NameDescriptionTypeRequired
f Function definition MacroFunction required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Function local name String required
line Line number in source file int optional
MacroLog
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
data Data to be logged. The server will fail to produce an accurate result if the actual evaluated data is too big. Object optional
line Line number in source file int optional
MacroLoop
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Loop variable String required
items Collection to iterate on String required
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroScriptParam
NameDescriptionTypeRequired
name Parameter name String optional
constraints Optional parameter constraints List[MacroScriptParamConstraint] optional
MacroScriptParamConstraint
NameDescriptionTypeRequired
config Constraint configuration Map[String,Object] optional
name Constraint name String optional
MacroStatement
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
exec Statement to be executed String required
line Line number in source file int optional
MacroStep ( Subclasses : MacroCall MacroInfo MacroTest MacroLog MacroVariable MacroLoop MacroLocalFunction MacroStatement MacroJump )
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
line Line number in source file int optional
MacroTest
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
otherwise Else MacroBlock optional
line Line number in source file int optional
condition Macro step condition. when evaluated to true, allows for execution of the steps String required
MacroVariable
NameDescriptionTypeRequired
value value to be evaluated Object required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Variable identifier String required
line Line number in source file int optional
Type
String enumeration. Possible values are :
NameDescription
BREAK missing enum desc
CONTINUE missing enum desc
Response
The response body has the type void
GET
/macro/delete/{name}
Deletes a macro
Audience
The API /macro/delete/{name} is reserved to developers
Implementation notes
Deletes the macro with the given 'name'.
Errors
No documented error codes.
Response
The response body has the type void
Path parameters
DescriptionNameType
Macro identifiernameString
ALL
/macro/exec/**
Runs a macro
Audience
The API /macro/exec/** is publicly accessible
Implementation notes
Runs the configured macro for the given route /macro/exec/{route}.
The HTTP POST body is expected to be a JSON object
The route (after '/exec/') may contain slashes
A route is configured along with a macro when it is created
The macro is run with the parameters you annotate with @RequestBody, @QueryParam, @RequestParam, @PathParam, @PathVariable, @HeaderParam, @RequestHeader, @Path.
Errors
No documented error codes.
Request body
The request body has the type Map[String,Object]
Response
The response body has the type DeferredResult[HttpEntity[ConfigurableHttpOutput]]
ConfigurableHttpOutput
NameDescriptionType
data missing field desc Object
GET
/macro/list
Lists the macros
Audience
The API /macro/list is reserved to developers
Implementation notes
Returns the whole list of defined macros.
Errors
No documented error codes.
Response
The response body has the type List[MacroInfo]
MacroBlock
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
steps Sub steps, sequentially executed List[MacroStep]
line Line number in source file int
MacroCall
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
suKey Key of the impersonated user String
noExpand Specifies whether parameter expansion should be avoided. The server will of course set this to true automatically if no refs are present. Defaults to false boolean
resultName Name of the result, for future reference String
parameter Parameter that will be passed to the verb. The format is the format expected by the target verb, with the following exception : any field can be replaced by a placeholder. A placeholder is an object with a '__ref' field. The value of the ref field follows java EL syntax with some pre-defined objects and functions (see the documentation on macros) Map[String,Object]
deploymentId DeploymentId of the service to be called String
line Line number in source file int
verb Verb to be called inside the specified service String
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean
MacroFunction
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
parameters Function parameters List[MacroFunctionParam]
name Function name String
result Function result Object
source source file String
steps Sub steps, sequentially executed List[MacroStep]
line Line number in source file int
MacroFunctionParam
NameDescriptionType
name Parameter name String
MacroInfo
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
target Target for the response (the syntax is the same as in messaging.send). Overrides 'broadcast' when set. Object
channel Optional return channel. Defaults to completed String
name Macro name String
result Optional macro result Map[String,Object]
userKey Setting this field effectively overrides the __userKey pseudo-constant for the duration of the macro. All non-sudoed internal calls will behave as if sudoed with the given user key. When this field is set, there is not point in calling this macro with sudo String
source source file (for debug) String
steps Sub steps, sequentially executed List[MacroStep]
returned Optional output field specifications List[MacroScriptParam]
params Optional parameter specifications List[MacroScriptParam]
broadcast Whether to broadcast to all the user's sessions, or just to the asking session. Defaults to false (request-response paradigm). boolean
line Line number in source file int
MacroJump
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
type jump type Type
line Line number in source file int
MacroLocalFunction
NameDescriptionType
f Function definition MacroFunction
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
var Function local name String
line Line number in source file int
MacroLog
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
data Data to be logged. The server will fail to produce an accurate result if the actual evaluated data is too big. Object
line Line number in source file int
MacroLoop
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
var Loop variable String
items Collection to iterate on String
steps Sub steps, sequentially executed List[MacroStep]
line Line number in source file int
MacroScriptParam
NameDescriptionType
name Parameter name String
constraints Optional parameter constraints List[MacroScriptParamConstraint]
MacroScriptParamConstraint
NameDescriptionType
config Constraint configuration Map[String,Object]
name Constraint name String
MacroStatement
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
exec Statement to be executed String
line Line number in source file int
MacroStep ( Subclasses : MacroCall MacroInfo MacroTest MacroLog MacroVariable MacroLoop MacroLocalFunction MacroStatement MacroJump )
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
line Line number in source file int
MacroTest
NameDescriptionType
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
steps Sub steps, sequentially executed List[MacroStep]
otherwise Else MacroBlock
line Line number in source file int
condition Macro step condition. when evaluated to true, allows for execution of the steps String
MacroVariable
NameDescriptionType
value value to be evaluated Object
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String
var Variable identifier String
line Line number in source file int
Type
String enumeration. Possible values are :
NameDescription
BREAK missing enum desc
CONTINUE missing enum desc
POST
/macro/mcreate
Creates macros
Audience
The API /macro/mcreate is reserved to developers
Use in recipes
The API /macro/mcreate is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Creates or updates several macro definitions.
Errors
No documented error codes.
Request body
The request body has the type MacroInfos
MacroInfos
NameDescriptionTypeRequired
macros List of macros List[MacroInfo] optional
purge Whether to wipe out all existing macros before taking the given ones into account boolean optional
functions List of functions List[MacroFunction] optional
deploymentId Deployment ID of the macro service String optional
globals Global data Map[String,Object] optional
types List of user types List[MacroTypeDefinition] optional
MacroBlock
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroCall
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
suKey Key of the impersonated user String optional
noExpand Specifies whether parameter expansion should be avoided. The server will of course set this to true automatically if no refs are present. Defaults to false boolean optional
resultName Name of the result, for future reference String optional
parameter Parameter that will be passed to the verb. The format is the format expected by the target verb, with the following exception : any field can be replaced by a placeholder. A placeholder is an object with a '__ref' field. The value of the ref field follows java EL syntax with some pre-defined objects and functions (see the documentation on macros) Map[String,Object] optional
deploymentId DeploymentId of the service to be called String required
line Line number in source file int optional
verb Verb to be called inside the specified service String required
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
MacroFunction
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
parameters Function parameters List[MacroFunctionParam] optional
name Function name String required
result Function result Object required
source source file String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroFunctionParam
NameDescriptionTypeRequired
name Parameter name String optional
MacroInfo
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
target Target for the response (the syntax is the same as in messaging.send). Overrides 'broadcast' when set. Object optional
channel Optional return channel. Defaults to completed String optional
name Macro name String required
result Optional macro result Map[String,Object] optional
userKey Setting this field effectively overrides the __userKey pseudo-constant for the duration of the macro. All non-sudoed internal calls will behave as if sudoed with the given user key. When this field is set, there is not point in calling this macro with sudo String optional
source source file (for debug) String optional
steps Sub steps, sequentially executed List[MacroStep] required
returned Optional output field specifications List[MacroScriptParam] optional
params Optional parameter specifications List[MacroScriptParam] optional
broadcast Whether to broadcast to all the user's sessions, or just to the asking session. Defaults to false (request-response paradigm). boolean optional
line Line number in source file int optional
MacroJump
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
type jump type Type required
line Line number in source file int optional
MacroLocalFunction
NameDescriptionTypeRequired
f Function definition MacroFunction required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Function local name String required
line Line number in source file int optional
MacroLog
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
data Data to be logged. The server will fail to produce an accurate result if the actual evaluated data is too big. Object optional
line Line number in source file int optional
MacroLoop
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Loop variable String required
items Collection to iterate on String required
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroScriptParam
NameDescriptionTypeRequired
name Parameter name String optional
constraints Optional parameter constraints List[MacroScriptParamConstraint] optional
MacroScriptParamConstraint
NameDescriptionTypeRequired
config Constraint configuration Map[String,Object] optional
name Constraint name String optional
MacroStatement
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
exec Statement to be executed String required
line Line number in source file int optional
MacroStep ( Subclasses : MacroCall MacroInfo MacroTest MacroLog MacroVariable MacroLoop MacroLocalFunction MacroStatement MacroJump )
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
line Line number in source file int optional
MacroTest
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
otherwise Else MacroBlock optional
line Line number in source file int optional
condition Macro step condition. when evaluated to true, allows for execution of the steps String required
MacroTypeDefinition
NameDescriptionTypeRequired
fields List of field definitions List[MacroScriptParam] optional
name Type name String optional
thisObject Initializer. contains class common fields, copied into each new instance Map[String,Object] optional
MacroVariable
NameDescriptionTypeRequired
value value to be evaluated Object required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Variable identifier String required
line Line number in source file int optional
Type
String enumeration. Possible values are :
NameDescription
BREAK missing enum desc
CONTINUE missing enum desc
Response
The response body has the type MacroUploadReport
MacroUploadReport
NameDescriptionType
macros List of successfully uploaded macro names List[String]
functions List of successfully uploaded function names List[String]
POST
/macro/run
Runs an arbitrary macro
Audience
The API /macro/run is reserved to developers
Use in recipes
The API /macro/run is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Runs a macro.
Any given macro of the service can be called with any given user key.
Errors
No documented error codes.
Request body
The request body has the type SuMacroPlay
SuMacroPlay
NameDescriptionTypeRequired
parameters Macro named parameters Map[String,Object] optional
suKey Key of the impersonated user String required
hardFail True if an error should trigger a response on an error channel, or false (the default) if the error should be simply reported in an error field boolean optional
name Macro name String required
requestId User field for traceability of requests. This field is generated on the client side and must be unique. String optional
tempMacros Temporary macros. This feature does not support concurrent calls. List[MacroInfo] optional
debug Deprecated. Use the 'livedebug' API. int optional
MacroBlock
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroCall
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
suKey Key of the impersonated user String optional
noExpand Specifies whether parameter expansion should be avoided. The server will of course set this to true automatically if no refs are present. Defaults to false boolean optional
resultName Name of the result, for future reference String optional
parameter Parameter that will be passed to the verb. The format is the format expected by the target verb, with the following exception : any field can be replaced by a placeholder. A placeholder is an object with a '__ref' field. The value of the ref field follows java EL syntax with some pre-defined objects and functions (see the documentation on macros) Map[String,Object] optional
deploymentId DeploymentId of the service to be called String required
line Line number in source file int optional
verb Verb to be called inside the specified service String required
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
MacroFunction
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
parameters Function parameters List[MacroFunctionParam] optional
name Function name String required
result Function result Object required
source source file String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroFunctionParam
NameDescriptionTypeRequired
name Parameter name String optional
MacroInfo
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
target Target for the response (the syntax is the same as in messaging.send). Overrides 'broadcast' when set. Object optional
channel Optional return channel. Defaults to completed String optional
name Macro name String required
result Optional macro result Map[String,Object] optional
userKey Setting this field effectively overrides the __userKey pseudo-constant for the duration of the macro. All non-sudoed internal calls will behave as if sudoed with the given user key. When this field is set, there is not point in calling this macro with sudo String optional
source source file (for debug) String optional
steps Sub steps, sequentially executed List[MacroStep] required
returned Optional output field specifications List[MacroScriptParam] optional
params Optional parameter specifications List[MacroScriptParam] optional
broadcast Whether to broadcast to all the user's sessions, or just to the asking session. Defaults to false (request-response paradigm). boolean optional
line Line number in source file int optional
MacroJump
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
type jump type Type required
line Line number in source file int optional
MacroLocalFunction
NameDescriptionTypeRequired
f Function definition MacroFunction required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Function local name String required
line Line number in source file int optional
MacroLog
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
data Data to be logged. The server will fail to produce an accurate result if the actual evaluated data is too big. Object optional
line Line number in source file int optional
MacroLoop
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Loop variable String required
items Collection to iterate on String required
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroScriptParam
NameDescriptionTypeRequired
name Parameter name String optional
constraints Optional parameter constraints List[MacroScriptParamConstraint] optional
MacroScriptParamConstraint
NameDescriptionTypeRequired
config Constraint configuration Map[String,Object] optional
name Constraint name String optional
MacroStatement
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
exec Statement to be executed String required
line Line number in source file int optional
MacroStep ( Subclasses : MacroCall MacroInfo MacroTest MacroLog MacroVariable MacroLoop MacroLocalFunction MacroStatement MacroJump )
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
line Line number in source file int optional
MacroTest
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
otherwise Else MacroBlock optional
line Line number in source file int optional
condition Macro step condition. when evaluated to true, allows for execution of the steps String required
MacroVariable
NameDescriptionTypeRequired
value value to be evaluated Object required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Variable identifier String required
line Line number in source file int optional
Type
String enumeration. Possible values are :
NameDescription
BREAK missing enum desc
CONTINUE missing enum desc
Response
The response body has the type DeferredResult[MacroCompletion]
MacroCompletion
NameDescriptionType
stats Execution statistics, when debug is enabled MacroCompletionStats
errors Encountered errors. Error reporting behavior can be changed with the hardFail parameter. List[ZetaApiError]
name Macro name String
result Generated result, if applicable Object
requestId User field for traceability of requests. String
log Generated debug output, if applicable List[String]
MacroCompletionStats
NameDescriptionType
elapsedMillis Elapsed server time for the execution of the macro long
ram Total number of RAM bytes long
nbCalls Total number of called verbs long
cycles Total number of VM cycles long
ZetaApiError
NameDescriptionType
code Symbolic error code String
message Human readable message. May vary depending on one or more of locale, input, developer code. String
location Error location, if available String
POST
/macro/validate
Validates a macro
Audience
The API /macro/validate is reserved to developers
Implementation notes
Validates the macro syntax
Only validates the given AST, not the (unavailable) source code.
Errors
No documented error codes.
Request body
The request body has the type MacroInfo
MacroInfo
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
target Target for the response (the syntax is the same as in messaging.send). Overrides 'broadcast' when set. Object optional
channel Optional return channel. Defaults to completed String optional
name Macro name String required
result Optional macro result Map[String,Object] optional
userKey Setting this field effectively overrides the __userKey pseudo-constant for the duration of the macro. All non-sudoed internal calls will behave as if sudoed with the given user key. When this field is set, there is not point in calling this macro with sudo String optional
source source file (for debug) String optional
steps Sub steps, sequentially executed List[MacroStep] required
returned Optional output field specifications List[MacroScriptParam] optional
params Optional parameter specifications List[MacroScriptParam] optional
broadcast Whether to broadcast to all the user's sessions, or just to the asking session. Defaults to false (request-response paradigm). boolean optional
line Line number in source file int optional
MacroBlock
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroCall
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
suKey Key of the impersonated user String optional
noExpand Specifies whether parameter expansion should be avoided. The server will of course set this to true automatically if no refs are present. Defaults to false boolean optional
resultName Name of the result, for future reference String optional
parameter Parameter that will be passed to the verb. The format is the format expected by the target verb, with the following exception : any field can be replaced by a placeholder. A placeholder is an object with a '__ref' field. The value of the ref field follows java EL syntax with some pre-defined objects and functions (see the documentation on macros) Map[String,Object] optional
deploymentId DeploymentId of the service to be called String required
line Line number in source file int optional
verb Verb to be called inside the specified service String required
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
MacroFunction
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
parameters Function parameters List[MacroFunctionParam] optional
name Function name String required
result Function result Object required
source source file String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroFunctionParam
NameDescriptionTypeRequired
name Parameter name String optional
MacroJump
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
type jump type Type required
line Line number in source file int optional
MacroLocalFunction
NameDescriptionTypeRequired
f Function definition MacroFunction required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Function local name String required
line Line number in source file int optional
MacroLog
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
data Data to be logged. The server will fail to produce an accurate result if the actual evaluated data is too big. Object optional
line Line number in source file int optional
MacroLoop
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Loop variable String required
items Collection to iterate on String required
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroScriptParam
NameDescriptionTypeRequired
name Parameter name String optional
constraints Optional parameter constraints List[MacroScriptParamConstraint] optional
MacroScriptParamConstraint
NameDescriptionTypeRequired
config Constraint configuration Map[String,Object] optional
name Constraint name String optional
MacroStatement
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
exec Statement to be executed String required
line Line number in source file int optional
MacroStep ( Subclasses : MacroCall MacroInfo MacroTest MacroLog MacroVariable MacroLoop MacroLocalFunction MacroStatement MacroJump )
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
line Line number in source file int optional
MacroTest
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
otherwise Else MacroBlock optional
line Line number in source file int optional
condition Macro step condition. when evaluated to true, allows for execution of the steps String required
MacroVariable
NameDescriptionTypeRequired
value value to be evaluated Object required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Variable identifier String required
line Line number in source file int optional
Type
String enumeration. Possible values are :
NameDescription
BREAK missing enum desc
CONTINUE missing enum desc
Response
The response body has the type String
Administrative debug API for macros
Manage debug mode: enable, disable and report.
GET
/debug/disable
Disables debug mode
Audience
The API /debug/disable is reserved to developers
Implementation notes
Disables debug mode on this STR node : macro calls will no longer honor their 'debug' field.
Errors
No documented error codes.
Response
The response body has the type void
GET
/debug/enable
Enables debug mode
Audience
The API /debug/enable is reserved to developers
Implementation notes
Enables debug mode on this STR node : macro calls will now honor their 'debug' field.
Affects only new macro calls : macros already running continue unaffected.
Also enables live debug mode.
Errors
No documented error codes.
Response
The response body has the type void
GET
/debug/livedebugToken
Returns a debug token
Audience
The API /debug/livedebugToken is reserved to developers
Implementation notes
Returns a debug token, which is needed to initiate a debug session.
This verb does not enable the debug mode : the token is returned only when the debug mode has been enabled with /enable.
Treat the returned token as a secret, as it theoretically allows any end-user to debug any macro.
The token validity duration is limited.
Errors
No documented error codes.
Response
The response body has the type MacroDebugToken
MacroDebugToken
NameDescriptionType
token Token suitable for use by debug verbs String
GET
/debug/status
Returns the service status
Audience
The API /debug/status is reserved to developers
Implementation notes
Reports the status of this macro service on this STR node.
Errors
No documented error codes.
Response
The response body has the type MacroServiceStatus
MacroServiceStatus
NameDescriptionType
currentNb Number of macros currently running int
debug Whether this macro service is currently in debug mode boolean
totalNb Total number of macros currently running, including nested calls int
Publish/Subscribe Services
User API for macro execution
Simple errors are reported as usual.
However, the macro execution verbs treat most errors in a particular way : instead of reporting errors on the usual 'error' channel, errors are put in the returned 'MacroCompletion' result.
This behavior can be tuned on a per-call basis with the hardFail parameter.
Note that some particular errors will always behave as if hardFail were true, because they are related to programming errors, or prevent processing from ending gracefully : STACK_OVERFLOW, NO_SUCH_FUNCTION, RAM_EXCEEDED, CYCLES_EXCEEDED, TIME_EXCEEDED, QUOTA_EXCEEDED, RATE_EXCEEDED, BAD_COMPARATOR_VALUE
HTTP Access
This service's verbs are also exposed via HTTP for convenience during development and testing.
  • http:///str/restd/BU_ID/depId14/call
  • http:///str/restd/BU_ID/depId14/getPublicHttpUrl
pub
call
Plays a previously recorded macro
Implementation notes
DO NOT use this verb from inside an enclosing macro when you need the result in order to proceed with the enclosing macro.
You can override the default notification channel when defining the macro.
Parameter
The parameter has the type MacroPlay
MacroPlay
NameDescriptionTypeRequired
parameters Macro named parameters Map[String,Object] optional
hardFail True if an error should trigger a response on an error channel, or false (the default) if the error should be simply reported in an error field boolean optional
name Macro name String required
requestId User field for traceability of requests. This field is generated on the client side and must be unique. String optional
debug Deprecated. Use the 'livedebug' API. int optional
Outputs
The output
  • is on channel completed
  • has the type MacroCompletion
  • is for the current user
The macro is ran. Upon completion the caller is asynchronously notified.
MacroCompletion
NameDescriptionType
stats Execution statistics, when debug is enabled MacroCompletionStats
errors Encountered errors. Error reporting behavior can be changed with the hardFail parameter. List[ZetaApiError]
name Macro name String
result Generated result, if applicable Object
requestId User field for traceability of requests. String
log Generated debug output, if applicable List[String]
MacroCompletionStats
NameDescriptionType
elapsedMillis Elapsed server time for the execution of the macro long
ram Total number of RAM bytes long
nbCalls Total number of called verbs long
cycles Total number of VM cycles long
ZetaApiError
NameDescriptionType
code Symbolic error code String
message Human readable message. May vary depending on one or more of locale, input, developer code. String
location Error location, if available String

Error codes
CodeDescription
NOT_FOUNDA macro with the given name could not be found.
CAPACITY_EXCEEDEDThe macro execution engine allows only a fixed amount of macros to be run concurrently.
server
evaluate
Evaluates a function result.
Implementation notes
Parameter
The parameter has the type MacroFunctionRequest
MacroFunctionRequest
NameDescriptionTypeRequired
name Function name String required
params Function parameter values List[Object] required
Primary output
The response has the type MacroFunctionResult.
The result is only sent to the user session who made the call.
MacroFunctionResult
NameDescriptionType
result Function evaluation result Object
Error codes
CodeDescription
NOT_FOUNDA macro with the given name could not be found.
CAPACITY_EXCEEDEDThe macro execution engine allows only a fixed amount of macros to be run concurrently.
server
func
Plays a previously recorded macro and returns the result.
Implementation notes
Use this verb when you want to synchronously call a macro from inside another macro.
Despite being a server verb, func will honor the 'loud' modifier in ZMS.
Parameter
The parameter has the type MacroPlay
MacroPlay
NameDescriptionTypeRequired
parameters Macro named parameters Map[String,Object] optional
hardFail True if an error should trigger a response on an error channel, or false (the default) if the error should be simply reported in an error field boolean optional
name Macro name String required
requestId User field for traceability of requests. This field is generated on the client side and must be unique. String optional
debug Deprecated. Use the 'livedebug' API. int optional
Primary output
The response has the type MacroCompletion.
The result is only sent to the user session who made the call.
MacroCompletion
NameDescriptionType
stats Execution statistics, when debug is enabled MacroCompletionStats
errors Encountered errors. Error reporting behavior can be changed with the hardFail parameter. List[ZetaApiError]
name Macro name String
result Generated result, if applicable Object
requestId User field for traceability of requests. String
log Generated debug output, if applicable List[String]
MacroCompletionStats
NameDescriptionType
elapsedMillis Elapsed server time for the execution of the macro long
ram Total number of RAM bytes long
nbCalls Total number of called verbs long
cycles Total number of VM cycles long
ZetaApiError
NameDescriptionType
code Symbolic error code String
message Human readable message. May vary depending on one or more of locale, input, developer code. String
location Error location, if available String
Error codes
CodeDescription
NOT_FOUNDA macro with the given name could not be found.
CAPACITY_EXCEEDEDThe macro execution engine allows only a fixed amount of macros to be run concurrently.
pub
getPublicHttpUrl
Returns the base HTTP URL for 'macro/exec' in this macro service.
Implementation notes
Primary output
The response has the type MacroExecBaseUrl.
The result is only sent to the user session who made the call.
MacroExecBaseUrl
NameDescriptionType
url missing field desc String
Error codes
CodeDescription
NOT_FOUNDA macro with the given name could not be found.
CAPACITY_EXCEEDEDThe macro execution engine allows only a fixed amount of macros to be run concurrently.
server
sudo
Similar to func, with the ability to impersonate any user at will.
Deprecation
This API was deprecated:
Starting with STR v2.3.15 and plugin v1.1.53, all API calls can use the sudo keyword from ZMS macro code.
Implementation notes
Use this verb when you do not want to use or cannot use the standard rights system and wish to bypass it completely.
Use this verb sparingly, as it can give the caller any right on any resource.
Parameter
The parameter has the type SuMacroPlay
SuMacroPlay
NameDescriptionTypeRequired
parameters Macro named parameters Map[String,Object] optional
suKey Key of the impersonated user String required
hardFail True if an error should trigger a response on an error channel, or false (the default) if the error should be simply reported in an error field boolean optional
name Macro name String required
requestId User field for traceability of requests. This field is generated on the client side and must be unique. String optional
tempMacros Temporary macros. This feature does not support concurrent calls. List[MacroInfo] optional
debug Deprecated. Use the 'livedebug' API. int optional
MacroBlock
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroCall
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
suKey Key of the impersonated user String optional
noExpand Specifies whether parameter expansion should be avoided. The server will of course set this to true automatically if no refs are present. Defaults to false boolean optional
resultName Name of the result, for future reference String optional
parameter Parameter that will be passed to the verb. The format is the format expected by the target verb, with the following exception : any field can be replaced by a placeholder. A placeholder is an object with a '__ref' field. The value of the ref field follows java EL syntax with some pre-defined objects and functions (see the documentation on macros) Map[String,Object] optional
deploymentId DeploymentId of the service to be called String required
line Line number in source file int optional
verb Verb to be called inside the specified service String required
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
MacroFunction
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
parameters Function parameters List[MacroFunctionParam] optional
name Function name String required
result Function result Object required
source source file String optional
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroFunctionParam
NameDescriptionTypeRequired
name Parameter name String optional
MacroInfo
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
target Target for the response (the syntax is the same as in messaging.send). Overrides 'broadcast' when set. Object optional
channel Optional return channel. Defaults to completed String optional
name Macro name String required
result Optional macro result Map[String,Object] optional
userKey Setting this field effectively overrides the __userKey pseudo-constant for the duration of the macro. All non-sudoed internal calls will behave as if sudoed with the given user key. When this field is set, there is not point in calling this macro with sudo String optional
source source file (for debug) String optional
steps Sub steps, sequentially executed List[MacroStep] required
returned Optional output field specifications List[MacroScriptParam] optional
params Optional parameter specifications List[MacroScriptParam] optional
broadcast Whether to broadcast to all the user's sessions, or just to the asking session. Defaults to false (request-response paradigm). boolean optional
line Line number in source file int optional
MacroJump
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
type jump type Type required
line Line number in source file int optional
MacroLocalFunction
NameDescriptionTypeRequired
f Function definition MacroFunction required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Function local name String required
line Line number in source file int optional
MacroLog
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
data Data to be logged. The server will fail to produce an accurate result if the actual evaluated data is too big. Object optional
line Line number in source file int optional
MacroLoop
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Loop variable String required
items Collection to iterate on String required
steps Sub steps, sequentially executed List[MacroStep] required
line Line number in source file int optional
MacroScriptParam
NameDescriptionTypeRequired
name Parameter name String optional
constraints Optional parameter constraints List[MacroScriptParamConstraint] optional
MacroScriptParamConstraint
NameDescriptionTypeRequired
config Constraint configuration Map[String,Object] optional
name Constraint name String optional
MacroStatement
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
exec Statement to be executed String required
line Line number in source file int optional
MacroStep ( Subclasses : MacroCall MacroInfo MacroTest MacroLog MacroVariable MacroLoop MacroLocalFunction MacroStatement MacroJump )
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
line Line number in source file int optional
MacroTest
NameDescriptionTypeRequired
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
steps Sub steps, sequentially executed List[MacroStep] required
otherwise Else MacroBlock optional
line Line number in source file int optional
condition Macro step condition. when evaluated to true, allows for execution of the steps String required
MacroVariable
NameDescriptionTypeRequired
value value to be evaluated Object required
description Informative text, for the macro creator. You SHOULD always fill this field, as reported errors will include this description. String optional
var Variable identifier String required
line Line number in source file int optional
Type
String enumeration. Possible values are :
NameDescription
BREAK missing enum desc
CONTINUE missing enum desc
Primary output
The response has the type MacroCompletion.
The result is only sent to the user session who made the call.
MacroCompletion
NameDescriptionType
stats Execution statistics, when debug is enabled MacroCompletionStats
errors Encountered errors. Error reporting behavior can be changed with the hardFail parameter. List[ZetaApiError]
name Macro name String
result Generated result, if applicable Object
requestId User field for traceability of requests. String
log Generated debug output, if applicable List[String]
MacroCompletionStats
NameDescriptionType
elapsedMillis Elapsed server time for the execution of the macro long
ram Total number of RAM bytes long
nbCalls Total number of called verbs long
cycles Total number of VM cycles long
ZetaApiError
NameDescriptionType
code Symbolic error code String
message Human readable message. May vary depending on one or more of locale, input, developer code. String
location Error location, if available String
Error codes
CodeDescription
NOT_FOUNDA macro with the given name could not be found.
CAPACITY_EXCEEDEDThe macro execution engine allows only a fixed amount of macros to be run concurrently.
User API for macro debugging
Debugger API for macro.
These API verbs are not intended for use by most developers.
pub
breakpoint
Enables or disables a breakpoint
Implementation notes
Parameter
The parameter has the type MacroDebugBreakpointSet
MacroDebugBreakpointSet
NameDescriptionTypeRequired
breakpoint Breakpoint information MacroDebugBreakpoint required
token Debug token, previously generated by a call to the admin verb 'livedebugToken' String optional
enabled Whether the breakpoint is enabled or not boolean optional
MacroDebugBreakpoint
NameDescriptionTypeRequired
line Line number inside the source file int optional
location Source file information String optional
Error codes
CodeDescription
DEBUG_FORBIDDENInvalid or missing debug token.
pub
info
Requests some information
Implementation notes
Parameter
The parameter has the type MacroDebugInfoRequest
MacroDebugInfoRequest
NameDescriptionTypeRequired
token Debug token, previously generated by a call to the admin verb 'livedebugToken' String optional
path optional path to apply on the result of the evaluation of exp String optional
exp expression to evaluate String optional
requestId request ID String optional
frame Frame index, as sent by the server by 'resume' int optional
Error codes
CodeDescription
DEBUG_FORBIDDENInvalid or missing debug token.
pub
livedebug
Debugs a previously recorded macro
Implementation notes
The given breakpoints will be honored, causing a suspension of the execution, resumable via 'resume'.
Only one debug session can be active at any given time.
Parameter
The parameter has the type MacroDebugSession
MacroDebugSession
NameDescriptionTypeRequired
parameters Macro named parameters Map[String,Object] optional
token Debug token, previously generated by a call to the admin verb 'livedebugToken' String optional
breakpoints List of breakpoints for the session List[MacroDebugBreakpoint] optional
hardFail True if an error should trigger a response on an error channel, or false (the default) if the error should be simply reported in an error field boolean optional
name Macro name String required
requestId User field for traceability of requests. This field is generated on the client side and must be unique. String optional
debug Deprecated. Use the 'livedebug' API. int optional
MacroDebugBreakpoint
NameDescriptionTypeRequired
line Line number inside the source file int optional
location Source file information String optional
Outputs
The output
  • is on channel completed
  • has the type MacroCompletion
  • is for the current user
The macro is debugged. Upon completion the caller is asynchronously notified.
MacroCompletion
NameDescriptionType
stats Execution statistics, when debug is enabled MacroCompletionStats
errors Encountered errors. Error reporting behavior can be changed with the hardFail parameter. List[ZetaApiError]
name Macro name String
result Generated result, if applicable Object
requestId User field for traceability of requests. String
log Generated debug output, if applicable List[String]
MacroCompletionStats
NameDescriptionType
elapsedMillis Elapsed server time for the execution of the macro long
ram Total number of RAM bytes long
nbCalls Total number of called verbs long
cycles Total number of VM cycles long
ZetaApiError
NameDescriptionType
code Symbolic error code String
message Human readable message. May vary depending on one or more of locale, input, developer code. String
location Error location, if available String

Error codes
CodeDescription
DEBUG_FORBIDDENInvalid or missing debug token.
pub
resume
Resumes a paused macro
Implementation notes
Parameter
The parameter has the type MacroDebugStep
MacroDebugStep
NameDescriptionTypeRequired
token Debug token, previously generated by a call to the admin verb 'livedebugToken' String optional
type Step type MacroDebugStepType optional
MacroDebugStepType
String enumeration. Possible values are :
NameDescription
STEP_OVER Step over the next instruction
RESUME Resume execution
TERMINATE Terminate execution
STEP_INTO Step into the next macrvo call
Error codes
CodeDescription
DEBUG_FORBIDDENInvalid or missing debug token.
pub
variable
Sets a variable value
Implementation notes
Parameter
The parameter has the type MacroDebugVariableChange
MacroDebugVariableChange
NameDescriptionTypeRequired
token Debug token, previously generated by a call to the admin verb 'livedebugToken' String optional
name Variable name String required
frame Frame index, as sent by the server by 'resume' int optional
data Variable value Object optional
Error codes
CodeDescription
DEBUG_FORBIDDENInvalid or missing debug token.
notif
trace
Server traces are sent to the developer when debug is enabled.
Notification
The output
  • is on channel trace
  • has the type MacroTrace
  • is for the developer
Server traces are sent to the developer when debug is enabled.
MacroTrace
NameDescriptionType
ctx Trace context (differentiates client calls) long
type Trace type (differentiates client calls) TraceType
n Trace number (monotonous increase) int
data Trace data Object
line Line number in the source code. int
owner Zetapush key of the user generating the trace String
level Trace level TraceLevel
location Location of the source code. String
TraceLevel
String enumeration. Possible values are :
NameDescription
DEBUG Debug (server-generated traces are DEBUG)
ERROR Currently unused
TRACE From the 'trace' keyword
WARN Currently unused
INFO Currently unused
TraceType
String enumeration. Possible values are :
NameDescription
MS A macro is starting
ME A macro has ended
CMT User comment
USR Developer-generated

notif
debug
Debug events are sent to the developer (this is used by the Eclipse plugin)
Notification
The output
  • is on channel debug
  • has the type MacroDebugEvent
  • is for the developer
Debug events are sent to the developer (this is used by the Eclipse plugin)
MacroDebugEvent ( Subclasses : MacroDebugEventPause MacroDebugEventResume MacroDebugEventTermination MacroDebugEventVar )
MacroDebugEventPause
NameDescriptionType
frames Stack frames List[MacroDebugFrame]
stepIntoPossible Whether it is possible to step into. boolean
line Line number int
location Source location String
MacroDebugEventResume
MacroDebugEventTermination
MacroDebugEventVar
NameDescriptionType
value Data value MacroDebugFrameValue
type Data type String
var Evaluated expression, as requested String
error The request may have caused an error ZetaApiError
requestId request ID String
frame Frame index, as requested int
MacroDebugFrame
NameDescriptionType
vars Variables List[MacroDebugFrameVariable]
macroName Macro name String
line Line number int
location Source location String
MacroDebugFrameValue
NameDescriptionType
value Actual value, for primitive types. Size for complex types Object
vars Sub fields, for complex types List[MacroDebugFrameVariable]
type Value type String
MacroDebugFrameVariable
NameDescriptionType
value Variable value MacroDebugFrameValue
type Variable type String
name Variable name String
ZetaApiError
NameDescriptionType
code Symbolic error code String
message Human readable message. May vary depending on one or more of locale, input, developer code. String
location Error location, if available String

Sends email through SMTP
Configuration options
DescriptionValueNameType
SMTP user mandatory
 
sendmail_username STRING
SMTP password mandatory
 
sendmail_password STRING
SMTP host mandatory
 
sendmail_host STRING
SMTP port (standard 25, secure 465) default is 25
 
sendmail_port LONG
From field for sent emails mandatory
 
sendmail_from STRING
ReplyTo field for sent emails mandatory
 
sendmail_replyTo STRING
SSL enabled default is false
 
sendmail_ssl BOOLEAN
STARTTLS enabled (needs SSL) default is false
 
sendmail_starttls BOOLEAN
HTTP Controllers
Administrative API for mail testing
GET
/mail/test
Sends a test email
Audience
The API /mail/test is reserved to developers
Use in recipes
The API /mail/test is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Sends a test email to the given email address.
Errors
No documented error codes.
Response
The response body has the type String
Publish/Subscribe Services
Mail service user API
This service is statically configured with an outgoing SMTP server.
Users call the API here to actually send emails.
server
send
Sends an email
Implementation notes
Sends an email with the given body to the intended recipients.
Parameter
The parameter has the type Email
Email
NameDescriptionTypeRequired
to Email recipients List[String] optional
html Email html body. you can use text and/or html String optional
cc Email recipients List[String] optional
bcc Email recipients List[String] optional
subject Email subject String required
text Email plain text body String optional
Messaging service
Configuration options
DescriptionValueNameType
Default channel name for messages forwarding default is reply
 
messaging_return_channel STRING
Publish/Subscribe Services
Messaging service
Simple and flexible user-to-user or user-to-group messaging service.
pub
send
Sends a message to a target
Implementation notes
Sends the given message to the specified target on the given (optional) channel.
The administratively given default channel name is used when none is provided in the message itself.
Parameter
The parameter has the type Message
Message
NameDescriptionTypeRequired
target Target user or group. Can be either a string, an array of string or an object that contains an array of string. The 'target' property of the output message will have exactly the same form. Target user or group, in the form userId or groupDeploymentId:owner:group. ListOrSingle[String] required
channel Optional (alphanumeric) channel name String optional
data Data to be sent. Message payload. object with a free format. Map[String,Object] required
ListOrSingle
NameDescriptionTypeRequired
values The list of values List[String] optional
Outputs
The output
  • is on channel [input.channel] or [messaging.return.channel]
  • has the type Message
  • is for 'target' field of the message
Message
NameDescriptionType
target Target user or group. Can be either a string, an array of string or an object that contains an array of string. The 'target' property of the output message will have exactly the same form. ListOrSingle[String]
channel Optional (alphanumeric) channel name String
source User key of the message sender String
data Data to be sent Map[String,Object]
ListOrSingle
NameDescriptionType
values The list of values List[String]

Producer consumer service. Users can submit tasks and other users consume them
Publish/Subscribe Services
Producer / consumer real-time API
Task producers submits their tasks.
The server dispatches the tasks.
Consumers process them and report completion back to the server.
Tasks are global to the service (i.e. NOT per user).
pub
call
Submits a task
Implementation notes
Producer API.
A task producer submits the given task to the server.
The server will find a tasker with processing capacity and dispatch the task.
The task result will be returned to the caller.
When called from inside a macro, the comsumer generated result is available for further use.
Parameter
The parameter has the type TaskRequest
TaskRequest
NameDescriptionTypeRequired
description Task description String optional
originBusinessId BusinessId of the service from wich the task is from String optional
originDeploymentId DeploymentId of the service from wich the task is from String optional
data Task parameters. Specific for each consumer/producer contract Object optional
owner When impersonating someone, user this field to differentiate from originator.owner String optional
OwnerResource
NameDescriptionTypeRequired
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
Primary output
The response has the type TaskCompletion.
The result is only sent to the user session who made the call.
TaskCompletion
NameDescriptionType
result Optional result of the processing. When 'success' is false, can contain an error object (with String fields 'code' and 'message'). Object
taskId Server-assigned task identifier. String
success A task consumer can specify whether computation was a success or not. boolean
Error codes
CodeDescription
TASK_ERROR_CAPACITYTask queue capacity is limited on the server. Consider adding more consumers or adding more capacity to each consumer.
CONSUMER_UNSPECIFIED_ERRORThe consumer of a task reported a failure, without more precisions.
pub
done
Notifies completion of a task
Implementation notes
Consumer API.
The tasker notifies completion of the given task to the server.
The tasker can optionally include a result or an error code.
Parameter
The parameter has the type TaskCompletion
TaskCompletion
NameDescriptionTypeRequired
result Optional result of the processing. When 'success' is false, can contain an error object (with String fields 'code' and 'message'). Object optional
taskId Server-assigned task identifier. String optional
success A task consumer can specify whether computation was a success or not. boolean optional
pub
register
Registers a consumer
Implementation notes
Consumer API.
Registers the current user resource as an available task consumer.
Tasks will be then dispatched to that consumer.
Parameter
The parameter has the type TaskConsumerRegistration
TaskConsumerRegistration
NameDescriptionTypeRequired
capacity Task consumer maximum capacity at a given time. The server will not exceed that capacity when dispatching new tasks int optional
pub
submit
Submits a task
Implementation notes
Producer API.
A task producer submits the given task to the server.
The server will find a tasker with processing capacity and dispatch the task.
The task result will be ignored : the producer will not receive any notification of any kind, even in case of errors (including capacity exceeded errors).
This verb will return immediately : you can use this API to asynchronously submit a task.
Parameter
The parameter has the type TaskRequest
TaskRequest
NameDescriptionTypeRequired
description Task description String optional
originBusinessId BusinessId of the service from wich the task is from String optional
originDeploymentId DeploymentId of the service from wich the task is from String optional
data Task parameters. Specific for each consumer/producer contract Object optional
owner When impersonating someone, user this field to differentiate from originator.owner String optional
OwnerResource
NameDescriptionTypeRequired
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
pub
unregister
Unregisters a consumer
Implementation notes
Consumer API.
Unregisters the current user resource as an available task consumer.
All non finished tasks are returned to the server.
notif
dispatch
Task dispatched by the server
Notification
The output
  • is on channel dispatch
  • has the type QueueTask
  • is for 'assignee' field of the message
Task dispatched by the server
QueueTask
NameDescriptionType
done missing field desc boolean
request missing field desc TaskRequest
businessId missing field desc String
taskId missing field desc String
comet missing field desc String
deploymentId missing field desc String
assignee missing field desc OwnerResource
dispatched missing field desc boolean
OwnerResource
NameDescriptionType
resource Optional resource name, used to distinguish between two sessions of the same user on different devices. A given device SHOULD provide a resource name, and SHOULD always use the same resource name (it needs to be persisted by the client code) String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
TaskRequest
NameDescriptionType
originator Request submitter OwnerResource
description Task description String
originBusinessId BusinessId of the service from wich the task is from String
originDeploymentId DeploymentId of the service from wich the task is from String
data Task parameters. Specific for each consumer/producer contract Object
owner When impersonating someone, user this field to differentiate from originator.owner String

Native Push Notifications for Android, iOS ...
HTTP Controllers
Administrative API for notifications management.
You can create and list your applications
POST
/notifs/createApp
Creates an application
Audience
The API /notifs/createApp is reserved to developers
Use in recipes
The API /notifs/createApp is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
The created application can then be referenced when registering a device.
Errors
No documented error codes.
Request body
The request body has the type NotifiableApplication
NotifiableApplication
NameDescriptionTypeRequired
credential Vendor-specific credential : 'private key' for APNS, 'API key' for GCM String required
applicationName Application name, as registered in your vendor-specific management console String required
platform Platform type NotificationPlatform required
principal Your vendor-specific principal : 'SSL certificate' (PEM format) for APNS, N/A for GCM String optional
appId Application primary key, that you choose arbitrarily. If absent, it will default to the value of applicationName String optional
NotificationPlatform
String enumeration. Possible values are :
NameDescription
APNS Apple
APNS_SANDBOX Apple sandbox
GCM Google Cloud Messaging
Response
The response body has the type void
Publish/Subscribe Services
Notification User API
User API for notifications.
For notifications to work properly, it is imperative that the resource name of a device remain constant over time.
server
register
Registers a device
Implementation notes
Registers the device for the current user and resource.
This service maintains a mapping of __userkey/__resource to device registration IDs.
You MUST NOT re-use the same resource name from one device to another if you want to target specific devices with 'send'.
Only one registration can be active for a given __userKey/__resource pair in a notification service.
Device registration can be neither impersonated nor called indirectly (from a scheduled job).
Parameter
The parameter has the type NotifiableDeviceRegistration
NotifiableDeviceRegistration
NameDescriptionTypeRequired
deviceToken Device-specific and app-specific opaque token. The format and meaning is vendor (Apple, Android...) specific. The value is generated by some vendor API on the device for a particular app and will be used by zetapush for notifications. String required
appId Application primary key (as defined in 'createApp') String required
server
send
Sends a notification to the target
Implementation notes
Sends a native push notification to the target.
Parameter
The parameter has the type NotificationMessage
NotificationMessage
NameDescriptionTypeRequired
resource Resource of the target device (optional. if not given, will notify all devices of the user) String optional
target Target user key (as in __userKey) String required
data Data to be sent (map or string). Top-level fields to be included in the message. If data is a string, data will be put in the right, vendor-specific, location in the data structure sent to the device. Object optional
Primary output
The response has the type NotificationSendStatus.
The result is only sent to the user session who made the call.
NotificationSendStatus
NameDescriptionType
report List of statuses for each target device List[DeviceNotificationSendStatus]
message Source message NotificationMessage
DeviceNotificationSendStatus
NameDescriptionType
deviceToken Token for target device String
endpoint Endpoint for target device String
success Whether the message was sent boolean
NotificationMessage
NameDescriptionType
resource Resource of the target device (optional. if not given, will notify all devices of the user) String
target Target user key (as in __userKey) String
data Data to be sent (map or string). Top-level fields to be included in the message. If data is a string, data will be put in the right, vendor-specific, location in the data structure sent to the device. Object
server
unregister
Unregisters a device
Implementation notes
Unregisters the device for the current user and resource.
This verb does not need any parameters.
Relational Database : SQL storage
HTTP Controllers
Administrative API for rdbms management.
You can create and list tables
POST
/rdbms/ddl
Issues a DDL query
Audience
The API /rdbms/ddl is reserved to developers
Use in recipes
The API /rdbms/ddl is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Creates a table, with the given structure.
A table consists of a name and column definitions. You can provide as many columns as you wish.
This API never deletes columns.
Errors
No documented error codes.
Request body
The request body has the type RdbmsSimpleQuery
RdbmsSimpleQuery
NameDescriptionTypeRequired
statement SQL query String optional
Response
The response body has the type void
Publish/Subscribe Services
RDBMS User API
User API for SQL queries.
Contrary to GDA or Stacks, the data are not stored on a per-user basis.
Users can store, get, list their data.
server
query
Runs a query.
Implementation notes
Runs a DML query with SQL syntax on this database.
The @@sql statement supports inline SQL (unquoted), embedded constants (prefixed by '$', unescaped and statically replaced in the generated SQL query), embedded parameters (prefixed by ':', dynamically replaced and escaped at run-time)
The returned RdbmsResultSet is an iterable collection of rows.
The returned result set is iterable only once.
The content of a row is accessible only when it is being iterated on.
Access control
Impersonating users need to be granted rights on action 'query'
Parameter
The parameter has the type RdbmsQuery
RdbmsQuery
NameDescriptionTypeRequired
parameters Parameters of the query List[Object] optional
statement SQL query String optional
Primary output
The response has the type RdbmsResultSet.
The result is only sent to the user session who made the call.
RdbmsResultSet
server
update
Runs an update.
Implementation notes
Runs a DML update with SQL syntax on this database.
Access control
Impersonating users need to be granted rights on action 'update'
Parameter
The parameter has the type RdbmsQuery
RdbmsQuery
NameDescriptionTypeRequired
parameters Parameters of the query List[Object] optional
statement SQL query String optional
SMS sender, to send text messages to mobile phones.This SMS sending service uses the OVH API.
Configuration options
DescriptionValueNameType
OVH Application Key mandatory
 
sms_ovh_ak STRING
OVH Application Secret mandatory
 
sms_ovh_as STRING
OVH Consumer Key mandatory
 
sms_ovh_ck STRING
OVH Service Name. Must match a defined service name in your OVH dashboard mandatory
 
sms_ovh_sn STRING
Publish/Subscribe Services
SMS service
User API for SMS.
server
send
Sends an SMS
Implementation notes
Sends the given message to the given recipients.
Parameter
The parameter has the type SmsMessage
SmsMessage
NameDescriptionTypeRequired
sender Sender name String optional
message Text message. Standard restrictions for text messages apply String optional
receivers List of recipients List[String] optional
Scheduler service. End-users can schedule one-time or repetitive tasks using a classical cron syntax (with the year field) or a timestamp (milliseconds from the epoch)
Publish/Subscribe Services
User API for the Scheduler
User endpoints for scheduling : users can schedule, list and delete tasks.
Tasks are stored on a per-user basis: a task will run with the priviledges of the user who stored it.
Tasks are run on the server and thus can call api verbs marked as server-only.
pub
list
List the configured tasks
Implementation notes
Returns a paginated list of the asking user's tasks.
Parameter
The parameter has the type CronTaskListRequest
CronTaskListRequest
NameDescriptionTypeRequired
start Start timestamp for the task list. Not implemented long optional
stop Stop timestamp for the task list. Not implemented long optional
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
page Pagination information Pagination optional
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionTypeRequired
pageSize Page size (minimum 1) int optional
pageNumber Page number (zero-based) int optional
direction Sort direction. Default is ASC when not specified. PageDirection optional
Primary output
The response has the type CronPlanning.
The result is only sent to the user session who made the call.
CronPlanning
NameDescriptionType
request Cron planning request CronTaskListRequest
tasks List of all tasks matching the request PageContent[CronTaskRequest]
CronTaskListRequest
NameDescriptionType
start Start timestamp for the task list. Not implemented long
stop Stop timestamp for the task list. Not implemented long
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
page Pagination information Pagination
CronTaskRequest
NameDescriptionType
cronName Cron identifier. mandatory for creation or update. String
schedule Cron-like expression (with fixed minutes and hours) or unix timestamp (as milliseconds from the epoch). Times are UTC. Object
parameter Parameter that will be passed to the target verb when called. The format is the format accepted by the target. Map[String,Object]
stop Max number of executions. Long
deploymentId DeploymentId of the target service. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
verb Verb to be called within the target service. String
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean
PageContent
NameDescriptionType
content Content List
page Pagination information Pagination
PageDirection
String enumeration. Possible values are :
NameDescription
DESC Descending order
ASC Ascending order
Pagination
NameDescriptionType
pageSize Page size (minimum 1) int
pageNumber Page number (zero-based) int
direction Sort direction. Default is ASC when not specified. PageDirection
server
schedule
Schedules a task
Implementation notes
Schedules a task for later execution. Tasks are executed asynchronously with the identity of the calling user.
Tasks will be executed at a fixed moment in time in the future, or repeatedly, with minute precision.
If a task already exists with the same cronName (a cronName is unique for a given user), this new task completely replaces it.
A task can be scheduled with a cron-like syntax for repetitive or one-shot execution.
Wildcards are not allowed for minutes and hours.
When scheduling for one-shot execution, the time must be at least two minutes into the future.
Parameter
The parameter has the type CronTaskRequest
CronTaskRequest
NameDescriptionTypeRequired
cronName Cron identifier. mandatory for creation or update. String required
schedule Cron-like expression (with fixed minutes and hours) or unix timestamp (as milliseconds from the epoch). Times are UTC. Object required
parameter Parameter that will be passed to the target verb when called. The format is the format accepted by the target. Map[String,Object] optional
stop Max number of executions. Long optional
deploymentId DeploymentId of the target service. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
verb Verb to be called within the target service. String required
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
Primary output
The response has the type CronTaskRequest.
The result is sent to all live connections of the user.
CronTaskRequest
NameDescriptionType
cronName Cron identifier. mandatory for creation or update. String
schedule Cron-like expression (with fixed minutes and hours) or unix timestamp (as milliseconds from the epoch). Times are UTC. Object
parameter Parameter that will be passed to the target verb when called. The format is the format accepted by the target. Map[String,Object]
stop Max number of executions. Long
deploymentId DeploymentId of the target service. String
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String
verb Verb to be called within the target service. String
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean
Error codes
CodeDescription
PAST_DATEA task can only be set in the future (two minutes from now). The current time (UTC) of the server can be accessed from inside a macro with the function time:now().
FORBIDDEN_CRONA schedule must respect some constraints : the 'minutes' and 'hours' fields must be precise. Wilcards are not allowed.
BAD_CRONThe schedule could not be parsed. Please check your syntax.
server
setTimeout
Schedules a task
Implementation notes
Schedules a task for later execution. Tasks are executed asynchronously with the identity of the calling user.
Tasks will be executed with second precision in the near future (120 seconds delay max).
Parameter
The parameter has the type TimerRequest
TimerRequest
NameDescriptionTypeRequired
parameter Parameter that will be passed to the target verb when called. The format is the format accepted by the target. Map[String,Object] optional
deploymentId DeploymentId of the target service. String required
owner Optional User key. When calling the API, defaults to the current (calling) user's primary key. For impersonation purposes, the caller may use the key of another user, provided that the proper authorizations have been given by the impersonated user String optional
verb Verb to be called within the target service. String required
delay Delay in seconds before calling the given API. Must be a integer between 1 and 120. int optional
loud Specifies whether this call should generate all expected direct user notifications (primary outputs). Does not affect side-effects (other outputs). Defaults to false boolean optional
Primary output
The response has the type TimerResult.
The result is sent to all live connections of the user.
TimerResult
NameDescriptionType
id Timer identifier String
server
unschedule
Removes a scheduled task
Implementation notes
Removes a previously scheduled task.
Does absolutely nothing if asked to remove a non-existent task.
Parameter
The parameter has the type