Configuring document storage (Local, Azure, S3)

Document storage settings decide where MobilityManager writes uploaded files. There is one active configuration, and it applies globally. You can point storage at a local disk path, Azure Blob Storage, or an S3-compatible bucket. This article explains each provider and how to switch between them safely.

Required permission

Reading and updating document storage settings requires settings:manage. Configure them at /admin/document-management.

The three providers

Local

• Base path (required) — the directory where documents are stored. The value is validated and normalized before it is saved.
• Encryption key — an optional base64-encoded 32-byte AES key held in the database. When encryption at rest is enabled, an encryption key reference is required and must resolve from configuration.

Azure Blob

• Container name (required).
• Connection string reference (required) — a secret reference, not the raw connection string.
• Blob service URI (optional).

S3

• Bucket name (required).
• Region (required).
• Access key reference and secret key reference (both required) — secret references.
• Service URL (optional) — set this for S3-compatible endpoints.

Note: Cloud credentials are stored as secret references that the platform resolves from its secure configuration. The raw credentials and the local encryption key are never returned by the settings API — a read only reports whether a local key is set, so the UI can offer key rotation without exposing the value.

Switch providers

1. Open /admin/document-management.
2. Choose the provider: Local, Azure Blob, or S3.
3. Fill in that provider's required fields.
4. Save. The platform validates the input, activates the new provider, and clears the fields that belong to the other providers.

Only supported provider values are accepted; anything else is rejected with an "Unsupported providerType" message. Missing required fields return a clear validation error naming the field.

Local encryption key handling

If you save a Local configuration without supplying a new encryption key, the existing key is preserved. Supplying a new value must be a valid base64-encoded 32-byte AES key, or the save is rejected.

Warning: Changing the local encryption key makes documents encrypted under the previous key permanently undecryptable — there is no re-encryption or keyring. Only rotate the key when you understand this, and the platform preserves the current key on any save that omits it precisely to prevent accidental loss.

Tip: Switching providers changes where new documents are written. Existing documents remain in the previous location. Plan a migration if you need historical files under the new provider.

Verify after saving

1. Reopen the settings to confirm the active provider and its fields.
2. Upload a test document and confirm it is stored and retrievable.
3. For Local with encryption enabled, confirm the key reference resolves.

Related

• System configuration overview and access
• Validating configuration before publishing
• Localization and workflow-state label translations