SLA Watch

SLA Watch turns matter key dates into a compact, traffic-light strip that helps teams see what is due, what is close, and what is already overdue.

It is designed for matter and work-item portal pages where the question is simple: which obligations need attention right now?

What it does

SLA Watch reads the current matter’s key dates and renders them as urgency pills:

• Red for overdue items or dates inside the red threshold
• Amber for dates inside the amber threshold
• Green for dates further away
• “+N more” when more dates exist than should be shown in the page strip

Each pill opens an action panel with practical context and next steps. Users can review the date story, see parent matter context, manage reminders, add comments, open the key-date detail view, and where permitted, progress the key date to an available status such as done or missed.

Business value

SLA Watch helps teams move from passive date tracking to active SLA management.

Instead of requiring users to open a key dates list, interpret due dates, and manually decide what matters most, the widget brings priority to the surface. It is especially useful on matter pages where lawyers, partners, or operations teams need a quick risk signal without leaving the work they are doing.

Key capabilities

At-a-glance SLA risk

The widget classifies key dates against configurable red and amber thresholds. The result is a concise row of colour-coded pills sorted critical-first.

Matter-aware context

When key dates come from child work items or ancestor-scoped searches, the widget can show parent reference and title in tooltips. It can also enrich the panel and tooltip with parent matter context such as owner, partner or responsible role, current phase, and latest activity.

Working-days disclosure

SLA Watch calculates both calendar-day and working-day distance where useful. It uses the tenant’s Sharedo working-day calendar when available, and falls back gracefully to weekday-only logic if the calendar call is unavailable.

Reminders at the point of risk

Users can see reminder badges on pills, review reminder details, add new reminders, and remove existing reminders from the action panel.

Comments on the key date

The action panel displays the key date’s comment thread and allows users to add public or private comments, subject to platform permissions.

Status action buttons

When the platform reports available phase transitions, SLA Watch renders action buttons such as “Mark Done” or “Mark Missed”. Closing a date removes it from the active watch list when closed dates are excluded.

Calm when silent

By default, the widget hides itself when there are no matching key dates. This keeps quiet matters clean while still allowing configurators to show an empty state when desired.

Where it fits

Use SLA Watch on matter, incident, or work-item portal pages where teams need immediate visibility of time-sensitive obligations. It is most valuable when the page already has operational context and the widget can act as a live SLA risk indicator.

Common placements include:

• Matter summary pages
• Matter operational dashboards
• Incident or claim pages with parent-matter key dates
• Work-item pages where descendant or ancestor key dates should be surfaced

Configuration model

Workflow authors can configure:

• Which key date types to include
• Whether to include open and/or closed dates
• Whether descendant key dates should be included
• Whether the search should resolve to the closest ancestor of a selected type
• Parent work-item type filters
• Red and amber urgency thresholds
• Maximum number of pills shown
• Empty-state behaviour
• Tooltip and parent-context fields
• Role system names used to resolve owner and partner/responsible roles

Important note

SLA Watch intentionally mirrors Sharedo’s out-of-the-box Key Dates List V2 query surface so it behaves like a standard key-date consumer. Some of the APIs used are internal Sharedo endpoints rather than public /api/v1/public endpoints, so they should be validated as part of Sharedo upgrade testing.

Technical notes

Component identity

• Widget id: Alt.SlaWatch
• Designer id: Alt.SlaWatchDesigner
• Source path: src/widgets/sla-watch
• Runtime wrapper: widget.ts
• Core logic: core.ts
• Pure classifier and formatting helpers: classifier.ts
• Designer marshalling: designer-model.ts
• Templates:
• templates/SlaWatch.html
• templates/SlaWatchDesigner.html

The widget registers under the Alt namespace and exposes loadAndBind and onDestroy lifecycle methods expected by Sharedo widgets.

Runtime architecture

widget.ts is intentionally thin. It resolves the work-item context from either:

1. configuration.sharedoId, or
2. $ui.pageContext.sharedoId()

It then creates SlaWatchCore and exposes core.model to the Knockout template.

SlaWatchCore owns:

• loading state
• key date search
• SLA classification
• overflow handling
• selected pill panel state
• reminder form state
• comment form state
• parent-context hydration
• key-date story hydration
• working-day calendar hydration
• phase transition action state
• request cancellation on destroy

The classifier is split into classifier.ts so tests can exercise the date logic without loading browser globals.

Classification logic

The key functions are:

• daysBetween(dueIso, nowDate)
• workingDaysBetween(dueIso, nowDate, holidays)
• classify(keyDates, opts, nowDate)
• formatLabel
• formatTooltip
• formatParentContextSuffix
• describeReminder

