Databox Integrations

Introduction

In Databox, an integration is a functional bridge either between Phrasea modules or between Phrasea and a third-party service. Integrations can be triggered by workflow events (for example during asset ingest) or by user actions. Their goal is to automate technical steps that would otherwise require manual operations between Phrasea and external tools.

Why integrations are useful

Integrations are used to interconnect Phrasea with external systems in a reliable and repeatable way. They provide practical value by:

• Automating processing tasks during file ingest.
• Normalizing data exchanged between Phrasea and external services.
• Keeping synchronized states between Phrasea objects and external resources.

Rendition integration (core.rendition)

Display name: Rendition

This integration builds media renditions based on workspace rendition definitions. For each rendition definition, it creates a workflow job and executes rendition generation through the rendition build action.

Main behavior:

• Loads rendition definitions for the workspace.
• Creates one workflow job per definition.
• Applies parent/child dependencies between jobs when a definition has a parent.
• Runs generation in dependency order so child renditions wait for parent renditions.

Operational notes:

• Rendition definitions must exist in the workspace configuration.
• Dependency chains are strict: a missing parent definition breaks the expected build sequence.
• This integration is part of workflow orchestration, not a manual user action.

Expose integration (phrasea.expose)

Display name: Expose

This integration connects Phrasea baskets to the Expose publication service. It is a basket-oriented integration driven by user actions and asynchronous synchronization.

Main behavior:

• Supports user actions: sync, force-sync, and stop.
• On sync, creates a publication in Expose and stores the publication ID in integration data.
• Dispatches asynchronous basket synchronization messages after creation and on basket updates.
• Transforms stored publication data to expose useful URLs (public URL and edit URL).

Operational notes:

• Requires a valid OAuth integration token to call Expose API endpoints.
• Requires configuration of baseUrl, clientId, and clientUrl.
• The Redirect URI generated by Phrasea must be allowed in Expose OAuth client settings.
• Scope is basket context only.

Read Metadata integration (core.read_metadata)

Display name: Read Metadata

This integration extracts technical metadata from the asset source file during asset ingest workflows. It reads raw file metadata, normalizes it, then stores normalized metadata on the source file entity.

Main behavior:

• Only runs on asset ingest workflows.
• Executes only when the asset has a source file.
• Fetches the source file, reads metadata, normalizes metadata, and persists it.
• Triggers attribute initialization after metadata extraction in the workflow chain.

Operational notes:

• If no source file exists, the action is skipped.
• Metadata is stored on the file linked to the asset source.
• File retrieval must succeed for extraction to complete.

Uploader integration (phrasea.uploader)

Display name: Uploader

This integration connects Phrasea to an external uploader service that sends incoming commits to Phrasea. It is configuration-driven and exposes a target endpoint that the uploader service can call.

Main behavior:

• Defines uploader connection settings such as base URL, collection target, and a security key.
• Generates a secure default security key when not explicitly configured.
• Exposes a Target URL and authorization information for the uploader-side setup.
• Validates uploader API URL format before activation.

Operational notes:

• Requires a valid base URL for the uploader API.
• Uses an ApiKey authorization scheme.
• Security key must match on both Phrasea and uploader configurations.

Toast UI Photo Editor integration (tui.photo-editor)

Display name: Toast UI Photo Editor

This integration enables editing actions from the asset view using Toast UI Photo Editor. It handles save and delete user actions and tracks generated edited files as integration data.

Main behavior:

• Supports user actions: save and delete.
• On save, creates a new file version and stores a link in integration data.
• On delete, removes integration data for a previously saved edited output.
• Pushes real-time file updates after save and delete actions.

Operational notes:

• Scope is asset view context.
• Save and delete actions require valid user context and integration data identifiers.
• Unsupported actions are rejected.

Exhaustive integration list

The table below is the exhaustive integration list currently available in Databox codebase.

Integration key	Display name	Primary usage	External service
core.rendition	Rendition	Workflow rendition generation orchestration	No
phrasea.expose	Expose	Basket publication synchronization with Expose	No
core.read_metadata	Read Metadata	Asset source metadata extraction and normalization	No
phrasea.uploader	Uploader	External upload/webhook integration for Phrasea	No
tui.photo-editor	Toast UI Photo Editor	Asset view editing integration	No
core.moderation	Moderation	Workflow moderation step for assets	No
core.watermark	Watermark	Workflow watermark generation	No
blurhash	Blurhash	Workflow blurhash generation	No
aws.transcribe	AWS Transcribe	Workflow transcription with AWS integration	Yes
happyscribe	Happyscribe	Workflow transcription/subtitling with Happyscribe	Yes
aws.rekognition	AWS Rekognition	Asset view integration for visual analysis	Yes
aws.translate	AWS Translate	Workflow translation integration	Yes
core.webhook	Webhook	Outbound workflow webhook calls	No
remove.bg	Remove BG	Asset view background removal	Yes
phraseanet.renditions	Phraseanet Renditions	Workflow rendition synchronization with Phraseanet	No
core.test_asset_operation	Test Asset Operation	Test-only workflow integration	No

Note: for integrations marked Yes in the External service column, some assets, metadata, or derived content will necessarily be submitted to these external services for processing.

Summary

Databox integrations provide the technical layer that interconnects Phrasea with external systems while keeping internal flows consistent. In practice:

• core.rendition handles rendition generation orchestration.
• phrasea.expose handles basket publication synchronization with Expose.
• core.read_metadata handles source file's metadata extraction during ingest.
• phrasea.uploader handles external uploader commit ingestion setup.
• tui.photo-editor handles file editing save and delete actions.