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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
key User key within the realm ('login' field, by default) 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/configureLimits
Configures connection limits
Audience
The API /memauth/configureLimits is reserved to developers
Use in recipes
The API /memauth/configureLimits is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Sets the configuration for connection limits.
When configured, allows to limit the rate at which a single IP address can make connection requests (cometd handshakes) to the STR server.
There is no default configuration : the default behaviour is to allow all connection requests.
Errors
No documented error codes.
Request body
The request body has the type SimpleConnectionLimits
SimpleConnectionLimits
NameDescriptionTypeRequired
maxConnections Maximum number of connection requests that a single IP can make to the server in one hour. int optional
maxRememberedIps Maximum number of distinct IP addresses that the rate limiter will remember at one given time. The current implementation being RAM-based, this parameter is necessary (and should be kept quite low) to ensure that the RAM consumption is reasonable. The default value when not set will be 100 int optional
whitelist List of IPv4 addresses (e.g. '10.159.75.45') that are still allowed to make any number of connections to the server. Set[String] optional
Response
The response body has the type void
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
key User key within the realm ('login' field, by default) 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/getLimits
Returns connection limits
Audience
The API /memauth/getLimits is reserved to developers
Implementation notes
Returns the current configuration for connection limits.
There is no default configuration : all values will be zeroed or empty when not set.
Errors
No documented error codes.
Response
The response body has the type SimpleConnectionLimits
SimpleConnectionLimits
NameDescriptionType
maxConnections Maximum number of connection requests that a single IP can make to the server in one hour. int
maxRememberedIps Maximum number of distinct IP addresses that the rate limiter will remember at one given time. The current implementation being RAM-based, this parameter is necessary (and should be kept quite low) to ensure that the RAM consumption is reasonable. The default value when not set will be 100 int
whitelist List of IPv4 addresses (e.g. '10.159.75.45') that are still allowed to make any number of connections to the server. Set[String]
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
checkAccount
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
key User key within the realm ('login' field, by default) 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 SimpleAccountInfo.
The result is only sent to the user session who made the call.
SimpleAccountInfo
NameDescriptionType
status Status. If status.active is false, the account cannot be used to log in. SimpleAccountStatus
fields Arbitrary map of fields. MUST contain the login field ('login') and the 'password' field Map[String,Object]
userKey Server generated user key (global unique key for a user, a user can be logged in via several accounts) String
SimpleAccountStatus
NameDescriptionType
data Optional developer-defined status object which contents should depend on the 'active' field. Object
active Whether this account should be usable for actual login by end users boolean
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
key account key in the realm. (configured 'unique key' used for authentication) String
server
checkUser
Checks some account's existence
Deprecation
This API was deprecated:
Use checkAccount
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
key User key within the realm ('login' field, by default) 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
createAccount
Creates an account
Implementation notes
Creates a new account in this 'simple' authentication realm.
Returns the 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 SimpleAccountCreation
SimpleAccountCreation
NameDescriptionTypeRequired
status Status after creation. If status.active is false, the account cannot immediately be used to log in. SimpleAccountStatus optional
fields Arbitrary map of fields. MUST contain the login field ('login') and the 'password' field Map[String,Object] optional
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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.
SimpleAccountStatus
NameDescriptionTypeRequired
data Optional developer-defined status object which contents should depend on the 'active' field. Object optional
active Whether this account should be usable for actual login by end users boolean optional
Primary output
The response has the type SimpleAccountInfo.
The result is only sent to the user session who made the call.
SimpleAccountInfo
NameDescriptionType
status Status. If status.active is false, the account cannot be used to log in. SimpleAccountStatus
fields Arbitrary map of fields. MUST contain the login field ('login') and the 'password' field Map[String,Object]
userKey Server generated user key (global unique key for a user, a user can be logged in via several accounts) String
SimpleAccountStatus
NameDescriptionType
data Optional developer-defined status object which contents should depend on the 'active' field. Object
active Whether this account should be usable for actual login by end users boolean
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
createUser
Creates an account
Deprecation
This API was deprecated:
Use createAccount, which has cleaner input and output fields
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 ImpersonatedTraceableRequest
ImpersonatedTraceableRequest
NameDescriptionTypeRequired
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 AllCredentials.
The result is only sent to the user session who made the call.
AllCredentials
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
key User key within the realm ('login' field, by default) 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
key User key within the realm ('login' field, by default) 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
setStatus
Change some account's status
Implementation notes
Changes status if 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 SimpleAccountStatusChangeRequest
SimpleAccountStatusChangeRequest
NameDescriptionTypeRequired
status New status. If status.active is false, the account cannot be used to log in. SimpleAccountStatus required
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
key User key within the realm ('login' field, by default) String required
SimpleAccountStatus
NameDescriptionTypeRequired
data Optional developer-defined status object which contents should depend on the 'active' field. Object optional
active Whether this account should be usable for actual login by end users boolean optional
Primary output
The response has the type SimpleAccountInfo.
The result is only sent to the user session who made the call.
SimpleAccountInfo
NameDescriptionType
status Status. If status.active is false, the account cannot be used to log in. SimpleAccountStatus
fields Arbitrary map of fields. MUST contain the login field ('login') and the 'password' field Map[String,Object]
userKey Server generated user key (global unique key for a user, a user can be logged in via several accounts) String
SimpleAccountStatus
NameDescriptionType
data Optional developer-defined status object which contents should depend on the 'active' field. Object
active Whether this account should be usable for actual login by end users boolean
Error codes
CodeDescription
NO_ACCOUNTThe given account key in this realm (login) does not match an existing account.
server
updateAccount
Updates an account
Implementation notes
Updates an existing account in this 'simple' authentication realm.
The configured login field MUST be given, as a user (identified by his zetapush userKey) might possess several accounts.
Returns the account fields
Parameter
The parameter has the type SimpleAccountUpdate
SimpleAccountUpdate
NameDescriptionTypeRequired
fields Arbitrary map of fields. MUST contain the login field ('login') and the 'password' field Map[String,Object] optional
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
key account key in the realm. (configured 'unique key' used for authentication) String required
Primary output
The response has the type SimpleAccountInfo.
The result is only sent to the user session who made the call.
SimpleAccountInfo
NameDescriptionType
status Status. If status.active is false, the account cannot be used to log in. SimpleAccountStatus
fields Arbitrary map of fields. MUST contain the login field ('login') and the 'password' field Map[String,Object]
userKey Server generated user key (global unique key for a user, a user can be logged in via several accounts) String
SimpleAccountStatus
NameDescriptionType
data Optional developer-defined status object which contents should depend on the 'active' field. Object
active Whether this account should be usable for actual login by end users boolean
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
Deprecation
This API was deprecated:
Use updateAccount
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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[]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
stack Stack name. String
ts Insertion timestamp long
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
stack Stack name. String required
ts Insertion timestamp long optional
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[]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
stack Stack name. String
ts Insertion timestamp long
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
Use in recipes
The API /gda/listTables is scriptable : it can be used in your recipe.zms to initialize your application.
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
Use in recipes
The API /gda/removeTable is scriptable : it can be used in your recipe.zms to initialize your application.
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/depId6/get
  • http:///str/restd/BU_ID/depId6/getCells
  • http:///str/restd/BU_ID/depId6/inc
  • http:///str/restd/BU_ID/depId6/list
  • http:///str/restd/BU_ID/depId6/mget
  • http:///str/restd/BU_ID/depId6/put
  • http:///str/restd/BU_ID/depId6/puts
  • http:///str/restd/BU_ID/depId6/range
  • http:///str/restd/BU_ID/depId6/removeCell
  • http:///str/restd/BU_ID/depId6/removeColumn
  • http:///str/restd/BU_ID/depId6/removeRange
  • http:///str/restd/BU_ID/depId6/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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
