# CaseControl plugin

Integrates CaseControl (opens new window) (by Finchamps) with the Epona provisioning service. The plugin periodically syncs matters from CaseControl to SharePoint and, when a matter is first created in SharePoint, imports the associated documents, emails, and correspondence from CaseControl into the matter document library.

DLL: Epona.CaseControl.dll

# What it does

Matter sync — reads matters from the CaseControl REST API and creates or updates corresponding records in SharePoint on a configurable schedule.
Field mapping — maps CaseControl matter fields to SharePoint properties using configurable expressions and key-value mapping syntax.
Locale translation — resolves locale-based IDs (case status, case type, communication channel) to their translated text values automatically.
Responsible employee — looks up the email address of the responsible case owner from the CaseControl employee/user directory.
Post handler — when a matter is first created in SharePoint, fetches and uploads the case's documents, inbox emails, and correspondence items (letters, emails, plain text) to the matter document library.

# Deployment

Copy Epona.CaseControl.dll to the service's bin directory.
Restart the provisioning service.
Open the Configurator, select the relevant SharepointCfg, and configure the CaseControl section that now appears in the property grid.
Configure the OAuth credentials — see Connection settings below.

# Required API scopes

The CaseControl OAuth client must be granted the following scopes:

cases.read
cases.correspondence.read
cases.documents.read
cases.logs.read
global.files.read
global.employees.read
global.users.read
global.locales.read
cases.inbox.read
relations.read
relation-entities.read
relation-entities.addresses.read
cases.relations.read

Contact Finchamps to provision an API client with these scopes. See the CaseControl API documentation (opens new window) for details.

# Configuration reference

# Connection settings

Property	Configurator label	Type	Default	Description
`Url`	Url	`string`	—	Base URL of the CaseControl API (e.g. `https://api.casecontrol.nl/`). HTTP URLs are automatically upgraded to HTTPS.
`AdministrationId`	AdministrationId	`string`	—	The administration ID used as the path prefix for all API calls (`/api/v1/administrations/{id}/`).
`ClientId`	ClientId	`string`	—	OAuth client ID. Stored encrypted. Manage via the Secrets manager in the Configurator.
`ClientSecret`	ClientSecret	`string`	—	OAuth client secret. Stored encrypted. Manage via the Secrets manager in the Configurator.

# Scheduling

Property	Configurator label	Type	Default	Description
`IntervalScheduleCfg`	CaseControl Schedule	`IntervalScheduleCfg`	—	Interval-based schedule controlling when the sync job runs. Expand in the Configurator to set the interval, start/end time window, and enabled state.

The plugin does not run if Url or AdministrationId is empty, or if the schedule is disabled.

# Client mapping

Property	Configurator label	Type	Default	Description
`EndpointClientId`	Client Id	`string`	—	Expression or field path used to populate the SharePoint client ID. Supports dynamic name variables (e.g. `{client_id}`).
`ClientName`	Client Name	`string`	—	Expression or field path used to populate the SharePoint client name.
`ClientFieldMapping`	Client Field Mapping	`string`	—	Maps CaseControl JSON fields to SharePoint client fields. Syntax: `sharepointField=caseControlField;sharepointField2=caseControlField2`. Supports pipe `\\|` for fallback fields.

# Matter mapping

Property	Configurator label	Type	Default	Description
`MatterId`	Matter Id	`string`	—	Expression or field path used to populate the SharePoint matter ID.
`MatterCode`	Matter Code	`string`	—	Expression or field path used to populate the SharePoint matter code.
`MatterName`	Matter Name	`string`	—	Expression or field path used to populate the SharePoint matter name.
`MatterStageSharepointColumnName`	Matter Stage SharePoint Column Name	`string`	—	Name of the SharePoint column that receives the matter's status (translated from the CaseControl locale). Leave empty to skip.
`MatterTypeSharepointColumnName`	Matter Type SharePoint Column Name	`string`	—	Name of the SharePoint column that receives the matter type (translated from the CaseControl locale). Leave empty to skip.
`ResponsibleEmailSharepointColumnName`	Responsible Email SharePoint Column Name	`string`	—	Name of the SharePoint column that receives the email address of the responsible case owner. Leave empty to skip.
`MatterFieldMapping`	Matter Field Mapping	`string`	—	Maps CaseControl JSON fields to SharePoint matter fields. Same syntax as `ClientFieldMapping`.

# Filter

Property	Configurator label	Type	Default	Description
`MatterFilter`	MatterFilter	`string`	—	Optional filter to limit which matters are processed. Syntax: `<CaseControlApiField>=<value>;`. Multiple filters are separated by semicolons.

# Post handler

The post handler runs automatically after a matter is first created in SharePoint. It fetches the case's documents, inbox emails, and correspondence from CaseControl and uploads them to the matter's document library.

Property	Configurator label	Type	Default	Description
`Enabled`	Enabled	`boolean`	`false`	Set to `true` to enable the post handler. When disabled, no files are imported on matter creation.
`DocumentTargetFolder`	Document SharePoint Target Folder	`string`	—	Relative path within the matter document library where case documents and text/letter correspondence are uploaded (e.g. `Documents`). Required when post handler is enabled.
`EmailTargetFolder`	Email SharePoint Target Folder	`string`	—	Relative path within the matter document library where email messages (`.msg`) are uploaded (e.g. `Emails`). Required when post handler is enabled.

What is imported by the post handler:

Source	Format	Target folder
Case documents	Original file	`DocumentTargetFolder`
Inbox emails	`.msg`	`EmailTargetFolder`
Correspondence — email channel	`.msg`	`EmailTargetFolder`
Correspondence — letter channel	`.docx` (HTML body converted)	`DocumentTargetFolder`
Correspondence — other channels	`.txt` (plain text body)	`DocumentTargetFolder`

Files are not re-uploaded if a file with the same name already exists in the target folder.

# Debug / test

Property	Configurator label	Type	Default	Description
`TestMapping`	TestMapping	`boolean`	`false`	When enabled, moves exported JSON to a `Test` subdirectory and skips updating the last-run timestamp. Use to validate field mappings without modifying sync state.

# Example configuration

Property	Example value
`Name`	`CaseControl`
`Url`	`https://api.casecontrol.nl/`
`AdministrationId`	`12345`
`IntervalScheduleCfg.Enabled`	`true`
`IntervalScheduleCfg.IntervalInMinutes`	`60`
`MatterCode`	`{number}`
`MatterName`	`{description}`
`MatterStageSharepointColumnName`	`MatterStage`
`MatterTypeSharepointColumnName`	`MatterType`
`ResponsibleEmailSharepointColumnName`	`ResponsibleEmail`
`MatterFieldMapping`	`OpenDate=opened_at;CloseDate=closed_at`
`MatterFilter`	`case_type=law;`
`Enabled`	`true`
`DocumentTargetFolder`	`Documents`
`EmailTargetFolder`	`Emails`

Configuration reference — provisioning configuration reference
Plugins index — list of available plugins