Arkipel Message Specifications

This section documents all message types supported by Arkipel communities. Each message type includes:

  • Description
  • Request schema
  • Request attributes
  • Response schema

Global Request Attributes (for all messages)

  • payload.type (Message Type)
  • signature
  • source_public_key

NOTE: In the request and response examples, only the minimum required attributes are shown, except otherwise

Search Request Attributes (for query messages)

Inside a payload.q hash:

  • per_page - Integer - How many records to be returned per page
  • page - Integer - Page number to be returned

Search Response Attributes (for query messages)

Inside a payload.q hash:

  • per_page - Integer - How many records returned per page
  • page - Integer - Page number returned
  • total - Integer - Total records count

Queries (Read Operations)

Distributions

Status Message Type Description Documentation
📅 distributions:query Retrieve a list of distributions. View

Distribution Templates

Status Message Type Description Documentation
📅 distribution_templates:query Retrieve a list of distribution templates. View

Forms

Status Message Type Description Documentation
📅 forms:query Retrieve a list of forms supported by the community. View

People

Status Message Type Description Documentation
📅 people:query Retrieve a list of people. View
✅ person:query Retrieve a single person by ID. View

Person Categories

Status Message Type Description Documentation
✅ person_categories:query Retrieve a list of person categories. View

Mutations (Write/Destroy Operations)

Procurements

Status Message Type Description Documentation
🚧 procurements:upsert Create a procurement or update a single procurement by ID. View
❌ procurement:delete Delete a single procurement by ID. View

Distributions

Status Message Type Description Documentation
📅 distributions:upsert Create a distribution or update a single distribution by ID. View
❌ distribution:delete Delete a single distribution by ID. View

Forms

Status Message Type Description Documentation
📅 forms:fill Fill a form. View

People

Status Message Type Description Documentation
🚧 people:upsert Create a person or update a single person by ID. View
❌ person:delete Delete a single person by ID. View

System Messages

Status Message Type Description Documentation
✅ ping Check connection health. View
✅ arkipel_messages:query Query a message from a given ID View

Asynchronous Message Processing

When sending mutation messages (e.g., people:upsert, procurements:upsert), the response will not immediately include the created, updated, or destroyed resource. Instead, the message will be processed asynchronously—either queued for background processing or pending user validation.

Response Structure

The response will always include a message_id, which serves as a reference to track the status or result of the operation. You can use this message_id to query the outcome later using the arkipel_messages:query message type.

How to Retrieve Results

  1. Store the message_id from the response.

  2. Query the status by sending an arkipel_messages:query message with the message_id:

    {
  "type": "arkipel_messages:query",
  "message_id": "6916452112f746b2b4cf48c1"
}
  3. The response will include the final state of the operation (e.g., success, failure, or pending).

Why This Approach?

  • Decoupling: Allows for background processing, user validation, or delayed execution.
  • Reliability: Ensures integrators can always retrieve the result, even if processing takes time.

Key Points to Highlight

  • Asynchronous by Design: Mutations are not blocking; the system acknowledges receipt but processes them later.
  • Tracking: The message_id is your reference to poll or subscribe for updates.
  • Idem-potency: The same message_id can be queried multiple times for consistency.

Sequence Diagram

Glossary

Message Implementation Status

Emoji Status Meaning
✅ Implemented Message is fully implemented
🚧 In Progress Currently being worked on
❌ Not Implemented Not started or not planned yet
📅 Planned Scheduled for future implementation
🗑️ Deprecated Message is deprecated