Incident Grouping
- Kyle McGrogan
- Ben Rosenbach
Incident Grouping was a feature introduced in March 2023. This is how it works.
Makeup of an incident
When an incident is generated, there are a few pieces of data that are associated with it:
What triggered it
This is the text of the incident
This may also include additional information like the event that logic failed to run on, or the text message that generated the incident
The status of the incident
Will generally be “Status set to New”, but some auto-resolving incidents will have “Status set to Resolved”
Additional references to relevant information
This can be something like what transactions prevented a participant from finishing, what block stopped another one from scheduling due to overlapping, or the variable that failed to calculate
Grouping settings
Each Incident Type in a build has 3 settings for grouping:
Do not group
This is the default for all incident types
It’s pretty straightforward. All incidents with this set will never group
Group open incidents
When this is selected, whenever a new incident of this type is generated it will group itself into the most recent existing open incident of its type for that participant
Group open incidents with matching details
When this is selected, it will function just like “Group open incidents”, but it will also require that the existing open incident have the same text as the new one.
These are a number of system-generated software incidents that don’t require the same text, but have “details” based on something in the system, like twilio error code. These are listed below in X
It should also be noted that any incident that is created manually will never group into or be be grouped onto any groups. This includes incidents generated by modifying a form submission, scheduling an unscheduled event block, the “Create Incident” form in the user admin, and any other place where you’re inputting Incident text at the time you’re making an action.
What grouping is doing
When a new incident is generated, it checks to see if there is an existing incident it should be grouped into. If it finds one, it moves all of its information over to the existing one except for its status. This means it will provide the existing incident with new information about what triggered it, and what additional references it should have. (1 and 3 from “Makeup of an incident”)
Matching Details
For the most part, “matching” details means that the new incident has the same text as the existing incident. This is a little different for some of our Software/Message Failure incidents, where we wanted things to group but the text wasn’t guaranteed to match. The text may match, but we won’t ever check the text in these cases, we will always use the specified details. Below is a table of where we set specific details:
Cause of incident | Incident type | Incident text | Details |
|---|---|---|---|
When new data attaches to a user event that has already been completed with data attached | Equipment | Closed event [event name] updated: Updated value received from data source for participant [participant id]- updating value from [old value] to [new value], on [date] | late_data_[source id] |
When new data attaches to a user event that was skipped due to lack of data | Equipment | Closed event [event name] updated: [source name] data received from participant [participant id] was linked to [event name] - [event start date]. | late_data_[source id] |
When trying to finish a participant via event logic, but they can’t be finished because they have pending transactions | Software | This patient could not be finished because there is [# transactions] unprocessed/unapproved transaction(s) | finish |
When trying to finish a participant via event logic, but they can’t be finished because they have payments that errored or are pending | Software | This patient could not be finished because there is [# payments] error/pending payment(s) | finish |
When an exception is thrown while attempting to execute the SendEpicInbasketMessageJob | Software | Sending Epic Inbasket Message failed. Error was: [error details] | epic_inbasket |
When validating demographics against Epic the values in w2h don’t match the Epic Record | Software | Demographics do not match between WTH and Epic for participant [participant id]. See the comments for details on the mismatch | epic_demographics |
When validating a patients demographic data with Epic, we did not get any demographic data from the EpicService | Software | Couldn't get demographics from Epic to validate this patient's demographics | epic_demographics |
When validating a patients demographic data with Epic, the EpicService returned an error | Software | This patient was not found in Epic, or another error took place during demographics validation.
The specific error from Epic was: [error] | epic_demographics |
When an error occurs while attempting to set a smart data element via the EpicService | Software | Could not write status update to Epic Smart Data Element. Error was: %s | epic_sde |
When attempting to send FormSubmission data to Epic via Flowsheet mappings; some of the mappings require approval | Software | EPIC FAIL: A form submission with a status of Not Sent has flowsheet mappings that required approval. | epic_flowsheet_[form submission id] |
When attempting to send FormSubmission data to Epic via Flowsheet mappings; none of the data was sent to successfully | Software | EPIC FAIL: A row of data failed to submit to the Epic flowsheet. | epic_flowsheet_[form submission id] |
When attempting to send FormSubmission data to Epic via Flowsheet mappings; only some of the data was sent to successfully | Software | EPIC FAIL: Some fields failed to file to the Epic flowsheet. | epic_flowsheet_[form submission id] |
When a lottery event runs but the participant doesn’t have a lottery number | Software | Participant [participant id] had a scheduled lottery event ([event name] [event id] - [event date]) but has not selected or been assigned a lottery number. | lottery_[event_id] |
When a lottery runs logic but finds transactions already related to it. Presumably to prevent re-running logic from creating multiple transactions | Software | Event logic applied on a lottery event ([event name] [event id] - [event date]) with existing transactions. New transactions were not created for participant [participant id]. | lottery_[event_id] |
When trying to send a message as part of a conversation but it contains a variable that can’t be calculated | Software | Unable to send a message in [convo name] conversation for participant [participant id] because we are unable to calculate a variable. | replacement_failure_[convo id] |
When sending a text message it failed to get delivered either on the initial send or when requesting an update from twilio. | Message Failure | Text failed to get delivered to [participant id] because of [twilio error message]. You can use this link to go to the participant's notifications tab to see the message that did not get delivered: [inbox link]. | message_failure_[twilio error code] |
When attempting to register a participant with Clincard we receive an error | Software | Clincard errored when registering or updating this participant as a cardholder. Details: [details] | clincard_register |
When updating a payment status that was sent to clincard, if clincard returned an error we create this incident. | Software | A payment approved for participant [participant id] failed to send to Greenphire Clincard. Confirm that the participant is in the Clincard portal and has a card assigned. Confirm that their Clincard number matches what is listed in their W2H record. You can attempt to reissue payment by clicking on payment details, then details, then log error. Then go to the transactions page to re-approve the transactions associated with the payment. | clincard_payment |
When attempting to refresh a participants' Fitbit access token. We routinely do this before pulling data. | Equipment | Had trouble collecting Fitbit information for [participant name] on [date]. We will try again on the next hourly data pull, but if this persists the user will have to visit WTH and reauthorize us to get Fitbit data. | fitbit_auth |
When there is an unrecoverable error in event logic that gets thrown, this incident is generated after the transaction rollback | Software | An error occurred when running event logic. Please review the event set up and put in a Help Desk ticket if you need further assistance. Event: [event name] Error details: [error message] Event date: [event date] | event_exception_[event_id] |
When the text replacer fails to generate the pre-event message for a Send Message event | Software | An error occurred when sending event message. Please review the event set up and put in a Help Desk ticket if you need further assistance. Event: [event name] Error details: [error message] Event date: [event date] | event_exception_[event_id] |
When the text replacer fails to generate the response message for a trigger | Software | An error occurred when trying to generate an automatic messaging response for [participant id]. Error Details: [details] | response_[trigger_id] |
When we encounter an error building the survey definition for an enrollment step because of a variable error
Note: I’m not entirely sure if this actually happens. There’s a comment in the code saying we suppress this error here | Software | Unable to generate the '[survey name]' survey for participant [participant id] because we are unable to calculate a variable. Error details: [details] | survey_error_[enrollment step id] |
Links
For a more thorough accounting of where we are creating incidents, what their triggers/attachments are, and how they’re grouped, you can see the page where we did our audit and marked things for update: https://waytohealth.atlassian.net/wiki/spaces/technical/pages/2466512950