feat: Add SurgicalBlockObsHandler with reusable dynamic URL token resolver

[vvkpd]

What This Introduces

Generic: Dynamic URL Token Resolver (Util.resolveUrlTokens)

A reusable utility method that resolves date tokens in any URL string at render time. Any form control that needs dynamic parameters in a configurable URL can use this.

Supported tokens:

Token	Resolves to
{NOW}	Current date, end of day, timezone-aware, URL-encoded
{NOW-Nd}	N days ago, start of day (e.g. {NOW-30d}, {NOW-40d})

Only days (d) are supported. Weeks/months are intentionally excluded — the surgical block API is designed for short date windows. Support for wider units can be added when a new consumer with a compatible endpoint requires it.

How to Use in Any Form Control

import { Util } from 'src/helpers/Util';

componentDidMount() {
  const { properties } = this.props;
  const defaultUrl = '/openmrs/ws/rest/v1/someEndpoint?from={NOW-30d}&to={NOW}';
  const url = Util.resolveUrlTokens(properties.URL || defaultUrl);
  httpInterceptor.get(url).then(...);
}

The designer descriptor exposes URL as a text field — the form builder configures the full URL including tokens:

{ name: 'URL', dataType: 'string', elementType: 'text',
  defaultValue: '/openmrs/ws/rest/v1/someEndpoint?from={NOW-30d}&to={NOW}' }

---

Specific: SurgicalBlockObsHandler

Uses the token resolver to implement a "Select Surgery" dropdown for operative report forms.

Data model: A SurgicalBlock is a time slot with a provider. Each block can contain multiple surgeries (SurgicalAppointment). The saved value is surgicalAppointment.uuid — the unique identifier per surgery — not the block UUID.

Default URL (used when properties.URL is not configured):

/openmrs/ws/rest/v1/surgicalBlock?activeBlocks=true
  &startDatetime={NOW-30d}
  &endDatetime={NOW}
  &includeVoided=false
  &v=custom:(id,uuid,provider:(uuid,person:(uuid,display),...),surgicalAppointments:(...))

Configuring a different date window (e.g. 40 days) — edit the URL field in implementer-interface:

...&startDatetime={NOW-40d}&endDatetime={NOW}...

All URL params are configurable — activeBlocks, includeVoided, v=custom representation, even the base endpoint path. Only the date values stay dynamic via tokens.

Results are filtered client-side by patientUuid (passed through the form rendering chain via Container → ObsControl) — only the current patient's surgeries appear in the dropdown.

---

Test Plan

• Add Select Surgery concept (Complex, SurgicalBlockObsHandler) to an operative report form via implementer-interface — verify URL text field appears in properties panel with token-based default
• Change {NOW-30d} to {NOW-40d} in the URL field, save and publish — verify API call uses 40-day window
• Open a patient's operative report form in clinical — verify dropdown shows only that patient's surgeries
• Verify that each surgery in a block appears as a separate dropdown option
• Verify form saves surgicalAppointment.uuid (not block UUID) on selection
• Unit tests: SurgicalBlock.spec.js (10 tests), designer/SurgicalBlock.spec.js (5 tests), Util.spec.js (7 new resolveUrlTokens tests)

🤖 Generated with Claude Code