Actions are registered and configured per-template to allow for interaction with vAtoms and user-triggered behavior.
Although templates are immutable once published (meaning they cannot be changed), actions for a given template can be added, modified, or removed even after the template is published.
All vAtoms that are created based on a given template will have the template's actions available.
Content-Type: application/json
App-Id: {app_id}| Name | Type | Description |
|---|---|---|
name
*
| string | Name of the action, has to be of the form
publisher_fqdn::Template_Name::v1::Action::Action_Name |
reactor
*
| string | Name of the reactor that is executed. |
wait | boolean | Flag to define if the action should be executed synchronously (
true
) or not (
false
). Default
false
. |
rollback | boolean | Not yet implemented |
abort_on_pre_error | boolean | Defines if the action should abort if an error occurs while executing the pre policies. |
abort_on_post_error | boolean | Defines if the action should abort if an error occurs while executing the post policies. |
abort_on_main_error | boolean | Defines if the action should abort if an error occurs while executing the main reactor. |
timeout
*
| integer | Max. execution time in milliseconds (has to be > 0). |
guest_user | boolean | Defines if users that are not activated (don't have a verified email of phone) are allowed to use the action. Default
false
. |
state_impact | array | Not yet implemented |
policy | object | Pre and Post reactors that can execute additional logic before or after the main reactor is executed. |
config | object | Generic action configuration. |
params | object | Input and output parameters. |
limit_per_user | integer | How many times a user can call this action. 0 means no limit. |
action_notification | object | Notification configuration that is applied when the action is executed. |
When considering the behaviors of a vatom, registered actions specify the "interface" for the behavior, such as the action name. Reactors are the code that actually implements the implementation of the action.
The BLOCKv platform includes some built-in reactors for commonly-registered actions:
Allows a user who owns a specific vAtom to transfer ownership of that vAtom to another user.
Clones the vAtom and sends the copy to another user. The cloning parameters are defined in the template variation.
Drops a vAtom on the map. The user who dropped the vAtom is still considered the owner until somebody else picks it up (by calling the Pickup action).
Picks up a vAtom that was previously dropped on the map. After calling this action, the vAtom changes ownership to whomever called the action and is no longer available on the map.
Acquires a vAtom from a publisher. The difference between this action and the Transfer action is in who initiates the transfer of ownership.
The Transfer action must be called by the current owner of the vAtom, whereas the Acquire action can be called by any other user to effectively "take" the vAtom from the publisher (but only if the publisher signals that they would like this kind of behavior, by having the Acquire action registered).
As an example, the Acquire can be used to allow a user to take a picture of a billboard with a QR code on it containing a vAtom id, and call the Acquire action with this id as a parameter to move the vAtom into their own inventory.
Acquires a vAtom of the same template variation as a given vAtom from a publisher. The difference between this action and the Acquire action is that it can transfer an existing vAtom (not necessarily the one with the given vAtom ID) or create a new one (if there are no vAtoms fulfilling the conditions and AutoCreateOnAcquire is set in the template variation).
Allows a user who owns a specific vAtom to redeem it, i.e. replace it for another vAtom(s) and/or goods according to the rules set by the publisher.
Discovers vAtoms, faces and actions associated with a Discover Container (vAtom::vAtomType::DiscoverContainerType) vAtom owned by the requester. It uses the discover query of the vAtom to dynamically get a list of child vAtoms.
Activates (i.e. unpacks) a package owned by the requester. The Activate action moves all vAtoms contained in the container vAtom out of it and trashes the container.
| Name | Type | Description |
|---|---|---|
[
pre
] | array | List of policies that are executed before the main action. |
[
post
] | array | List of policies that are executed after the main action. |
rule | string | Not yet implemented |
| Name | Type | Description |
|---|---|---|
action_handler | string | Name of the action handler that is executed. |
rule | string | Not yet implemented |
The config object is a generic JSON object, which allows the action publisher to define additional configuration parameters that can be read by the registered reactor during execution. Please see the Examples section of this document for information on what this section should look like for the built-in actions detailed above.
The params object documents the input and output parameters of an action. This object is returned as part of the response payload when a list of actions for a template is requested.
The fields input and output contain an array of strings which represent parameters and response values of the action. All listed parameters are required. If the user should be required to specify one of many parameters, but only one is required and the rest are optional, then they can be represented as a single string with the parameter names separated by a | character.
| Name | Type | Description |
|---|---|---|
on | boolean | Set to true to send a message when the action is executed. |
msg | string | The message content that is sent. |
custom | object | Key, value object with additional configuration parameters. |
| Error | Type | Description |
|---|---|---|
200 | http | Everything is OK |
400 | http | Bad Request |
403 | http | Not Authorized |
{
"name": "publisher_fqdn::Template_Name::v1::Action::Transfer",
"reactor": "blockv://v1/Transfer",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id", "new.owner.email|new.owner.phone_number|new.owner.id"],
"output":["v1::Error"]
},
"config": {
"auto_create_landing_page": "http://viewer.blockv.io/#",
"auto_create_mode": "claim",
"auto_create_non_existing_recipient": true
},
"action_notification": {
"on": true,
"msg": "You received a vAtom",
"custom": {}
}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::Clone",
"reactor": "blockv://v1/Clone",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id", "new.owner.email|new.owner.phone_number|new.owner.id"],
"output":["v1::Error"]
},
"config": {
"auto_create_landing_page": "http://viewer.blockv.io/#",
"auto_create_mode": "claim",
"auto_create_non_existing_recipient": true
},
"action_notification": {
"on": true,
"msg": "You received a vAtom",
"custom": {}
}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::Drop",
"reactor": "blockv://v1/Drop",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id", "geo.pos"],
"output":["v1::Error"]
},
"config": {},
"action_notification": {
"on": false,
"msg": "",
"custom": {}
}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::Pickup",
"reactor": "blockv://v1/Pickup",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id"],
"output":["v1::Error"]
},
"config": {},
"action_notification": {
"on": false,
"msg": "",
"custom": {}
}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::Acquire",
"reactor": "blockv://v1/AcquireWithCoins",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id"],
"output":["v1::Error"]
},
"config": {},
"action_notification": {}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::AcquirePubVariation",
"reactor": "blockv://v1/AcquirePubVariationWithCoins",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id"],
"output":["v1::Error"]
},
"config": {},
"action_notification": {}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::Redeem",
"reactor": "blockv://v1/Redeem",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id", "new.owner.email|new.owner.phone_number|new.owner.id"],
"output":["v1::Error"]
},
"config": {},
"action_notification": {
"on": true,
"msg": "a vAtom has been redeemed",
"custom": {}
}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::Discover",
"reactor": "blockv://v1/Discover",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id"],
"output":["v1::Error"]
},
"config": {},
"action_notification": {}
}{
"name": "publisher_fqdn::Template_Name::v1::Action::Activate",
"reactor": "blockv://v1/PackageActivate",
"wait": true,
"rollback": false,
"abort_on_pre_error": true,
"abort_on_post_error": false,
"abort_on_main_error": true,
"timeout": 10000,
"guest_user": true,
"limit_per_user": 0,
"params":{
"input": ["this.id"],
"output":["v1::Error"]
},
"config": {},
"action_notification": {}
}| Error | Type | Description |
|---|---|---|
200 | http | Everything is OK |
400 | http | Invalid data |
403 | http | Not Authorized |
409 | http | Action already exists |
{
"payload": {
"success_message": "Registered action: name=publisher_fqdn::Template_Name::v1::Action::Transfer"
}
}