Working with Participant Data Fields

Introduction

You can attach data fields to a Participant in a similar way to how you attach data fields to a Matter. This step-by-step tutorial using Postman will show how to create, update, and delete data fields for a Participant.

Understanding How Participant Data Fields Work in Actionstep

In Actionstep a Contact record can be assigned one or more contact types. A contact type is a designation that indicates a potential role the Contact may assume when associated with a particular Matter. For example, a Contact may be designated a Client, a Defendant, a Plaintiff, a Witness, a Lawyer, etc. As such an individual Contact can assume a different role on different Matters.

When a Contact is associated with a Matter they are referred to as a Participant to the Matter, and their contact types are referred to as participant types. Participant data fields in Actionstep are associated with participant types, and the data stored in these fields is scoped to the role of the Contact in the Matter. Only data fields associated with the participant type of the Participant on the Matter are made available for data entry. Editing data fields for a Participant will only affect information held against them on a per-Matter basis, i.e. the same set of data fields could hold different values for the same Participant on different Matters.

When data fields are created for a participant type they become available for data entry on the Participant record. Actual data field values are persisted to a separate table from the data field definition. Only when a data field is populated with data is an entry created in the the Participant Data Field Values table.

NB: This also applies when a data field has been assigned a default value. The default value is not persisted until a different value is entered into the field.

Creating a Participant Data Field

To create a new participant data field you make a POST request to the participanttypedatafields endpoint. This has the effect of making the data field available for data entry on the Participant record for the specified participant type.

Setting a Participant Data Field Value

As noted above, an entry in the Participant Data Field Values table is only created when a value is set for a data field. Once a data field value has been persisted you can use a PUT request to subsequently update its value. If we were to attempt setting a value for a data field that does not yet exist, the API will respond with a 404 error.

If the same request is now changed to a POST request, the data field value table entry will be created and populated.

The two options here are to either make a PUT request such that if it responds with a 404 you follow up with a POST request, or, use a GET request to check if the data field value exists before deciding whether to use a PUT or POST request. A PUT request is not automatically switched to a POST request if the resource cannot be found.

To perform any subsequent updates use a PUT request.

Note how the unique identifier for a data field value is a composite key made up of the participant Id, the participant type Id, and the participant type data field Id.

Removing a Participant Data Field Value

To remove a value from a specific data field clear, its contents using a PUT request to the participantdatafieldvalues endpoint specifying a stringValue property value of null.

Deleting a Participant Data Field

To delete a data field, make a DEL request to the participanttypedatafields endpoint, specifying the participant type data field Id in the URL.

WARNING: Deleting a data field will also delete all data field values across all Matters that contain participants of the type associated with the data field.