Cloud Events Base Extension

Version: 27.0.0.0 Publisher: Origo App ID: 54db7020-675c-4760-aca6-f4061f924ed2 ID Range: 65300-65399 Target Platform: Business Central Cloud (27.0+) Languages: en-US, is-IS

Overview

Cloud Events Base is a comprehensive Business Central extension that provides REST API endpoints for processing cloud events following the CloudEvents 1.0 specification. The extension enables external systems to interact with Business Central through standardized event-driven messaging patterns for data integration, metadata queries, sales operations, and business logic calculations.

Key Features

• Three REST API Endpoints: Queue (asynchronous), Task (synchronous), and Data (response retrieval)
• Message Types Across Core Integration Areas: Covering data records, deleted record sync, metadata, field translations, notifications, sales operations, purchase operations, finance operations, change log history/restore, incoming documents, memory storage, and business calculations
• Interface-Based Architecture: Extensible design using strategy pattern for message processing
• Field-Level Security: User-based field access restrictions for Data.Records.Get/Set operations
• ChangeLog Write Guard: Configurable guard for Data.Records.Set — Open, Blocked, or Via-force modes with permission-gated bypass. Extensible via interface/enum.
• Draft Email Creation: Email.Draft.Set creates Business Central email drafts with HTML body, CC/BCC recipients, optional URL-based attachments, and setup-driven email scenario resolution.
• Incoming Document Workflow: Full lifecycle support — Create, Attach supplemental files, Process to purchase invoice or journal line, and Get with all attachments as Base64.
• Webhook Notifications: External Business Events for completed/failed message processing
• Background Task Scheduling: Non-blocking asynchronous processing with error handling
• Multi-Language Support: Language context management for international operations
• CloudEvents 1.0 Compliance: Standard HTTP/JSON payload structure with required attributes

Functional Flow

API Endpoints

1. Cloud Event Queue API (/cloudEventQueue)

• Purpose: Asynchronous message submission
• Method: POST
• Behavior: Accepts CloudEvents JSON payload, validates structure, schedules background task, returns 202 Accepted
• Actions: GetStatus (poll processing status), RetryTask (requeue failed messages), CancelTask (cancel running tasks)
• Use Case: Long-running operations, batch processing, non-blocking integrations

2. Cloud Event Task API (/cloudEventTask)

• Purpose: Synchronous message processing
• Method: POST
• Behavior: Processes message immediately, returns response data inline, returns 200 OK with response payload
• Use Case: Real-time queries, immediate feedback required, low-latency operations

3. Cloud Event Data API (/cloudEventData)

• Purpose: Retrieve processed message responses
• Method: GET
• Parameters: Filter by MessageId to retrieve specific response
• Behavior: Returns response JSON from completed asynchronous messages
• Use Case: Polling for async results, retrieving historical message data

Message Processing Flow

External System → POST /cloudEventQueue (JSON payload)
                ↓
    Validate CloudEvents structure (id, source, type, subject, data)
                ↓
    Store in Cloud Event Message table (Direction: Incoming)
               | --- | --- |
    Schedule background task (TaskScheduler.CreateTask)
                ↓
    [Background Processing]
               | --- | --- |
    Dispatch to interface implementation based on MessageType
                ↓
    Execute business logic (read/write data, calculations)
                ↓
    Store response in Cloud Event Message table (Direction: Outgoing)
                ↓
    Raise External Business Event (OnCloudEventMessageCompleted)
                ↓
    Webhook notification sent to subscribers (MessageId, MessageType, ResponseContentLink, Timestamp)
                ↓
External System ← GET /cloudEventData (retrieve response using MessageId)

Webhook Notification Pattern

The extension uses Business Central's native External Business Events for webhook notifications:

1. Minimal Notification Payload: Webhooks send only essential data (MessageId, MessageType, ResponseContentLink, Timestamp)
2. Direct Download Link: External systems can use ResponseContentLink for direct data download, or use MessageId to call /cloudEventData API
3. Event Types:

• OnCloudEventMessageCompleted: Raised when message processing succeeds
• OnCloudEventMessageFailed: Raised when message processing fails