Classification is deterministic and client-side:

1. Entries without an id or parseable due date are skipped.
2. Calendar days are calculated by UTC date part, not by elapsed hours.
3. Working days are calculated separately and exclude weekends plus configured non-working days when loaded.
4. Pills are bucketed:

• overdue or days <= redDays → red
• days <= amberDays → amber
• otherwise → green

1. Pills are sorted by tier first, then by soonest due date.

Completed dates are filtered client-side when includeClosed is false. Completed phase system names include milestone-complete and milestone-done.

Default configuration

Core defaults include:

limitResultsTo: 20
includeOpen: true
includeClosed: false
keyDateTypePaths: ["/task/milestone/"]
includeDescendentsKeyDates: true
useClosestKeyDateAncestorTypePath: ""
keyDateParentTypePaths: []
parentDisplayMode: "always"

redDays: 7
amberDays: 14
maxPills: 6
showWhenEmpty: false
showParentInTooltip: true

ownerRoleSystemNames: ["matter-owner"]
partnerRoleSystemNames: ["matter-partner", "responsible-partner", "primary-fee-earner"]
showOwnerInTooltip: true
showPartnerInTooltip: true
showPhaseInTooltip: true
showLastActivityInTooltip: true

showTypeDescription: true
showCreatedInTooltip: true
showNotesEditor: true

The designer validates:

• red threshold must be non-negative
• amber threshold must be non-negative
• amber must be greater than or equal to red
• max pills must be at least 1
• result limit must be at least 1
• at least one of open or closed dates must be included

API usage

The component mirrors Sharedo’s out-of-the-box Key Dates List V2 query model.

Known API surfaces from source:

• POST /api/keyDates/search
• primary key-date search
• internal endpoint
• uses the same request shape as the OOB Key Dates List V2 widget
• GET /api/workday/{fromIso}/{toIso}
• loads non-working days for holiday-aware working-day counts
• failure is non-fatal; widget falls back to weekday-only calculation
• /api/keyDates/for/{parentId}
• used to hydrate key-date details, reminders and related fields
• /api/tasks/{keyDateId}/addReminder/
• adds reminders
• POST /api/comments/list
• loads comments attached to the key date
• POST /api/comments/
• creates a comment
• PUT /api/comments/{id}/isPrivate
• toggles privacy after comment creation
• GET /api/sharedo/{keyDateId}/phase
• loads current phase and available transitions
• /api/sharedo/{keyDateId}/transitionHistory
• loads lifecycle history for the key-date story

Several of these are internal Sharedo APIs rather than /api/v1/public APIs. Keep them on the upgrade-test checklist.

Authentication implementation note

core.ts uses a local $ajax wrapper rather than Foundry’s plain ApiClient for key calls. The source comment explains that the platform $ajax wrapper attaches the session bearer token, while the fallback plain jQuery path may not do so for internal endpoints.

The wrapper normalises failures into SharedoApiError classifications such as:

• permission
• not-found
• validation
• transient
• aborted
• unknown

Stale response and teardown handling

The core uses Foundry’s loadSequence() to ignore stale responses when refreshes overlap. It also owns an AbortController; onDestroy() marks the instance destroyed and aborts in-flight requests.

This is important because the widget performs multiple progressive hydration calls after the initial key-date search.

Progressive hydration

Initial load performs the key-date search and renders classified pills. Additional data is hydrated progressively:

• reminders
• parent context
• key-date story
• comments
• phase transition availability
• working-day calendar data

Failures in progressive enhancements are generally logged and swallowed so the SLA strip remains usable even if an enrichment endpoint fails.

Knockout model surface

The template binds to model and expects key observables including:

• loaded
• error
• pills
• overflowCount
• hasPills
• hasOverflow
• showRow
• refreshing
• selectedPill
• reminderForm
• commentForm
• transitioningPillIds
• holidayCount
• holidaysFetchFailed

Each pill includes observables/computeds for:

• reminders
• active reminder count
• reminder tooltip suffix
• parent context
• parent context tooltip suffix
• story
• story tooltip suffix
• comments
• comment count

Designer implementation

The designer is split between:

• designer.ts: Knockout entry point and widget-designer registration
• designer-model.ts: pure state creation, validation and config serialization

Type-path selection uses the OOB sharedo-type-picker component with selectMode: "typePath". CSV fields are retained as fallbacks for tenants where the picker component is unavailable or for headless/test configuration.

buildDesignerConfig prefers picker arrays over CSV values and trims/deduplicates arrays before saving.

Tests

The test files cover:

