It is recommended to get familiar with the concepts of Defined Entity Types, Defined Entities and Interfaces before moving on to Behaviors.
Runtime Defined Entity Behaviors (or just Behaviors) are operations which execute custom logic in VMware Cloud Foundation Automation.
A number of behavior execution types are supported:
Behaviors can be executed on a defined entity via an API call if the user has the necessary access permissions. In addition, behaviors can also be configured to be automatically executed in relation to the defined entity’s lifecycle events (PreCreate, PostCreate, PostUpdate, PreDelete, PostDelete). Behaviors can also be invoked statically without referring to a defined entity.
Behaviors can be scheduled for periodic execution using cron expressions, enabling automated recurring operations.
Behaviors are defined in an Interface (a collection of Behaviors).
POST /cloudapi/1.0.0/interfaces/<interface-id>/behaviors
{
"name": "noopBehavior",
"execution" : {
"type": "noop"
}
}
Response:
{
"name": "noopBehavior",
"id": "urn:vcloud:behavior-interface:noopBehavior:vmware:test:1.0.0",
"ref": "urn:vcloud:behavior-interface:noopBehavior:vmware:test:1.0.0",
"description": null,
"execution": {
"type": "noop"
}
}
API reference can be found here.
Each RDE Type implements one or more interfaces. The behaviors defined in those interfaces can be executed on instances of the RDE Type.
It is possible for the RDE Type definition to override the execution and description of interface behaviors. If an overridden behavior is executed on an instance of that RDE Type, then the behavior defined in the RDE Type will be invoked, rather than the default behavior in the inherited Interface, even if the behavior is specified by its Interface ID.
PUT cloudapi/1.0.0/entityTypes/<entity-id>/behaviors/<behavior-ref>
{
"name": "noopBehavior",
"description": "Some description",
"execution": {
"type": "WebHook",
"id": "testWebHook",
"href": "..." ,
"_internal_key": "...",
"execution_properties": {
"actAsToken": true
}
}
}
Response:
{
"name": "noopBehavior",
"id": "urn:vcloud:behavior-type:noopBehavior:vmware:testType:1.0.0:vmware:test:1.0.0",
"ref": "urn:vcloud:behavior-interface:noopBehavior:vmware:test:1.0.0",
"description": "Some description",
"execution": {
"id": "testWebHook",
"href": "...",
"type": "WebHook",
"execution_properties": {
"actAsToken": true
}
}
}
API reference can be found here.
All types of behavior execution have a common definition structure:
{
"name": "noopBehavior",
"id": "urn:vcloud:behavior-type:behaviorName:typeVendor:typeName:typeVersion:interfaceVendor:interfaceName:interfaceVersion",
"ref": "urn:vcloud:behavior-interface:behaviorName:interfaceVendor:interfaceName:interfaceVersion",
"description": null,
"execution": {
"type": "...",
"execution_properties": {...}
}
}
The behavior execution type is set in the type field of the execution section.
A behavior has both an id and a ref. Their values can be both the same or different. This is depending on whether the behavior is overridden in a Defined Entity Type. More information on how to override a behavior can be found here.
The id property holds the actual behavior id. If the behavior is not overridden, it is a behavior-interface id:
urn:vcloud:behavior-interface:behaviorName:interfaceVendor:interfaceName:interfaceVersion
Otherwise, it is a behavior-type id:
urn:vcloud:behavior-type:behaviorName:typeVendor:typeName:typeVersion:interfaceVendor:interfaceName:interfaceVersion
The ref property always holds a reference to the interface behavior to be used for polymorphic behavior invocations - it always holds the behavior-interface id.
There are some special properties which can be set in the behavior definition execution or execution_properties sections.
scope - static/dynamic - default is dynamic. This property sets the scope of the behavior. If set to dynamic the behavior must be invoked on a RDE instance. If set to static the behavior can be invoked both statically (without a RDE instance) and dynamically. More about static and dynamic behaviors can be found here.
Fields with the prefix _internal_ are write-only. Once they are set, they cannot be obtained through a GET request on the behavior. The field value is saved in the DB in an encrypted form. It is only accessible to VMware Cloud Foundation Automation (e.g. the shared secret in webHook behaviors). These fields can be defined at the top level of the behavior’s execution or execution_properties sections.
"execution": {
"type": "...",
"_internal_key": "...",
"execution_properties": {
"_internal_key_1": "..."
}
}
_secure_ are write-only. Once they are set, they cannot be obtained through a GET request on the behavior. The field value is saved in the DB in an encrypted form. However, this field is accessible to the behavior execution code. This means a different thing in the context of different types of behaviors (i.e. these fields are accessible to the webHook behaviors’ template). These fields can be defined at the top level of the behavior’s execution or execution_properties sections. "execution": {
"type": "...",
"_secure_key": "...",
"execution_properties": {
"_secure_key_1": "..."
}
}
actAsToken - boolean (default is false) – set to true if a VMware Cloud Foundation Automation act-as token needs to be included in the behavior invocation arguments. Depending on the type of behavior an act-as token might be needed in order to make additional API calls to VMware Cloud Foundation Automation. The token invalidates when the behavior execution completes (the behavior invocation task is completed). The token is created on behalf of the user who invokes the behavior. This property is part of the execution_properties section. "execution": {
"type": "...",
"execution_properties": {
"actAsToken": "true"
}
}
Here is a sample API call for creating a behavior:
POST /cloudapi/1.0.0/interfaces/<interface-id>/behaviors
{
"name": "noopBehavior",
"execution" : {
"type": "noop"
}
}
Response:
{
"name": "noopBehavior",
"id": "urn:vcloud:behavior-interface:noopBehavior:vmware:test:1.0.0",
"ref": "urn:vcloud:behavior-interface:noopBehavior:vmware:test:1.0.0",
"description": null,
"execution": {
"type": "noop"
}
}
API reference can be found here.
Behavior invocation is an asynchronous operation in VMware Cloud Foundation Automation since a behavior execution is a long running process. For each behavior invocation, a BEHAVIOR_INVOCATION task is created to track the execution.
Behaviors can be defined as either dynamic or static.
Dynamic behaviors must be invoked in the context of an RDE instance.
Static (or standalone) behaviors do not need to refer to a defined entity instance in order to be invoked. However, such behaviors can be invoked in the context of a defined entity instance as well.
By default, behaviors as created as dynamic. In VMware Cloud Foundation Automation there is the option to define a behavior as static as well.
A dynamic behavior invocation on a defined entity is performed with the following API call:
POST /cloudapi/1.0.0/entities/<entity-id>/behaviors/<behavior-id>/invocations
{
"arguments": {
"x": 7
},
"metadata": {
"convert": true
}
}
Response:
202 Accepted
Headers:
Location: https://<vcfa-host>/api/task/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API reference can be found here.
The <entity-id> represents the id of the entity which the behavior will be invoked on.
A static/standalone behavior invocation is performed with the following API call:
POST /cloudapi/1.0.0/interfaces/<interface-id>/behaviors/<behavior-id>/invocations
Response:
202 Accepted
Headers:
Location: https://<vcfa-host>/api/task/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API reference can be found here.
The <interface-id> is the id of the interface which the behavior is defined in.
When invoking a behavior, an API user can supply arguments and metadata to the behavior invocation. Apart from user-defined arguments, the behavior code might also receive additional metadata information upon execution. The metadata depends on the specific type of behavior execution.
The user defined invocation arguments are defined in the body of the behavior invocation request.
{
"arguments": {
"x": 7,
...
},
"metadata": {
"convert": true,
...
}
}
The different types of behavior execution types have a different format of the payload which the custom execution code receives. More detailed information for each behavior execution type can be found in the dedicated documentation for this execution type:
Each behavior invocation is tracked by a BEHAVIOR_INVOCATION task. Once the behavior execution is completed, the tracking task will also be completed. If the behavior execution is successful, the task will succeed and the result of the execution will be in the result field of the task. If the behavior execution fails, the task will also fail with the appropriate error in the error field of the task.
All behavior execution types return results as JSON-encoded strings in the task’s result.resultContent field:
{
"result": {
"resultContent": "{\"key\":\"value\"}", // Always a JSON-encoded string
"resultReference": null
}
}
This applies to:
The execution result is always a JSON-encoded string (or null).
API call to get a task:
GET /api/task/<task-id>
Response:
{
"otherAttributes": {},
"link": [
{
"otherAttributes": {},
"href": "https://127.0.0.1:8443/api/task/d5ca75e4-9d14-4a9e-98d2-1fbdb4ce7d97",
"id": null,
"type": "application/vnd.vmware.vcloud.task+xml",
"name": "task",
"rel": "edit",
"model": null,
"vCloudExtension": []
},
{
"otherAttributes": {},
"href": "https://127.0.0.1:8443/api/task/d5ca75e4-9d14-4a9e-98d2-1fbdb4ce7d97",
"id": null,
"type": "application/vnd.vmware.vcloud.task+json",
"name": "task",
"rel": "edit",
"model": null,
"vCloudExtension": []
}
],
"href": "https://127.0.0.1:8443/api/task/d5ca75e4-9d14-4a9e-98d2-1fbdb4ce7d97",
"type": "application/vnd.vmware.vcloud.task+json",
"id": "urn:vcloud:task:d5ca75e4-9d14-4a9e-98d2-1fbdb4ce7d97",
"operationKey": null,
"description": null,
"tasks": null,
"name": "task",
"owner": {
"otherAttributes": {},
"href": "",
"id": "urn:vcloud:entity:vmware:testType:92016846-f98b-400e-aa4b-db4a4c6b9007",
"type": "application/json",
"name": "entity",
"vCloudExtension": []
},
"error": null,
"user": {
"otherAttributes": {},
"href": "https://127.0.0.1:8443/api/admin/user/3b81c0f4-5463-4177-aa6c-26e603323d6c",
"id": "urn:vcloud:user:3b81c0f4-5463-4177-aa6c-26e603323d6c",
"type": "application/vnd.vmware.admin.user+xml",
"name": "administrator",
"vCloudExtension": []
},
"organization": {
"otherAttributes": {},
"href": "https://127.0.0.1:8443/api/org/a93c9db9-7471-3192-8d09-a8f7eeda85f9",
"id": "urn:vcloud:org:a93c9db9-7471-3192-8d09-a8f7eeda85f9",
"type": "application/vnd.vmware.vcloud.org+xml",
"name": "System",
"vCloudExtension": []
},
"progress": null,
"params": null,
"details": "",
"vcTaskList": {
"otherAttributes": {},
"vcTask": [],
"vCloudExtension": []
},
"result": { // the behavior result
"resultContent": "{\"arguments\":{\"x\":7},\"entityId\":\"urn:vcloud:entity:vmware:testType:92016846-f98b-400e-aa4b-db4a4c6b9007\",\"typeId\":\"urn:vcloud:type:vmware:testType:1.0.0\",\"entity\":{\"entity\":{\"vm\":{\"name\":true}}}}",
"resultReference": null
},
"status": "success",
"operation": "Invoked noopBehavior test(urn:vcloud:entity:vmware:testType:92016846-f98b-400e-aa4b-db4a4c6b9007)",
"operationName": "executeBehavior",
"serviceNamespace": "com.vmware.vcloud",
"startTime": "2024-03-06T14:11:57.473+0200",
"endTime": "2024-03-06T14:11:59.989+0200",
"expiryTime": "2024-06-04T14:11:57.473+0300",
"cancelRequested": false,
"vCloudExtension": []
}
Dynamic behaviors have an access control mechanism for execution based on the RDE instance which the behavior is invoked on. The access controls are defined in the defined entity type scope. They specify what minimum level of access an API user must have to a defined entity instance of that type in order to invoke a specific behavior on that defined entity instance. If no behavior access control is created for a specific RDE Type and a specific behavior, then this behavior is effectively not executable on any of the RDE instances of the type.
Behavior executions are not subject to any access control rules if the execution is initiated as a RDE lifecycle hook execution.
Example API call to create a behavior access control:
POST /cloudapi/1.0.0/entityTypes/<entity-type-id>/behaviorAccessControls
{
"behaviorId": "<behavior-id>",
"accessLevelId": "urn:vcloud:accessLevel:ReadWrite"
}
API reference can be found here.
The possible access levels are:
urn:vcloud:accessLevel:ReadOnly - if accessLevelId is set to this value, an API user must have at least RO (read-only) access to a defined entity instance in order to invoke the behavior with id <behavior-id> on that defined entity instance.urn:vcloud:accessLevel:ReadWrite- if accessLevelId is set to this value, an API user must have at least RW (read-write) access to a defined entity instance in order to invoke the behavior with id <behavior-id> on that defined entity instance.urn:vcloud:accessLevel:FullControl- if accessLevelId is set to this value, an API user must have FC (full control) access to a defined entity instance in order to invoke the behavior with id <behavior-id> on that defined entity instance.More information on RDE access control can be found here.
Currently, static behaviors do not have an access control mechanism for execution.
Behaviors can be configured to execute at the different lifecycle stages of a defined entity:
More information on RDE lifecycle hooks can be found here.