Inviting an Actor to a Case

This page is not normative

This page is not considered a core part of the Vultron Protocol as proposed in the main documentation. Although within the page we might provide guidance in terms of SHOULD, MUST, etc., the content here is not normative.

Inviting an actor to a case is a way to add them as a participant in the case. The invitation is sent to the actor as an as:Invite activity. Depending on the actor's response, they may become a participant in the case.

---
title: Invite Actor to Case
---
sequenceDiagram
    actor O as Case Owner
    actor A as Actor
    participant C as Case
    activate O
    O ->>+ A: Invite(object=Case)
    note over A: Consider invitation
    alt Accept Invitation
        A -->> O: Accept(object=Case, inReplyTo=Invite)
        alt Create CaseParticipant
        O ->> C: Create(object=CaseParticipant(actor=Actor), target=Case)
        else Add CaseParticipant
        O ->> O: Create(object=CaseParticipant(actor=Actor))
        O ->> C: Add(object=CaseParticipant(actor=Actor), target=Case)
        end
        note over C: Actor becomes participant in case
    else Reject Invitation
        A -->> O: Reject(object=Case, inReplyTo=Invite)
        note over C: Actor is not participant in case
    end
    deactivate A
    deactivate O

Invite vs Add?

When a case is first created, the Case Owner and any known participants (e.g., the Reporter) should be automatically added to the case. It's not even necessary for these to be emitted as separate as:Add activities. The as:Create activity for the case can include the Case Owner and any known participants as CaseParticipant objects. See Initializing a Case for more.

However, over the lifespan of a case, there may be other actors that were not already involved at the time the case was created, but who should be invited to participate in the case. This is where the as:Invite activity comes in.

Avoid bogging down in details

Adding a participant to a case involves creating the participant object and a participant status object. As we discuss elsewhere, it's probably overkill to emit separate as:Create and as:Add events for each of these events.

flowchart LR

a[create participant] --> b[create participant status]
b --> c[add participant status to participant]
c --> d[add participant to case]

Instead, we could emit a single as:Create event for the participant, already containing a status object, and have the target of the as:Create event be the case object.

flowchart LR
a[create particpant with status] -->|target| b[case]

Invite to Case

A vendor invites a coordinator to a case.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "asType": "Invite",
  "id": "https://vultron.example/cases/VDR-20991514/invitation/1",
  "name": "https://vultron.example/organizations/vendor Invite https://vultron.example/organizations/coordinator to https://vultron.example/cases/VDR-20991514",
  "content": "We're inviting you to participate in VENDOR Case #20991514.",
  "to": "https://vultron.example/organizations/coordinator",
  "actor": "https://vultron.example/organizations/vendor",
  "target": "https://vultron.example/cases/VDR-20991514",
  "object": "https://vultron.example/organizations/coordinator"
}

Accept Invite to Case

A coordinator accepts a vendor's invitation to a case.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "asType": "Accept",
  "id": "https://for.example/c4f0e633-1f8f-4ad8-91fc-7e9ffa8b80c1",
  "name": "https://vultron.example/organizations/coordinator Accept https://vultron.example/cases/VDR-20991514",
  "inReplyTo": "https://vultron.example/cases/VDR-20991514/invitation/1",
  "content": "We're accepting your invitation to participate in VENDOR Case #20991514.",
  "to": "https://vultron.example/organizations/vendor",
  "actor": "https://vultron.example/organizations/coordinator",
  "object": "https://vultron.example/cases/VDR-20991514"
}

Reject Invite to Case

A coordinator rejects a vendor's invitation to a case.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "asType": "Reject",
  "id": "https://for.example/11380eec-20e1-4cef-9852-676f952ebc31",
  "name": "https://vultron.example/organizations/coordinator Reject https://vultron.example/cases/VDR-20991514",
  "inReplyTo": "https://vultron.example/cases/VDR-20991514/invitation/1",
  "content": "Thanks for the invitation, but we're declining to participate in VENDOR Case #20991514.",
  "to": "https://vultron.example/organizations/vendor",
  "actor": "https://vultron.example/organizations/coordinator",
  "object": "https://vultron.example/cases/VDR-20991514"
}

Add Participant to Case

The vendor adds a coordinator participant to the case.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "asType": "Add",
  "id": "https://for.example/db05c73f-b632-4bb3-b9fe-e19198f83d2b",
  "name": "https://vultron.example/organizations/vendor Add Coordinator LLC to https://vultron.example/cases/VDR-20991514",
  "content": "We're adding the coordinator as a participant to this case.",
  "actor": "https://vultron.example/organizations/vendor",
  "target": "https://vultron.example/cases/VDR-20991514",
  "object": {
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "CaseParticipant",
    "id": "https://vultron.example/cases/VDR-20991514/participants/coordinator",
    "name": "Coordinator LLC",
    "context": "https://vultron.example/cases/VDR-20991514",
    "published": "2024-07-09T20:17:18+00:00",
    "updated": "2024-07-09T20:17:18+00:00",
    "actor": "https://vultron.example/organizations/coordinator",
    "caseRoles": [
      "COORDINATOR"
    ],
    "participantStatus": [
      {
        "@context": "https://www.w3.org/ns/activitystreams",
        "type": "ParticipantStatus",
        "id": "https://for.example/9e82e7e2-38ba-4178-8bd7-1ec25e86f817",
        "name": "REPORT_MANAGEMENT_START vfd",
        "context": "https://vultron.example/cases/VDR-20991514",
        "published": "2024-07-09T20:17:18+00:00",
        "updated": "2024-07-09T20:17:18+00:00",
        "actor": "https://vultron.example/organizations/coordinator",
        "rmState": "REPORT_MANAGEMENT_START",
        "vfdState": "vfd",
        "caseEngagement": true,
        "embargoAdherence": true
      }
    ]
  }
}