Updated Feature: Activity-based Incident Cost Model

docs/docs/user-guide/cost_model.mdx

@@ -0,0 +1,105 @@
+# Cost Model
+
+Our Cost Model is a feature that enables teams to estimate response cost for each incident. Users can opt in to create and use personalized cost calculations for each incident based on participant activity.
+
+If no cost model is assigned to an incident, the default classic cost model will be used. See [Incident Cost Type](../administration/settings/incident/incident-cost-type.mdx###calculating-incident-cost).
+
+<div style={{textAlign: 'center'}}>
+
+![](/img/admin-ui-cost-model.png)
+
+</div>
+
+## Key Features
+
+### Customizable Cost Models
+Users have the flexibility to define their unique cost models based on their organization's workflow and tools. This customization can be tailored to each incident, providing a versitile approach to cost calculation. The cost model for an incident can be changed at any time during its lifespan. All participant activity costs moving forward will be calculated using the new cost model.
+
+### Plugin-Based Tracking
+Users can track costs from their existing tools by using our plugin-based tracking system. Users have the flexibility to select which plugins and specific plugin events they want to track, offering a targeted approach to cost calculation.
+
+### Effort Assignment
+For each tracked activity, users can assign a quantifiable measure of effort, represented in seconds of work time. This feature provides a more accurate representation of the cost of an incident.
+
+### Incident Cost Calculation
+Incident cost calculation is based on the cost model and effort assignment for each tracked participant activity. This helps in understanding resource utilization and cost of an incident.
+
+
+## Currently Supported Plugin Events
+
+### Slack: Channel Activity
+This event tracks activity within a specific Slack channel. By periodically polling channel messages, this gathers insights into the activity and engagement levels of each participant.
+
+### Slack: Thread Activity
+This event tracks activity within a specific Slack thread. By periodically polling thread replies, this gathers insights into the activity and engagement levels of each participant.
+
+
+<div style={{textAlign: 'center'}}>
+
+![](/img/admin-ui-edit-cost-model.png)
+
+</div>
+
+## Cost Calculation Examples
+
+Below, we illustrate the use of the cost model through two examples. These are based on the following values:
+
+<b>Cost Model 1</b>
+
+| Plugin Event | Response Time (seconds)
+|  ------------ | -------------
+| Slack Channel Activity | 300
+
+The employee hourly rate can be adjusted by modifying the `Annual Employee Cost` and `Business Year Hours` fields in the [project settings](../administration/settings/project.mdx). In these examples, we will use the following value:
+```
+hourly_rate = 100
+```
+
+#### Example 1
+
+Consider the following Slack channel activity for `Incident 1`:
+
+| Slack Channel Activity Timestamp | Participant
+|  ------------ | -------------
+| 100 | Cookie Doe
+| 200 | Nate Flex
+
+The resulting recorded participant activity will be:
+
+| Participant | started_at | ended_at | Plugin Event | Incident
+|  ------------ | ------------- | ------------- |  ------------- | -------------
+| Cookie Doe | 100 | 400 | Slack Channel Activity | Incident 1
+| Nate Flex | 200 | 500 | Slack Channel Activity | Incident 1
+
+
+The incident cost is then calculated as:
+
+```
+( (400 - 100) + (500-200) ) / SECONDS_IN_HOUR * hourly_rate = $16.67
+```
+
+#### Example 2
+
+Consider the following Slack channel activity for `Incident 2`:
+
+| Slack Channel Activity Timestamp | Participant
+|  ------------ | -------------
+| 100 | Cookie Doe
+| 150 | Cookie Doe
+| 200 | Nate Flex
+| 500 | Cookie Doe
+
+The resulting recorded participant activity will be:
+
+| Participant | started_at | ended_at | Plugin Event | Incident
+|  ------------ | ------------- | ------------- |  ------------- | -------------
+| Cookie Doe | 100 | 450 | Slack Channel Activity | Incident 2
+| Nate Flex | 200 | 500 | Slack Channel Activity | Incident 2
+| Cookie Doe | 500 | 800 | Slack Channel Activity | Incident 2
+
+
+The incident cost is then calculated as:
+
+```
+( (450 - 100) + (500 - 200) + (800 - 500) ) / SECONDS_IN_HOUR * hourly_rate = $26.39
+```

src/dispatch/__init__.py

@@ -20,6 +20,10 @@
     from dispatch.route.models import Recommendation  # noqa lgtm[py/unused-import]
     from dispatch.conference.models import Conference  # noqa lgtm[py/unused-import]
     from dispatch.conversation.models import Conversation  # noqa lgtm[py/unused-import]
+    from dispatch.cost_model.models import (
+        CostModel,  # noqa lgtm[py/unused-import]
+        CostModelActivity,  # noqa lgtm[py/unused-import]
+    )
     from dispatch.definition.models import Definition  # noqa lgtm[py/unused-import]
     from dispatch.document.models import Document  # noqa lgtm[py/unused-import]
     from dispatch.event.models import Event  # noqa lgtm[py/unused-import]
@@ -37,8 +41,11 @@
     from dispatch.individual.models import IndividualContact  # noqa lgtm[py/unused-import]
     from dispatch.notification.models import Notification  # noqa lgtm[py/unused-import]
     from dispatch.participant.models import Participant  # noqa lgtm[py/unused-import]
+    from dispatch.participant_activity.models import (
+        ParticipantActivity,  # noqa lgtm[py/unused-import]
+    )
     from dispatch.participant_role.models import ParticipantRole  # noqa lgtm[py/unused-import]
-    from dispatch.plugin.models import Plugin  # noqa lgtm[py/unused-import]
+    from dispatch.plugin.models import Plugin, PluginEvent  # noqa lgtm[py/unused-import]
     from dispatch.report.models import Report  # noqa lgtm[py/unused-import]
     from dispatch.service.models import Service  # noqa lgtm[py/unused-import]
     from dispatch.storage.models import Storage  # noqa lgtm[py/unused-import]
@@ -61,7 +68,9 @@
     from dispatch.case.severity.models import CaseSeverity  # noqa lgtm[py/unused-import]
     from dispatch.case.type.models import CaseType  # noqa lgtm[py/unused-import]
     from dispatch.signal.models import Signal  # noqa lgtm[py/unused-import]
-    from dispatch.feedback.service.reminder.models import ServiceFeedbackReminder  # noqa lgtm[py/unused-import]
+    from dispatch.feedback.service.reminder.models import (
+        ServiceFeedbackReminder,  # noqa lgtm[py/unused-import]
+    )
     from dispatch.forms.type.models import FormsType  # noqa lgtm[py/unused-import]
     from dispatch.forms.models import Forms  # noqa lgtm[py/unused-import]
 

src/dispatch/api.py

@@ -30,6 +30,7 @@
 from dispatch.incident.type.views import router as incident_type_router
 from dispatch.incident.views import router as incident_router
 from dispatch.incident_cost.views import router as incident_cost_router
+from dispatch.cost_model.views import router as cost_model_router
 from dispatch.incident_cost_type.views import router as incident_cost_type_router
 from dispatch.incident_role.views import router as incident_role_router
 from dispatch.individual.views import router as individual_contact_router
@@ -197,6 +198,11 @@ def get_organization_path(organization: OrganizationSlug):
     prefix="/case_severities",
     tags=["case_severities"],
 )
