[Enhancement]:creating a property for stakeholder object: status

[TracyHappy123]

Description of Enhancement :

Should create a property for a stakeholer object, which is "status", is used to describe the staus of this stakeholder. for example, active, inactive, terminated, for the purpose to provide a complete and clear idea of a specifi stakeholder.

Why is this Needed?

Anything else we need to know?

[Jake Yavis - Shareworks]

Hi @TracyHappy123, thank you for this suggestion. Apologies that this issue was not responded to sooner!

I too think it's important to be able to provide a complete a clear picture for a given stakeholder.

Closely related is our TerminationWindow schema.

Take this snippet from the sample for a grant issuance object (near the bottom of this page):

"termination_exercise_windows": [
      {
        "reason": "INVOLUNTARY_WITH_CAUSE",
        "period": 0,
        "period_type": "DAYS"
      },
      {
        "reason": "VOLUNTARY_GOOD_CAUSE",
        "period": 3,
        "period_type": "MONTHS"
      },
      {
        "reason": "INVOLUNTARY_OTHER",
        "period": 14,
        "period_type": "DAYS"
      },
      {
        "reason": "INVOLUNTARY_DEATH",
        "period": 3,
        "period_type": "YEARS"
      },
      {
        "reason": "INVOLUNTARY_DISABILITY",
        "period": 3,
        "period_type": "YEARS"
      },
      {
        "reason": "VOLUNTARY_RETIREMENT",
        "period": 1,
        "period_type": "MONTHS"
      },
      {
        "reason": "VOLUNTARY_OTHER",
        "period": 3,
        "period_type": "MONTHS"
      }
    ],

So at time of issuance, we are tracking what can happen (i.e. grant cancellation) given a status change, but at or after the actual status change, we have no way to track what is happening.

Take this e.g.:
Jane Doe has retired as of November 30th and only has until December 31st to exercise her options.

Sure, we would track the cancellation when an OCF archive is generated after December 31st. However, with the current schema, an OCF archive generated before November 30th (the status change date) compared to an OCF archive generated on December 1st, there would be no difference. No evidence at all of the termination.

I would propose the following, optional schema property be included on the Stakeholder object:

"status_events"; {[
    "date": "2024-11-30",
    "status": "TERMINATION_VOLUNTARY_RETIREMENT"
]}

Full list of proposed enum values for new enum StakeholderStatusType (seeking parity with TerminationWindowType)

    "TERMINATION_VOLUNTARY_OTHER",
    "TERMINATION_VOLUNTARY_GOOD_CAUSE",
    "TERMINATION_VOLUNTARY_RETIREMENT",
    "TERMINATION_INVOLUNTARY_OTHER",
    "TERMINATION_INVOLUNTARY_DEATH",
    "TERMINATION_INVOLUNTARY_DISABILITY",
    "TERMINATION_INVOLUNTARY_WITH_CAUSE",
    "LEAVE_OF_ABSENCE",
    "RETURN_TO_ACTIVE"

Note: LOA is common (a.k.a. "Inactive") but typically does not trigger an exercise termination / grant cancellation. I propose status_events to be an array so an LOA and RETURN_TO_ACTIVE can both be tracked for historic purposes.

Note: If the status events array is not provided or empty, then the stakeholder is assumed to be active

[Patrick Johnmeyer]

TWG Notes: Relates to #373, @jacobyavis to take another pass at a proposal to solving both at once.