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.

Every member of these arrays includes the following properties:

  • relatedTo - the type and ID of the object that the ClaimContact is related to
  • role - the role the ClaimContact has on that object
  • active - a Boolean identifying whether the ClaimContact actively holds the role on the claim.

The active field is used to identify ClaimContacts who previously held a role on the claim but are no longer actively involved in the claim. For example, suppose an injured person is treated by one doctor, but then the case is reassigned to a second doctor. Both doctors could be ClaimContacts on the claim, but active would be set to true only for the second doctor.

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.

Reserved roles

A reserved role is a role that cannot be set on a ClaimContact explicitly. Instead, the role must be set implicitly through a field, array, or action on another object.

For example, reporter is a reserved role. You cannot add this role directly to a ClaimContact. However, you can set a Claim's reporter field to a given ClaimContact. This implicitly adds the reporter role to that ClaimContact. This also removes the reporter role from any other ClaimContact that previous had it.

The reserved roles are defined in the ReservedContactRoles.yaml file in the integration/contactroles/v1 directory. In general, the reserved roles are either:

  • Roles for which there can be at most one ClaimContact with the role. (For example, reporter. A claim can have at most one reporter.)
  • Roles that are set through an array on a non-ClaimContact object. (For example, witness. Witnesses are defined on the Claim resource's witnesses array.)

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. For example, alternate contact is a non-reserved role. A claim can have any number of alternate contacts, and this type of ClaimContact is not managed by an array on Claim.

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>
Java

For example, the following request PATCHes Claim cc:610 so that ClaimContact cc:777 has the alternate contact role (whose code is altcontact) on the claim itself.

Command

PATCH http://localhost:8080/cc/rest/claim/v1/claims/cc:610/contacts/cc:777
Java

Request body

{
  "data": {
    "attributes": {
      "editableRoles": [
        {
          "role": {
            "code": "altcontact"
          },
          "relatedTo": {
            "type": "Claim",
            "id": "cc:610"
          }
        }
      ]
    }
  }
}
Java

Similarly, the following request PATCHes 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 specified as the owner of the vehicle from vehicle incident cc:102.)

Command

PATCH http://localhost:8080/cc/rest/claim/v1/claims/cc:610/contacts/cc:208
Java

Request body

{
  "data": {
    "attributes": {
      "editableRoles": [
        {
          "role": {
            "code": "incidentowner"
          },
          "relatedTo": {
            "type": "vehicleIncident",
            "id": "cc:102"
          }
        }
      ]
    }
  }
}
Java