+authenticated_organization_api_router.include_router(
+    cost_model_router,
+    prefix="/cost_models",
+    tags=["cost_models"],
+)
 authenticated_organization_api_router.include_router(
     workflow_router, prefix="/workflows", tags=["workflows"]
 )
@@ -223,13 +229,12 @@ def get_organization_path(organization: OrganizationSlug):
 authenticated_organization_api_router.include_router(
     incident_role_router, prefix="/incident_roles", tags=["role"]
 )
-authenticated_organization_api_router.include_router(
-    forms_router, prefix="/forms", tags=["forms"]
-)
+authenticated_organization_api_router.include_router(forms_router, prefix="/forms", tags=["forms"])
 authenticated_organization_api_router.include_router(
     forms_type_router, prefix="/forms_type", tags=["forms_type"]
 )
 
+
 @api_router.get("/healthcheck", include_in_schema=False)
 def healthcheck():
     return {"status": "ok"}

src/dispatch/cli.py

@@ -83,7 +83,7 @@ def install_plugins(force):
     from dispatch.common.utils.cli import install_plugins
     from dispatch.database.core import SessionLocal
     from dispatch.plugin import service as plugin_service
-    from dispatch.plugin.models import Plugin
+    from dispatch.plugin.models import Plugin, PluginEvent
     from dispatch.plugins.base import plugins
 
     install_plugins()
@@ -104,6 +104,7 @@ def install_plugins(force):
                 description=p.description,
             )
             db_session.add(plugin)
+            record = plugin
         else:
             if force:
                 click.secho(f"Updating plugin... Slug: {p.slug} Version: {p.version}", fg="blue")
@@ -115,6 +116,23 @@ def install_plugins(force):
                 record.description = p.description
                 record.type = p.type
 