1. Event Category: "Origo Cloud Event" (EventCategory extension)

Message Type Processing Flow

All cloud event messages follow a consistent processing pattern:

1. Message Validation – CloudEvents specification fields are validated (specversion, type, source)
2. Type Resolution – Message type enum determines which implementation to use
3. Interface Execution – Message type implements Cloud Event Msg Interface and executes business logic
4. Response Generation – Implementation generates response data in appropriate format (JSON, Markdown, XML, etc.)
5. Storage – Response is stored in the message record's response data blob
6. Delivery – Response is returned to caller (synchronous) or made available for retrieval (asynchronous)

Built-in Message Types

Extensibility Pattern

The extension provides five key extensibility points through AL interfaces:

1. Cloud Event Message Interface

Interface: Cloud Event Msg Interface Extensible Enum: Cloud Event Message Type (65300)

Allows creation of custom message types by:

1. Creating a codeunit that implements Cloud Event Msg Interface
2. Adding a new value to Cloud Event Message Type enum with the implementation binding
3. Implementing the ExecuteCloudEventTask() method to define custom business logic

2. Customer Credit Limit Interface

Interface: Customer Credit Limit Extensible Enum: Customer Credit Limit Type (65303) Setup Field: Cloud Events Setup → Customer Credit Limit Type

Allows custom credit limit calculation logic. Built-in implementation:

• Default Credit Limit – Uses standard Business Central credit limit calculations with configurable tolerance percentage

3. Item Availability Interface

Interface: Item Calc. Availability Extensible Enum: Item Calc. Availability Type (65304) Setup Field: Cloud Events Setup → Item Calc. Availability Type

Allows custom item availability calculations. Built-in implementations:

• Physical Inventory – Calculates availability based on physical inventory from item ledger entries
• Calculated Quantity – Uses Business Central's standard availability calculation engine

4. Item Price Calculation Interface

Interface: Item Price Calculation Extensible Enum: Item Price Calculation Type (65305) Setup Field: Cloud Events Setup → Item Price Calculation Type

Allows custom price calculation logic. Built-in implementations:

• Default Price – Uses item's unit price from item card
• Sales Price Header Handler – Retrieves prices from sales price lists with customer/date filtering

5. Customer Statement Interface

Interface: Customer Statement Extensible Enum: Customer Statement Type (65306) Setup Field: Cloud Events Setup → Customer Statement Type

Allows custom customer statement generation. Built-in implementation:

• Standard Statement – Uses BC Report Selections for C.Statement to generate the PDF

Benefits

Extensibility

• Interface-Based Design: Implement Cloud Event Msg Interface to add custom message types
• Integration Events: OnBeforeCloudEventMessageProcessing, OnAfterCloudEventMessageCompleted, OnAfterCloudEventMessageFailed for extending processing logic
• Version Support: Cloud Event Message Version enum allows multiple implementation versions
• Business Logic Interfaces: Four additional interfaces (Customer Credit Limit, Item Calc. Availability, Item Price Calculation, Customer Statement) allow custom implementations without code modification

Scalability

• Asynchronous Processing: Background tasks prevent blocking during long operations
• RESTful Architecture: Stateless APIs support horizontal scaling
• Minimal Webhook Payloads: Reduces network overhead and improves security

Operational Efficiency

• Standardized Protocol: CloudEvents 1.0 compliance enables integration with standard tools
• Error Handling: Automatic error capture with retry capabilities via task scheduler
• Language Context Management: Preserves user language context during background processing
• Self-Documenting API: Help message types provide runtime discovery of available functionality

Business Value

• Real-Time Integrations: Customer credit limits, item availability, pricing calculations
• Sales Automation: Order release/reopen, PDF document generation, order statistics
• Data Synchronization: Bi-directional record synchronization via Data.Records.Get/Set
• Metadata Discovery: Help APIs for fields, tables, message types, permissions

Logic Flow

Message Processing (Technical)

1. API Page Receives Request

• Queue API (CloudEventQueueAPI.Page.al) or Task API (CloudEventTaskAPI.Page.al) receives POST request
• Message fields are mapped from JSON body to Cloud Event Message table record