• UTC date-part day counting
• same-day, tomorrow and overdue labels
• threshold bucketing
• critical-first sorting
• tooltip parent display
• malformed item skipping
• completed-phase detection
• active reminder filtering
• reminder description formatting
• designer defaults
• designer validation
• picker-array vs CSV fallback behaviour
• parent-context role defaults

Deployment

Use the unified tenant deployment wrapper rather than a component-specific script:

npm run deploy:tenant -- --tenant <tenant> --widget Alt.SlaWatch

The designer widget may need to be deployed as its own manifest on first installation depending on the deployment path:

npm run deploy:tenant -- --tenant <tenant> --widget Alt.SlaWatchDesigner

How it's built

Git is the single source of truth — the component lives at src/widgets/sla-watch. Deployment is to the Sharedo IDE; the manifest defines how the platform loads it.

User guide

Purpose

Use SLA Watch when a portal page needs a compact view of upcoming or overdue key dates. It helps users prioritise time-sensitive obligations without opening a full key-date list.

Adding the widget

1. Open the portal/page designer.
2. Add the SLA Watch widget.
3. Open the widget configuration panel.
4. Configure the query and thresholds.
5. Save and publish the page.

The widget works best on a work-item or matter page where a Sharedo context is available.

Query settings

Limit results pulled from server

Controls how many key dates are retrieved before the widget sorts and displays them.

Default: 20

Use a higher value if matters commonly have many key dates and you want the “most urgent” set to be chosen from a wider pool.

Include open key dates

Shows planned or outstanding key dates.

Default: on

Most SLA Watch placements should keep this enabled.

Include closed key dates

Shows complete, done or missed key dates.

Default: off

Leave this off if the widget should focus only on dates that still need action.

Key date work type paths

Choose which key-date types to include.

Default: /task/milestone/

If no types are selected, the search can return all key-date types. Use this carefully on high-volume matters.

Include descendants’ key dates

Includes key dates from child work items.

Default: on

This is useful when a matter page needs to surface obligations held on related child records.

Use closest ancestor of this type for search context

Optionally tells the widget to search from the nearest ancestor matching a selected type.

Use this when the widget is placed on a child work item, but the SLA view should be based on the parent matter or another ancestor.

Key date parent sharedo types

Optionally restricts results to key dates whose parent work item matches selected type paths.

Use this to avoid mixing operational key dates from unrelated child work-item types.

SLA thresholds

Red threshold

Dates due in this many days or fewer are red. Overdue dates are always red.

Default: 7

Amber threshold

Dates due after the red threshold but within this many days are amber.

Default: 14

The amber threshold must be greater than or equal to the red threshold.

Max pills shown

Controls how many pills appear in the row before the widget collapses the rest into a “+N more” indicator.

Default: 6

Use a smaller number for narrow header areas and a larger number for dashboard-style pages.

Display settings

Render the row even when there are no key dates

Default: off

When off, the widget hides itself if there are no matching key dates. This is the recommended “calm when silent” behaviour.

Turn it on if users should see an explicit “No upcoming key dates” message.

Show parent reference and title in pill tooltip

Default: on

Recommended when descendant or ancestor searching is enabled, because it helps users understand which matter or work item owns each key date.

Parent display mode

Forwarded to the underlying key-date API to align with the out-of-the-box Key Dates List behaviour.

Options:

• Always
• Never
• When not in current context

The pill UI has its own tooltip setting for whether parent information is displayed to users.

Parent matter context

SLA Watch can enrich each pill with context that helps answer “who owns this?” and “where is it stuck?”

Configurable fields include:

• owner role system names
• partner/responsible role system names
• show phase
• show owner
• show partner/responsible person
• show latest activity

Owner role system names

Enter one or more role system names, comma-separated, in priority order.

The first role that resolves to a value is used.

Example:

matter-owner

Partner / responsible role system names

Enter one or more role system names, comma-separated, in priority order.

Example:

matter-partner, responsible-partner, primary-fee-earner

If the resolved partner/responsible person is the same as the owner, the widget hides the duplicate value.

Type-path fallback fields

The designer includes CSV fallback fields for type paths.

Use them only when the type picker is unavailable in a tenant or when configuring the widget through a raw/headless path.

In normal designer use, prefer the type pickers.

What users see

Loading

While data is loading, users see a loading message.

Pill row

Each pill shows:

• key-date name
• due label, such as today, tomorrow, 5d, or 3d overdue
• urgency colour
• reminder bell if active reminders exist

Overflow

How to use it

Add SLA Watch to a portal page via the Sharedo Portal Designer (it appears under Alterspective / Matter). Configure it via the designer cog on the placed widget.

For the authoritative configuration fields and behaviour, see the component's designer help panel and the source linked in the footer.