+        # Registers the plugin events with the plugin or updates the plugin events
+        for plugin_event_in in p.plugin_events:
+            click.secho(f"  Registering plugin event... Slug: {plugin_event_in.slug}", fg="blue")
+            if plugin_event := plugin_service.get_plugin_event_by_slug(
+                db_session=db_session, slug=plugin_event_in.slug
+            ):
+                plugin_event.name = plugin_event_in.name
+                plugin_event.description = plugin_event_in.description
+                plugin_event.plugin = record
+            else:
+                plugin_event = PluginEvent(
+                    name=plugin_event_in.name,
+                    slug=plugin_event_in.slug,
+                    description=plugin_event_in.description,
+                    plugin=record,
+                )
+                db_session.add(plugin_event)
         db_session.commit()
 
 

src/dispatch/conversation/enums.py

@@ -20,3 +20,8 @@ class ConversationButtonActions(DispatchEnum):
     service_feedback = "service-feedback"
     subscribe_user = "subscribe-user"
     update_task_status = "update-task-status"
+
+
+class ConversationFilters(DispatchEnum):
+    exclude_bots = "exclude-bots"
+    exclude_channel_join = "exclude-channel-join"

src/dispatch/cost_model/models.py

@@ -0,0 +1,111 @@
+from datetime import datetime
+from pydantic import Field
+from sqlalchemy import (
+    Column,
+    Integer,
+    String,
+    Boolean,
+    ForeignKey,
+    PrimaryKeyConstraint,
+    Table,
+)
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql.schema import UniqueConstraint
+from sqlalchemy_utils import TSVectorType
+from typing import List, Optional
+
+from dispatch.database.core import Base
+from dispatch.models import (
+    DispatchBase,
+    NameStr,
+    Pagination,
+    PrimaryKey,
+    ProjectMixin,
+    TimeStampMixin,
+)
+from dispatch.plugin.models import PluginEventRead, PluginEvent
+from dispatch.project.models import ProjectRead
+
+assoc_cost_model_activities = Table(
+    "assoc_cost_model_activities",
+    Base.metadata,
+    Column("cost_model_id", Integer, ForeignKey("cost_model.id", ondelete="CASCADE")),
+    Column(
+        "cost_model_activity_id",
+        Integer,
+        ForeignKey("cost_model_activity.id", ondelete="CASCADE"),
+    ),
+    PrimaryKeyConstraint("cost_model_id", "cost_model_activity_id"),
+)
+
+
+# SQLAlchemy Model
+class CostModelActivity(Base):
+    id = Column(Integer, primary_key=True)
+    plugin_event_id = Column(Integer, ForeignKey(PluginEvent.id, ondelete="CASCADE"))
+    plugin_event = relationship(PluginEvent, backref="plugin_event")
+    response_time_seconds = Column(Integer, default=300)
+    enabled = Column(Boolean, default=True)
+
+
+class CostModel(Base, TimeStampMixin, ProjectMixin):
+    __table_args__ = (UniqueConstraint("name", "project_id"),)
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    description = Column(String)
+    enabled = Column(Boolean)
+    activities = relationship(
+        "CostModelActivity",
+        secondary=assoc_cost_model_activities,
+        lazy="subquery",
+        backref="cost_model",
+    )
+    search_vector = Column(
+        TSVectorType("name", "description", weights={"name": "A", "description": "B"})
+    )
+
+
+# Pydantic Models
+class CostModelActivityBase(DispatchBase):
+    plugin_event: PluginEventRead
+    response_time_seconds: Optional[int] = 300
+    enabled: Optional[bool] = Field(True, nullable=True)
+
+
+class CostModelActivityCreate(CostModelActivityBase):
+    pass
+
+
+class CostModelActivityRead(CostModelActivityBase):
+    id: PrimaryKey
+
+
+class CostModelActivityUpdate(CostModelActivityBase):
+    id: Optional[PrimaryKey]
+
+
+class CostModelBase(DispatchBase):
+    name: NameStr
+    description: Optional[str] = Field(None, nullable=True)
+    enabled: Optional[bool] = Field(True, nullable=True)
+    created_at: Optional[datetime]
+    updated_at: Optional[datetime]
+    project: ProjectRead
+
+
+class CostModelUpdate(CostModelBase):
+    id: PrimaryKey
+    activities: Optional[List[CostModelActivityUpdate]] = []
+
+
+class CostModelCreate(CostModelBase):
+    activities: Optional[List[CostModelActivityCreate]] = []
+
+
+class CostModelRead(CostModelBase):
+    id: PrimaryKey
+    activities: Optional[List[CostModelActivityRead]] = []
+
+
+class CostModelPagination(Pagination):
+    items: List[CostModelRead] = []