1. Message Persistence

• Record is inserted into table 65300 Cloud Event Message
• System assigns unique GUID identifier
• Timestamp is recorded in date & time field

1. Task Scheduling (Queue API Only)

• Background task is created using TaskScheduler.CreateTask()
• Task ID is stored in the message record
• Codeunit 65313 Cloud Event Message Task is scheduled for execution

1. Message Type Resolution

• Enum field type determines which implementation to invoke
• Enum value implements interface Cloud Event Msg Interface
• Implementation codeunit is instantiated

1. Argument Preparation

• Temporary record of table 65301 Cloud Event Message Argument is populated
• Request data is loaded from message blob
• Message metadata (subject, source, content type) is copied to argument

1. Interface Execution

• Method ExecuteCloudEventTask() is invoked on the interface implementation
• Implementation reads request data from argument record
• Business logic is executed (query data, process records, etc.)
• Response data is written to argument record

1. Response Storage

• Argument's response data is written to message record's response blob
• Content type is updated based on implementation (application/json, text/markdown, etc.)
• Message record is modified and committed

1. Error Handling

• If error occurs, codeunit 65312 Cloud Event Message Error is invoked
• Error details are written to response data as JSON
• Content type is set to text/json with error structure

1. Task Completion

• Background task completes (Queue API) or returns immediately (Task API)
• External system retrieves response via Data API or from direct response body

Setup & Configuration

Cloud Events Setup

The extension includes a Cloud Events Setup table (65302) and page (65307) accessible from the Administration area. Configuration options include:

To access the setup page, search for "Cloud Events Setup" in Business Central.

Field Access Restrictions

The extension includes Cloud Events Field Accesses page (65309) for managing user-level field access restrictions. This feature allows administrators to:

• Restrict Read Access: Prevent specific fields from appearing in Data.Records.Get responses
• Restrict Write Access: Block field modifications in Data.Records.Set operations
• Restrict Both: Completely hide and protect fields from read and write operations
• Bypass Write Guard: Allow the ChangeLog Write Guard to pass writes for a specific field without requiring Change Log coverage (field-scoped, not user-scoped)
• Per-User Control: Apply different restrictions to different users or AAD applications
• Table/Field Granularity: Target specific fields in specific tables

Restriction Types:

• Both (default): Most restrictive - blocks both read and write access
• Read: Prevents field from appearing in GET responses (write still allowed)
• Write: Allows reading but prevents modification via SET operations
• Bypass: Exempts the field from Write Guard evaluation — allows API writes regardless of Change Log coverage. Does not restrict read or write access.

To access field restrictions, search for "Cloud Events Field Accesses" in Business Central. See Field Access Restrictions documentation for detailed setup instructions and use cases.

Permission Requirements

Users or service accounts accessing the API endpoints must be assigned one of the following permission sets:

• Cloud Events Full (65300) – Full read/write access to all Cloud Events objects including message creation, modification, and deletion
• Cloud Events Read (65301) – Read-only access to Cloud Events messages and setup for monitoring and reporting purposes

API Endpoint Configuration

API endpoints are published at:

• Queue API: /api/origo/cloudEvent/v1.0/queues
• Task API: /api/origo/cloudEvent/v1.0/tasks
• Data API: /api/origo/cloudEvent/v1.0/responses

Authentication follows standard Business Central web service authentication (OAuth 2.0 or Basic Auth depending on deployment).

Retention Policy

The extension registers the Cloud Event Message table with Business Central's retention policy framework, allowing administrators to automatically delete old message records based on the date & time field.

Example Scenario

Scenario: Query Customer Credit Limit

Objective: External system needs to check available credit for a customer before accepting an order.

Step 1: Submit Asynchronous Request

POST https://<bc-instance>/ODataV4/Company('<company-name>')/cloudEventQueue
Content-Type: application/cloudevents+json

{
  "specversion": "1.0",
| --- | --- |
  "source": "https://external-system.example.com",
  "type": "Customer.CreditLimit.Get",
  "subject": "CUST-10000",
  "datacontenttype": "application/json",
  "time": "2024-01-15T14:30:00Z",
  "data": {
    "CustomerNo": "CUST-10000"
  }
}

