Skip to content

Data Box - Technical Reference

Entities

1. DataBoxAccount

Represents a connection to an ISDS account. * Scope: Administration * Key Fields: * login (Varchar): ISDS Login. * password (Password): Encrypted password. * dev (Boolean): Toggles between Production and Test environment endpoints. * users (Link): Users authorized to use this account.

2. DataBoxMessage

Represents a single message (sent or received). * Key Fields: * dmId (Varchar): Unique ISDS Message ID. * status (Enum): Draft, Sending, Sent, Delivered, Received. * from (Varchar): Sender ID (ISDS ID). * to (Varchar): Recipient ID. * attachments (Link): Linked Attachment entities (files). * dataBoxAccountId (Link): The account used for this message.

Service Architecture

Core Logic: Espo\Modules\DataBox\Tools\DataBox\Service

This service handles all interactions with the Czech Data Box API.

Methods

  • checkDataBox(string $id, int $daysBack = 90)

    • Orchestrator for synchronization. Calls checkDataBoxReceived and checkDataBoxSent.
    • $id: ID of the DataBoxAccount.
    • $daysBack: How far back to check for messages (default 90 days).

  • createMessage(tRecord $messageRecord, ...)

    • Input: tRecord object (from Defr\CzechDataBox library).
    • Process:
      1. Extracts metadata (Sender, Recipient, Annotation).
      2. Fetches attachments via getReceivedDataMessageAttachmentsRaw.
      3. Decodes base64 content and creates CRM Attachment entities.
      4. Creates DataBoxMessage entity.
      5. Calls applyFilters() (custom logic hooks).
      6. Calls noteDataBoxMessageReceived() to update the Activity Stream.

  • send(DataBoxMessage $message, User $user)

    • Process:
      1. Validates user permissions for the DataBoxAccount.
      2. Constructs DataMessage object.
      3. Calls api->sendDataMessage().
      4. Updates status to Sent.
      5. Adds "Sent" note to the Activity Stream.

  • noteDataBoxMessageReceived/Sent

    • Creates a Note entity linked to the parent record (e.g., Account, Contact).
    • Uses DefaultParentFinder to determine which entity to link to (based on ISDS ID matching).

Integration Library

The module relies on the dfr/czech-data-box PHP library (wrapped in Espo\Modules\DataBox\Tools\CzechDataBox\DataBox).

  • Namespace: Defr\CzechDataBox\Api
  • Key Classes:
    • tRecord: Represents a message record.
    • DataMessage: Represents the payload for sending.