Modifying ClaimContact roles

The ClaimContact resource has two role-related array properties:

  • roles - A read-only array of all roles held by the ClaimContact
  • editableRoles - 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.