Response: 202 Accepted

Step 2: Subscribe to Webhook (One-Time Setup)

Configure webhook subscription in Business Central:

• Navigate to Event Subscriptions
• Subscribe to OnCloudEventMessageCompleted event
• Provide webhook endpoint URL
• Business Central will send notifications when messages complete

Step 3: Receive Webhook Notification

Your webhook endpoint receives:

{
  "MessageId": "credit-check-001",
  "MessageType": "Customer.CreditLimit.Get",
  "ResponseContentLink": "/api/origo/cloudEvent/v1.0/responses(credit-check-001)/data",
  "Timestamp": "2024-01-15T14:30:02Z"
}

Step 4: Retrieve Response Data

GET https://<bc-instance>/ODataV4/Company('<company-name>')/cloudEventData?$filter=MessageId eq 'credit-check-001'

Response:

{
  "value": [
    {
      "MessageId": "credit-check-001",
      "MessageType": "Customer.CreditLimit.Get",
      "Direction": "Outgoing",
      "ResponseData": "{\"CustomerNo\":\"CUST-10000\",\"CreditLimit\":50000.00,\"Balance\":35000.00,\"AvailableCredit\":15000.00}",
      "ResponseTime": "2024-01-15T14:30:02Z"
    }
  ]
}

Alternative: Synchronous Request

For immediate response without webhook callback:

POST https://<bc-instance>/ODataV4/Company('<company-name>')/cloudEventTask
Content-Type: application/cloudevents+json

{
  "specversion": "1.0",
  "id": "credit-check-sync-001",
  "source": "https://external-system.example.com",
  "type": "Customer.CreditLimit.Get",
  "subject": "CUST-10000",
  "datacontenttype": "application/json",
  "data": {
    "CustomerNo": "CUST-10000"
  }
}

Response: 200 OK with response data inline

Objects

Dependencies

No external dependencies. This extension runs on standard Business Central platform capabilities only.

Documentation

Context-Sensitive Help

The extension provides built-in context-sensitive help pages for all user-facing pages in both English and Icelandic. When a user presses the help button on any page in Business Central, they are directed to the corresponding help page for their locale.

Help pages are located in the app/Help/ folder:

• English (en-US): app/Help/en-US/
• Icelandic (is-IS): app/Help/is-IS/

Each language folder contains an index.html home page with a table of contents linking to individual page help files.

Internal Documentation

Detailed documentation is available within the extension:

• Message Type Documentation: Each message type includes Help codeunits with JSON schema examples, required fields, and usage instructions
• API Reference: Located at app/docs/en-us/API_Reference.md
• Message Type References:
• Data Message Types
• Metadata Message Types
• Sales Message Types
• Purchase Message Types
• Finance Message Types
• Notification Message Types
• Memory Message Types
• Setup Reference: app/docs/en-us/Setup_Reference.md
• Field Access Restrictions: app/docs/en-us/Field_Access_Restrictions.md
• Events & Webhooks: app/docs/en-us/Events_and_Webhooks.md

CloudEvents Specification

This extension implements the CloudEvents 1.0 Specification.

Required CloudEvents Attributes:

• specversion: "1.0"
• id: Unique message identifier (used for response retrieval)
• source: URI identifying the context in which the event occurred
• type: Message type (e.g., "Customer.CreditLimit.Get")
• subject: Business entity identifier (e.g., customer number, item code)

Optional Attributes:

• datacontenttype: MIME type of data payload (default: "application/json")
• time: Timestamp when event occurred (RFC 3339 format)

Note for Data message types: Data.Records.Get and Data.Records.Set also accept the table identification in the subject field — both a table name (e.g., "Customer") and a numeric table ID (e.g., "18") are supported. The JSON data payload parameters tableName / tableNumber take precedence when both are provided.

Support

For questions, issues, or feature requests, contact Origo support or refer to internal Confluence documentation.

© 2026 Origo. All rights reserved.

© Origo – Cloud Events Base Extension