Skip to content
Public API/
/
Standard Metadata Headers

Standard Metadata/Headers

Architecture Approved

Overview

Standard Message Headers define the required metadata fields for HSOne service communication across HTTP and Kafka protocols.

Standard Metadata Schema Examples

Field Definitions

Field NameStatusAliasRequirement DescriptionTypeHTTPKafka
sessionIdDecided—Async routingStringOPTIONALOPTIONAL
messageIdDecidedcorrelationID, idempotencyIDOrigination strategy. To be used for idempotency checks and as the correlation id for related messages.String (UUID Recommended)REQUIREDREQUIRED
createdOnDecided—Generated for each new messageLong (representing epoch in milliseconds)REQUIREDREQUIRED
tenantIdTypeDecided—[ACCOUNT_ID, SERIAL_NUMBER, CUSTOMER_NUMBER] *default = CUSTOMER_NUMBER. Others should be approved and added to this document. CUSTOMER_NUMBER should represent only a child-most account.String (represents enum)REQUIREDREQUIRED
tenantIdDecidedsalesforce accountId, customerNumber, SerialNumber⚠️ Warning: An HSOne OrgId needs to become an engineering/architecture priority and is essential to ensuring data is processed securely. We are currently using salesforce accountId for lack of a better current option but should be considered expensive technical debt.StringREQUIREDREQUIRED
userIdREVIEWINGclientIdAuth0 userId or Auth0 clientId for M2M. We should get more clarity on this as the Auth0 projects move forward. Must be provided but can be either a user ID or a machine ID if a user ID is not available. Use the first identifiable system. Get as close to the initial request as possible. Should we add UserIdType?StringREQUIREDREQUIRED
systemIdUNDECIDED—This is the system user———
applicationIdDecided—[DENTRIX_CORE, DENTRIX_ENTERPRISE, ASCEND, etc] Originating application id (mostly useful for on-prem applications where we do not have proper identity/auth solutions)String (represents enum)OPTIONALOPTIONAL
applicationVersionUNDECIDED—Version number for originating applicationStringOPTIONALOPTIONAL
isSyntheticUNDECIDED—A marker for synthetic test data that can be filtered out of the streaming before triggering non-idempotent events. Synthetics can be generated by test and APM tooling to validate continuous uptimes and SLOs.boolean (default false)OPTIONALOPTIONAL

Example Workflow

This example demonstrates how standard metadata flows through a multi-service architecture:

Scenario: Salesforce → CRM-Service → Licensing-Service → Voice-Perio-Service → Bola

  1. Salesforce triggers event originating from Salesforce by assigning "Voice-Perio" product to a practice's account. Using Confluent Cloud Connector for Salesforce, event is published to:

    private.crm.salesforce.order_change_delta_event.1

  2. CRM-Service consumes Salesforce event, and calls Licensing-Service through sync API call:

    POST https://licensing-service.dev-dentalapp.cc/api/license

  3. Licensing-Service receives command request via API then:

    • Publishes a command to:
      private.licensing.license.command.1
    • Consumes command request, stores event data and publishes event to:
      public.licensing.license.event.1

  4. Voice-Perio-Service consumes LicenseEvent then:

    • Calls Bola API to provision a new Bola Account for the practice
    • POSTs a ResourceCommandRequest to:
      POST https://licensing-service.dev-dentalapp.cc/api/resource

  5. Licensing-Service receives command request then:

    • Publishes a command to:
      private.licensing.resource.command.1
    • Consumes command request, stores event data and publishes ResourceEvent to:
      public.licensing.resource.event.1

  6. Licensing-Service receives ResourceEvent then:

    • Publishes a command to update the LicenseStatus from "PROVISIONING" to "PROVISIONED":
      private.licensing.license.command.1
    • Consumes command request, makes change, then stores event data and publishes LicenseEvent to:
      public.licensing.license.event.1

Key Considerations

TenantId Warning

An HSOne OrgId needs to become an engineering/architecture priority and is essential to ensuring data is processed securely. We are currently using Salesforce accountId for lack of a better current option but should be considered expensive technical debt.

MessageId (Idempotency)

The messageId field serves dual purposes:

  • Idempotency checks: Prevents duplicate message processing
  • Correlation ID: Links related messages across services

Use UUID format for globally unique identifiers.

Synthetic Data Filtering

The isSynthetic flag allows test and APM tooling data to be filtered from production event streams before triggering non-idempotent operations.

Previous page
Next page