# Matter List
Creates or updates items in the central matter list by processing rows from an Excel file or a single matter from a JSON file. Optionally creates or updates the associated client record, moves the matter item to a folder, and applies a permission set.
Filename pattern: filename must contain matterlist (case-insensitive).
Examples: 20240115 matterlist matters.xlsx, 20240115 matterlist.json
# Columns
| Name | Required | Description |
|---|---|---|
| MatterCode | Yes | Unique matter identifier. Used to look up or create the matter list item. |
| MatterID / ExternalID | No | External identifier for the matter, such as an ID from a case management system. |
| MatterName | No | Display name of the matter. Used to derive the list item title when Title is not provided. |
| Title | No | Explicit title for the matter list item. When provided, overrides the title derived from MatterName. When absent and MatterName is present, the title is calculated from the configured MatterListTitleFormat. |
| ClientID | No | Internal identifier for the client. |
| ClientCode | No | Unique client code. Required together with ClientName to create or update the client list entry. |
| ClientName | No | Display name of the client. Required together with ClientCode to create or update the client list entry. |
| SiteURL | No | URL of the matter's SharePoint site. Updates the value in the matter list even when the field already has a value. |
| URL | No | URL of the matter's default document library. |
| PermissionSet | No | Name of a permission set configuration to apply to the matter list item after creating or updating it. |
| Folder | No | Folder path within the matter list to move the item into after creating or updating it. |
| __Code__ | No | Renames the matter's Code field to this value after the row is matched to an existing item. Use this instead of MatterCode when the matter's code has changed and the row must still match the existing item by its current MatterCode or MatterID/ExternalID. |
| __ExternalID__ | No | Renames the matter's ExternalID field to this value after the row is matched. Same in-place rename behavior as __Code__, applied to the external ID instead. |
MatterCode is always required. Any additional columns are passed as metadata properties and written to the matter list item, except columns with a __ prefix (other than __Code__/__ExternalID__ above) — those are used only for the PermissionSet lookup below and are never written. See Match-only properties.
Note: Including a blank
SiteURLcell will clear any existing value. To leave the existing value untouched, omit theSiteURLcolumn entirely.
# Behavior
The client record is created or updated only when both ClientCode and ClientName are provided in the same row. If only one is given, the client step is skipped.
When Title is provided, it is used directly as the list item title. When Title is absent but MatterName is present, the title is formatted according to the MatterListTitleFormat setting in the service configuration.
When PermissionSet is provided, the named permission set configuration is resolved by dynamic name against the row's extra properties (see Dynamic name values) and applied to the matter list item.
When Folder is provided, the matter list item is moved into the specified folder within the matter list.
Renaming a code or external ID: __Code__ and __ExternalID__ are match-independent — the row is still matched using MatterCode or MatterID/ExternalID as usual, but after the existing item is found, its Code or ExternalID field is overwritten with the __Code__/__ExternalID__ value. This lets a single row rename a matter's code or external ID in place, without a separate step to change the value used for matching.
# Related links
- Site Collection handler — provision the matter site collection
- Permission Set handler — define permission set configurations
- Doclib Set handler — provision document libraries within a matter site