start Start row key (inclusive) String optional
table Table name String required
stop Stop row key (exclusive) String optional
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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 required
Response
The response body has the type UserGroup
UserGroup
NameDescriptionType
user The user's key (as in __userKey) String
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 required
Response
The response body has the type GroupInfo
GroupInfo
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
POST
/groups/delUser
Removes a user from a group
Audience
The API /groups/delUser is reserved to developers
Use in recipes
The API /groups/delUser is scriptable : it can be used in your recipe.zms to initialize your application.
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
Use in recipes
The API /groups/deleteGroup is scriptable : it can be used in your recipe.zms to initialize your application.
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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/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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 GrantList
GrantList
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 GroupUsers
GroupUsers
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
Use in recipes
The API /groups/revoke is scriptable : it can be used in your recipe.zms to initialize your application.
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
Deprecation
This API was deprecated:
Replaced by listDetailedOwnedGroups
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 List[GroupUsers].
The result is only sent to the user session who made the call.
GroupUsers
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
Primary output
The response has the type GroupInfo.
The result is sent to all live connections of the user.
GroupInfo
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 GroupRelated.
The result is sent to all live connections of the user.
GroupRelated
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 GroupExistence.
The result is only sent to the user session who made the call.
GroupExistence
NameDescriptionType
exists Existence of the group boolean
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 GroupUsers.
The result is only sent to the user session who made the call.
GroupUsers
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
Deprecation
This API was deprecated:
Replaced by listOwnedGroups
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 List[GroupInfo].
The result is only sent to the user session who made the call.
GroupInfo
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
listDetailedOwnedGroups
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 TraceablePaginatedImpersonatedRequest
TraceablePaginatedImpersonatedRequest
NameDescriptionTypeRequired
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 OwnedGroupsWithDetails.
The result is only sent to the user session who made the call.
OwnedGroupsWithDetails
NameDescriptionType
groups Detailed groups owned by the user. PageContent[GroupUsers]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
GroupUsers
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
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
pub
listGrants
Lists rights for a group
Deprecation
This API was deprecated:
Use listGroupGrants
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 GrantList.
The result is only sent to the user session who made the call.
GrantList
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
listGroupGrants
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 GroupRelatedAndPaged
GroupRelatedAndPaged
NameDescriptionTypeRequired
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 PagedGrantList.
The result is only sent to the user session who made the call.
PagedGrantList
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
grants List of granted rights PageContent[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
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
pub
listGroupPresences
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 GroupRelatedAndPaged
GroupRelatedAndPaged
NameDescriptionTypeRequired
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 PagedGroupPresence.
The result is only sent to the user session who made the call.
PagedGroupPresence
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
presences List of group users, with their presence information. PageContent[Presence]
GroupRelated
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
Presence
NameDescriptionType
user User information OwnerResource
presence Presence status. OFF or ON String
group Group information GroupRelated
pub
listJoinedGroups
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 TraceablePaginatedImpersonatedRequest
TraceablePaginatedImpersonatedRequest
NameDescriptionTypeRequired
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 JoinedGroups.
The result is only sent to the user session who made the call.
JoinedGroups
NameDescriptionType
groups Groups joined by the user. PageContent[GroupInfo]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
GroupInfo
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
pub
listOwnedGroups
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 TraceablePaginatedImpersonatedRequest
TraceablePaginatedImpersonatedRequest
NameDescriptionTypeRequired
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 OwnedGroups.
The result is only sent to the user session who made the call.
OwnedGroups
NameDescriptionType
groups Groups owned by the user. PageContent[GroupInfo]
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
GroupInfo
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
pub
listPresences
Lists presences for a group
Deprecation
This API was deprecated:
Use listGroupPresences
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 GroupPresence.
The result is only sent to the user session who made the call.
GroupPresence
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
presences List of group users, with their presence information. List[Presence]
GroupRelated
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
Deprecation
This API was deprecated:
Replaced by listJoinedGroups
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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 List[GroupInfo].
The result is only sent to the user session who made the call.
GroupInfo
NameDescriptionType
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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 'gda_0:wshwWSDOJSD:myTable' , gda_0 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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

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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
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/depId18/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
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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
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
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
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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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
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.
Log service
HTTP Controllers
Administrative API for log management.
You can configure and list logs
GET
/logs/configuration
Current configuration
Audience
The API /logs/configuration is publicly accessible
Use in recipes
The API /logs/configuration is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Returns the current logging configuration.
Errors
No documented error codes.
Response
The response body has the type LogConfig
LogConfig
NameDescriptionType
rootLoggerConfig Config for the root logger. The sink defined here (INTERNAL if absent) will be used by default by other loggers. RootLoggerConfig
sinkConfigs List of defined sinks. It is useless to configure more than one INTERNAL or REAL_TIME sink List[LogSinkConfig]
loggers Maps loggers to levels (DEBUG, INFO, ...). A logger name should appear only once in this list List[LoggerConfig]
LogLevel
String enumeration. Possible values are :
NameDescription
DEBUG All information usually needed by developers or administrators to help diagnose problems.
ERROR Something is wrong enough to compromise the correct processing of a request (for example a mandatory external resource, e.g. another HTTP server, is not responding)
TRACE Lowest level of traces. All service verbs at the TRACE level will dump all input and output. DO NOT enable TRACE unless you are prepared to go through a very high volume of logs. Enabling TRACE may degrade application performance.
WARN Anything that can cause application misbehaviour, but that does not need human intervention.
INFO Events meaningful for your application should go there : the creation of a user, a purchase, etc ...
LogSinkConfig
NameDescriptionType
name Sink name String
sinkType Sink type LogSinkType
sinkConfig specific to each sink type Map[String,Object]
LogSinkType
String enumeration. Possible values are :
NameDescription
TODO missing enum desc
INTERNAL missing enum desc
REAL_TIME missing enum desc
LoggerConfig
NameDescriptionType
sinkNames Sink name references, as defined in the sinkConfigs section of the LogConfig. When none is given, the root sink is used. Set[String]
logger Logger name. Hierarchical, dot-separated identifier, such as 'myClass.myVerb' to ease log storage and filtering. String
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel
RootLoggerConfig
NameDescriptionType
sinkNames Sink name references, as defined in the sinkConfigs section of the LogConfig. Set[String]
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel
POST
/logs/configure
Configures the logs
Audience
The API /logs/configure is reserved to developers
Use in recipes
The API /logs/configure is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Sets the whole logs configuration.
Totally replaces any existing configuration.
Errors
No documented error codes.
Request body
The request body has the type LogConfig
LogConfig
NameDescriptionTypeRequired
rootLoggerConfig Config for the root logger. The sink defined here (INTERNAL if absent) will be used by default by other loggers. RootLoggerConfig required
sinkConfigs List of defined sinks. It is useless to configure more than one INTERNAL or REAL_TIME sink List[LogSinkConfig] optional
loggers Maps loggers to levels (DEBUG, INFO, ...). A logger name should appear only once in this list List[LoggerConfig] optional
LogLevel
String enumeration. Possible values are :
NameDescription
DEBUG All information usually needed by developers or administrators to help diagnose problems.
ERROR Something is wrong enough to compromise the correct processing of a request (for example a mandatory external resource, e.g. another HTTP server, is not responding)
TRACE Lowest level of traces. All service verbs at the TRACE level will dump all input and output. DO NOT enable TRACE unless you are prepared to go through a very high volume of logs. Enabling TRACE may degrade application performance.
WARN Anything that can cause application misbehaviour, but that does not need human intervention.
INFO Events meaningful for your application should go there : the creation of a user, a purchase, etc ...
LogSinkConfig
NameDescriptionTypeRequired
name Sink name String required
sinkType Sink type LogSinkType required
sinkConfig specific to each sink type Map[String,Object] optional
LogSinkType
String enumeration. Possible values are :
NameDescription
TODO missing enum desc
INTERNAL missing enum desc
REAL_TIME missing enum desc
LoggerConfig
NameDescriptionTypeRequired
sinkNames Sink name references, as defined in the sinkConfigs section of the LogConfig. When none is given, the root sink is used. Set[String] optional
logger Logger name. Hierarchical, dot-separated identifier, such as 'myClass.myVerb' to ease log storage and filtering. String required
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel required
RootLoggerConfig
NameDescriptionTypeRequired
sinkNames Sink name references, as defined in the sinkConfigs section of the LogConfig. Set[String] required
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel required
Response
The response body has the type void
POST
/logs/list
List log entries
Audience
The API /logs/list is publicly accessible
Use in recipes
The API /logs/list is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Returns a paginated list of log entries, that were stored internally.
Will NOT return log entries other than stored through INTERNAL.
Errors
No documented error codes.
Request body
The request body has the type LogListRequest
LogListRequest
NameDescriptionTypeRequired
start Start timestamp (inclusive) long optional
stop Start timestamp (inclusive) long 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
Response
The response body has the type LogEntries
LogEntries
NameDescriptionType
start Start timestamp (inclusive) long
entries missing field desc PageContent[LogEntry]
stop Start timestamp (inclusive) long
page Pagination information Pagination
LogEntry
NameDescriptionType
resource Refines the identification of a connected client. Automatically set by the server from the current connection if available. String
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
timestamp server-generated timestamp Long
custom For developer-defined values, tags, etc... A typical usage is to trace an application-generated transaction ID across several API calls, to be able to retrace a full click-stream afterwards Map[String,Object]
data The actual data you are logging. Can be a text message, or more structured data. Object
logger Logger name. Hierarchical, dot-separated identifier, such as 'myClass.myVerb' to ease log storage and filtering. 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
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel
node server node name String
timestampOverride User supplied timestamp. The server will still store its own timestamp. long
LogLevel
String enumeration. Possible values are :
NameDescription
DEBUG All information usually needed by developers or administrators to help diagnose problems.
ERROR Something is wrong enough to compromise the correct processing of a request (for example a mandatory external resource, e.g. another HTTP server, is not responding)
TRACE Lowest level of traces. All service verbs at the TRACE level will dump all input and output. DO NOT enable TRACE unless you are prepared to go through a very high volume of logs. Enabling TRACE may degrade application performance.
WARN Anything that can cause application misbehaviour, but that does not need human intervention.
INFO Events meaningful for your application should go there : the creation of a user, a purchase, etc ...
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
Log API
User API for logging.
This service is a fa├žade for a system logging facility. Creating two log services has no effect.
pub
log
Creates a log entry
Implementation notes
Adds some server generated data and stores the entry into the sink defined by configuration.
Parameter
The parameter has the type LogRequest
LogRequest
NameDescriptionTypeRequired
resource Refines the identification of a connected client. Automatically set by the server from the current connection if available. String optional
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String optional
custom For developer-defined values, tags, etc... A typical usage is to trace an application-generated transaction ID across several API calls, to be able to retrace a full click-stream afterwards Map[String,Object] optional
data The actual data you are logging. Can be a text message, or more structured data. Object optional
logger Logger name. Hierarchical, dot-separated identifier, such as 'myClass.myVerb' to ease log storage and filtering. 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
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel optional
timestampOverride User supplied timestamp. The server will still store its own timestamp. long optional
LogLevel
String enumeration. Possible values are :
NameDescription
DEBUG All information usually needed by developers or administrators to help diagnose problems.
ERROR Something is wrong enough to compromise the correct processing of a request (for example a mandatory external resource, e.g. another HTTP server, is not responding)
TRACE Lowest level of traces. All service verbs at the TRACE level will dump all input and output. DO NOT enable TRACE unless you are prepared to go through a very high volume of logs. Enabling TRACE may degrade application performance.
WARN Anything that can cause application misbehaviour, but that does not need human intervention.
INFO Events meaningful for your application should go there : the creation of a user, a purchase, etc ...
notif
logged
Notification
The output
  • is on channel logged
  • has the type LogEntry
  • is for users with read or all privileges on the sandbox
This notification is automatically sent each time a log entry is created.
Notifications are sent if and only if the appropriate loggers are configured to do so and the sink type is set to REAL_TIME.
LogEntry
NameDescriptionType
resource Refines the identification of a connected client. Automatically set by the server from the current connection if available. String
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String
timestamp server-generated timestamp Long
custom For developer-defined values, tags, etc... A typical usage is to trace an application-generated transaction ID across several API calls, to be able to retrace a full click-stream afterwards Map[String,Object]
data The actual data you are logging. Can be a text message, or more structured data. Object
logger Logger name. Hierarchical, dot-separated identifier, such as 'myClass.myVerb' to ease log storage and filtering. 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
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel
node server node name String
timestampOverride User supplied timestamp. The server will still store its own timestamp. long
LogLevel
String enumeration. Possible values are :
NameDescription
DEBUG All information usually needed by developers or administrators to help diagnose problems.
ERROR Something is wrong enough to compromise the correct processing of a request (for example a mandatory external resource, e.g. another HTTP server, is not responding)
TRACE Lowest level of traces. All service verbs at the TRACE level will dump all input and output. DO NOT enable TRACE unless you are prepared to go through a very high volume of logs. Enabling TRACE may degrade application performance.
WARN Anything that can cause application misbehaviour, but that does not need human intervention.
INFO Events meaningful for your application should go there : the creation of a user, a purchase, etc ...

notif
configured
Notification
The output
  • is on channel configured
  • has the type LogConfig
  • is for users with all privileges on the sandbox
This notification is automatically sent each time the log configuration is changed.
Workers SHOULD listen to this notification and filter their log requests accordingly, to save resources.
LogConfig
NameDescriptionType
rootLoggerConfig Config for the root logger. The sink defined here (INTERNAL if absent) will be used by default by other loggers. RootLoggerConfig
sinkConfigs List of defined sinks. It is useless to configure more than one INTERNAL or REAL_TIME sink List[LogSinkConfig]
loggers Maps loggers to levels (DEBUG, INFO, ...). A logger name should appear only once in this list List[LoggerConfig]
LogLevel
String enumeration. Possible values are :
NameDescription
DEBUG All information usually needed by developers or administrators to help diagnose problems.
ERROR Something is wrong enough to compromise the correct processing of a request (for example a mandatory external resource, e.g. another HTTP server, is not responding)
TRACE Lowest level of traces. All service verbs at the TRACE level will dump all input and output. DO NOT enable TRACE unless you are prepared to go through a very high volume of logs. Enabling TRACE may degrade application performance.
WARN Anything that can cause application misbehaviour, but that does not need human intervention.
INFO Events meaningful for your application should go there : the creation of a user, a purchase, etc ...
LogSinkConfig
NameDescriptionType
name Sink name String
sinkType Sink type LogSinkType
sinkConfig specific to each sink type Map[String,Object]
LogSinkType
String enumeration. Possible values are :
NameDescription
TODO missing enum desc
INTERNAL missing enum desc
REAL_TIME missing enum desc
LoggerConfig
NameDescriptionType
sinkNames Sink name references, as defined in the sinkConfigs section of the LogConfig. When none is given, the root sink is used. Set[String]
logger Logger name. Hierarchical, dot-separated identifier, such as 'myClass.myVerb' to ease log storage and filtering. String
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel
RootLoggerConfig
NameDescriptionType
sinkNames Sink name references, as defined in the sinkConfigs section of the LogConfig. Set[String]
level Levels ensure that requests end up in the logs only when configured to do so. LogLevel

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[ResponseEntity[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
contextId Context ID. Clients and developers must not pass this explicitly. This value is generated by the server and can be passed back by the worker SDKs. String 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
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
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
cause Optional cause. ZetaApiError
code Symbolic error code String
message Human readable message. May vary depending on one or more of locale, input, developer code. String
context Developer-generated context. Each code can have a specific context format. Object
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.
POST
/debug/configure
Configures debug mode
Audience
The API /debug/configure is reserved to developers
Use in recipes
The API /debug/configure is scriptable : it can be used in your recipe.zms to initialize your application.
Implementation notes
Enables or disables debug mode on this STR node. See 'enable' for details.
Errors
No documented error codes.
Request body
The request body has the type MacroServiceDebugConfig
MacroServiceDebugConfig
NameDescriptionTypeRequired
debug Whether this macro service is currently in debug mode boolean optional
Response
The response body has the type void
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 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
frame