Skip to content
Hantera Developer Portal Developer Portal

Actors

Business entities in Hantera are modeled as actors. Actors can be explained as individual processes that perform work based on received messages. There are different types of actors responding to different types of messages. For a complete reference of each actor’s messages and functionality, refer to the Actor Types section.

The actor API provides a unified way to interact with any type of actor using a standardized API.

Identifiers

Each actor may provide multiple identifiers. Every actor has a UUID identifier, but may provide additional IDs as well. An example of this is the Order actor, which along with its orderId, can also be accessed using its natural orderNumber key:

These paths may point to the same actor instance:

/resources/reference/actors/order/6e558257-f67c-45e5-b013-1f36fbb4c944
/resources/reference/actors/order/ORD12345

There are also some actors that provide virtual identifiers. For example, the Order actor provides the virtual actor new to create a new order that will be assigned unique identifiers automatically. The newly generated identifiers will be included in the response.

Sending Messages

A single transaction may include multiple messages sent to the same actor, although each message is processed individually in the order that they appear.

POST https://<hantera-hostname>/resources/reference/actors/order/a2daafde-ffaa-4beb-bb81-4ac163262c89
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json


[{
  "type": "applyCommands",
  "body": {
    "commands": [{
        "type": "createOrderLine",
        "deliveryId": "65812410-bd14-4d6d-ab79-374789a976c1",
        "productNumber": "P1",
        "quantity": 1,
        "unitPrice": 90,
        "taxFactor": 0.25
      }
    ]
  }
}]

Previewing

A powerful feature of actors is the preview mode. Messages sent as preview will all be performed in a transient transaction and will not be stored. This allows for testing messages and seeing the outcome. A common use case is to preview what an order will look like after a certain change is made. For more detailed examples, refer to the Actor Types section.

For the sake of the API, using preview is as simple as adding the ?preview querystring to the actor’s message endpoint:

POST https://<hantera-hostname>/resources/reference/actors/order/new?preview
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json


[{
  "type": "create",
  "body": {
    "currencyCode": "EUR",
    "taxIncluded": true,
    "commands": [{
        "type": "createDelivery",
        "deliveryId": "65812410-bd14-4d6d-ab79-374789a976c1",
        "shippingPrice": 100
      },{
        "type": "createOrderLine",
        "deliveryId": "65812410-bd14-4d6d-ab79-374789a976c1",
        "productNumber": "P1",
        "quantity": 1,
        "unitPrice": 90,
        "taxFactor": 0.25
      }
    ]
  }
}]

Commands

Many actors utilizes commands to execute operations in a single transaction. Commonly the message applyCommands is used, but other message types may support commands as well. Additionally, rules within Hantera can emit commands from some hooks to automate mutations based on specific events.

Not every mutation is available as a command. Some processes must be done using a single message.

Batch Processing of Commands

Commands are always processed in a single batch. This means that all commands submitted together are executed as one atomic operation. If any command within the batch fails, the entire batch is rejected, and no changes are applied to the system. This all-or-nothing approach ensures data integrity and consistency across the platform.

This is different from messages that are processed in sequence. If a single message fails, the others will still be processed even if they are sent in the same request. Commands are used for simple mutations within the actor and will never have side-effects outside the current actor. Messages on the other hand, may cause side-effects in other actors.

Access Control

The ACE for actors looks like this:

actors/<type>[/<id>]:<message type>

Note that the ID used for authorization must be the global UUID for the actor.