Modifying ClaimContact roles
The ClaimContact resource has two role-related array properties:
roles
- A read-only array of all roles held by the ClaimContacteditableRoles
- An editable array of non-reserved roles held by the ClaimContact
Both properties use the ContactRole
schema.
You can modify the roles a ClaimContact has, but this is never done by modifying the
roles
array. Instead, you either modify a field or array on a related
object, or you modify the editableRoles
array. Which approach to use is
determined by whether the role is reserved or not.
Setting reserved roles
A reserved role is a role that cannot be set on a ClaimContact explicitly. Instead, the role must be set by:
- Setting a field on another object
- Modifying an array on another object
- Executing an action on another object
The reserved roles are defined in the ReservedContactRoles.yaml file in
the integration/contactroles/v1
directory.
To assign a reserved role to a ClaimContact, you must identify the field, array, or action that implicitly sets the role.
Reserved roles that are set from a field
For example, the reporter role is set from the Claim's reporter
field. To add the reporter role to a ClaimContact, modify the Claim's
reporter
field so that it references the ClaimContact.
Suppose that there is a claim with ID cc:610 , and there is a ClaimContact with ID cc:1306. The following is an example of adding the reporter role to that ClaimContact:
PATCH http://localhost:8080/cc/rest/claim/v1/claims/cc:610
{
"data": {
"attributes": {
"reporter": {
"id": "cc:1306"
}
}
}
}
Reserved roles that are set from an array
As another example, the witness role is set from the Claim's
witnesses
array. To add the witness role to a ClaimContact, add
the ClaimContact the witnesses
array.
Suppose that there is a claim with ID cc:610 , and there is a ClaimContact with ID cc:1306. The claim has no witnesses. The following is an example of adding the witness role to ClaimContact cc:1306.
PATCH http://localhost:8080/cc/rest/claim/v1/claims/cc:610
{
"data": {
"attributes": {
"witnesses": [
{
"contact": {
"id": "cc:1306"
}
}
]
}
}
}
Keep in mind that, within the system APIs, PATCHing an array does not add new members to the existing members. It replaces the existing members with the new members. If you want to add members to an array, you must first determine the existing members, and then specify an array with those members and the ones you wish to add. For more information, see PATCHes.
Reserved roles that are set through actions
In some situations, a reserved role is set when an action is executed on a resource other than the ClaimContact itself. For example, when a service request is created, the ServiceRequestInstruction can specify a ClaimContact as the CustomerContact. This ClaimContact is given the reserved role servicerequestparticipant.
Setting non-reserved roles
A non-reserved role is a role that can be set on a ClaimContact explicitly. Every role that is not listed in the ReservedContactRoles.yaml file is a non-reserved role.
To assign a non-reserved role to a ClaimContact, you must modify the ClaimContact's
editableRoles
array.
JSON syntax for the editableRoles array
When POSTing or PATCHing a ClaimContact, every member of the editableRoles
array must include three pieces of information:
- The role's code
- The type of object on which the ClaimContact has this role
- The ID of the object on which the ClaimContact has this role
The syntax used to specify this is:
"editableroles": [
{
"role": {
"code": "<roleCode>"
},
"relatedTo": {
"type": "<parentObjectType>",
"id": "<parentObjectId>"
}
},
... <additionalRoles>
For example, the following PATCHes Claim cc:610 so that ClaimContact cc:777 has the
alternate contact role (whose code is altcontact
) on the claim
itself.
PATCH http://localhost:8080/cc/rest/claim/v1/claims/cc:610/contacts/cc:777
{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "altcontact"
},
"relatedTo": {
"type": "Claim",
"id": "cc:610"
}
}
]
}
}
}
Similarly, this example shows how to PATCH Claim cc:610 so that ClaimContact cc:208 has the
owner role (whose code is incidentowner
) on the vehicle incident
whose ID is cc:102. (In other words, ClaimContact cc:208 is the owner of the vehicle
specified in vehicle incident cc:102.)
PATCH http://localhost:8080/cc/rest/claim/v1/claims/cc:610/contacts/cc:208
{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "incidentowner"
},
"relatedTo": {
"type": "vehicleIncident",
"id": "cc:102"
}
}
]
}
}
}
PATCHing editableRoles
scenarios
Keep in mind that, within the system APIs, PATCHing an array does not add new members to the existing members. It replaces the existing members with the new members. If you want to add members to an array, you must first determine the existing members, and then specify an array with those members and the ones you wish to add. For more information, see PATCHes.
When PATCHing editableRoles
, the following table details the possible
request payloads and they way the system APIs will respond.
If the request payload contains... | ...then... |
---|---|
No editableRoles array |
The non-reserved roles on the ClaimContact remain unchanged. |
An editableRoles array with one or more non-reserved
roles |
The existing non-resolved roles are replaced by the non-reserved roles specified in the payload. |
An empty editableRoles array |
All existing non-reserved roles are removed. (However, if this would result in the ClaimContact no longer having any roles, the system API returns an error.) |
An editableRoles array with one or more reserved roles |
The system API returns an error. |
A roles array |
The system API returns an error. |