T11.4: Customizes Clinical UI

Overview

Patient search is the starting point for clinicians using the Clinical Viewer. Before viewing any clinical data, a clinician must search for and select a patient. The patient search configuration determines what search criteria are available, what minimum criteria must be provided, and how the search interacts with the Master Patient Index (MPI) to find matching patients.

Proper patient search configuration balances usability (making it easy for clinicians to find patients) with performance (preventing overly broad searches) and security (ensuring appropriate patient identification).

Minimum Search Requirements

• Configure the minimum number of fields that must be populated before a search can execute
• Different MPI types may enforce different minimums:
• HealthShare MPI: Typically requires last name plus one additional field
• External MPI: May have its own minimum requirements
• Common minimum configurations:
• Last name + date of birth
• Last name + first name
• Patient identifier (MRN, SSN)
• Minimum requirements are configured in the Clinical Viewer settings

Search Configuration Options

• Available Fields: Select which search fields appear on the search form
• Required Fields: Designate which fields are mandatory
• Default Values: Pre-populate fields with default values (e.g., current facility)
• Search Behavior: Configure exact match vs. partial match for text fields
• Results Display: Configure columns shown in search results and sort order
• Identifier Search: Enable search by specific identifier types (MRN, SSN, insurance ID)

---

Overview

Chartbooks are the highest-level organizational unit in the Clinical Viewer's display hierarchy. A chartbook defines the complete clinical data view available to a user, containing one or more charts that group related clinical information. Chartbooks are managed through the TrakCare Tools interface, which provides tools for creating, copying, modifying, and organizing chartbook structures.

Understanding chartbook management is essential for customizing the Clinical Viewer to meet the needs of different clinical roles and departments within the organization.

Chartbook Hierarchy

• Chartbook: Contains one or more charts (e.g., "Emergency Department Chartbook")
• Chart: A tab or section within a chartbook (e.g., "Medications", "Lab Results", "Diagnoses")
• Chart Item/Profile: Individual data displays within a chart (e.g., "Active Medications List", "Recent Lab Results Table")

Creating Chartbooks

1. Open TrakCare Tools from the Clinical Viewer 2. Navigate to Chartbook management 3. Create a new chartbook or copy an existing one as a starting point 4. Name the chartbook descriptively (reflecting its intended audience or use) 5. Add charts to the chartbook in the desired sequence 6. Configure chart items within each chart 7. Save and test the chartbook

Design Recommendations

• Create role-specific chartbooks (nursing, physician, pharmacy, etc.)
• Start by copying a default chartbook and customizing it
• Keep the number of charts manageable (avoid overwhelming users with too many tabs)
• Order charts by clinical priority (most commonly accessed first)
• Consider workflow when organizing chart sequence
• Test chartbooks with representative users before deployment

---

Overview

Charts are the second level of the Clinical Viewer display hierarchy, appearing as tabs within a chartbook. Each chart groups related clinical information and contains one or more chart items that display specific data types (medications, lab results, diagnoses, etc.). Chart configuration involves creating charts, arranging them in the desired order, and populating them with appropriate chart items.

Creating and Copying Charts

1. Open TrakCare Tools and navigate to the target chartbook 2. Add a new chart or copy an existing chart from the same or different chartbook 3. Set the chart name and display label 4. Configure chart properties (visibility, default expanded/collapsed state) 5. Add chart items to the chart

Chart Sequence Management

• Charts appear as tabs in the order defined in the chartbook configuration
• Reorder charts by adjusting their sequence numbers
• Place frequently accessed charts earlier in the sequence
• Consider clinical workflow when determining order (e.g., demographics → diagnoses → medications → results)

Chart Properties

• Name: Internal identifier for the chart
• Display Label: Text shown on the chart tab in the Clinical Viewer
• Sequence: Numeric value controlling tab order
• Visible: Whether the chart is shown or hidden
• Default State: Whether the chart content is expanded or collapsed by default

---

Overview

Chart items are the most granular configurable element in the Clinical Viewer display hierarchy. Each chart item displays a specific type of clinical data (e.g., active medications, recent lab results, problem list) in a specific format (table, list, summary). Chart items are associated with profiles that define the data source, columns displayed, and formatting options.

Customizing chart items allows organizations to control exactly what data clinicians see and how it is presented.

Adding Chart Items to Charts

1. Open TrakCare Tools and navigate to the target chart 2. Add a new chart item or copy an existing one 3. Select the profile that defines the data type and display format 4. Configure the display name and sequence within the chart 5. Set additional options (drop-down display, default expanded/collapsed)

Configuring Display Names

• Override the default display name with a custom label
• Use clinically meaningful names that are familiar to the target user group
• Keep names concise for readability in the tab/header display

Result Detail Pages

• Configure drill-down behavior for chart items that support detailed views
• When a user clicks on a row in a table chart item, the detail page opens
• Detail pages show the full record with all available fields
• Customize which fields appear on the detail page

Drop-Down List Display

• Chart items can be configured to display as collapsible drop-down sections
• Users click to expand/collapse sections within a chart
• Useful for organizing multiple related data types within a single chart
• Reduces visual clutter by allowing users to focus on relevant sections

---

Overview

The Layout Picker and Layout Editor are the primary tools for customizing the visual arrangement and content of the Clinical Viewer. The Layout Picker allows administrators to select from available layouts, create copies, and manage layout assignments. The Layout Editor provides a visual interface for modifying the structure and content of individual layouts, including adding, removing, and rearranging components.

These tools provide a visual approach to Clinical Viewer customization that does not require direct code editing.

Layout Picker

• Access the Layout Picker from the Clinical Viewer's configuration menu
• Browse available layouts by type and category
• Copy an existing layout to create a new customizable version
• Assign layouts to user groups or specific users
• Remove user/group preferences to revert to default layouts
• Preview layouts before assigning them

Layout Editor Operations

• Select: Choose elements in the layout for modification
• Move: Drag elements to new positions within the layout
• Add: Insert new elements (data fields, labels, separators) into the layout
• Remove: Delete elements from the layout
• Resize: Adjust the size and proportions of layout elements
• Properties: Modify properties of selected elements (labels, formatting, data binding)

Working with Layouts

1. Open the Layout Picker and find the layout to customize 2. Copy the layout to create a new working version 3. Open the copied layout in the Layout Editor 4. Make desired changes (add/remove/move elements) 5. Save the modified layout 6. Assign the layout to the appropriate user group 7. Test the layout in the Clinical Viewer

---

Overview

Component options provide fine-grained control over how individual elements in the Clinical Viewer behave and display. These settings affect the user experience by controlling aspects like the number of rows displayed in tables, column arrangement, and navigation behavior. Configuring these options allows administrators to optimize the Clinical Viewer for different clinical workflows and user preferences.

Component Options Configuration

• Access component options through the Layout Editor or TrakCare Tools
• Each component type has its own set of configurable options
• Options are specific to the component instance (different instances can have different settings)

Number of Rows Setting

• Controls how many data rows are displayed by default in table components
• Lower values reduce scrolling but may hide important data
• Higher values show more data but may require scrolling
• Consider the typical amount of data and screen size when setting this value
• Users can typically override the default to see more or fewer rows

Column Merging and Splitting

• Merging: Combine multiple data fields into a single display column to save horizontal space
• Splitting: Separate a merged column back into individual columns for more detail
• Useful for optimizing layout on different screen sizes
• Consider readability when merging columns (too much data in one column reduces clarity)

Navigation Configuration

• Configure breadcrumb navigation for drilling into detail pages
• Set default chart tab selection when opening a chartbook
• Configure back button behavior for returning from detail pages
• Set auto-refresh intervals for data that changes frequently

---

Overview

CSS styling and branding customizations allow organizations to make the Clinical Viewer match their institutional identity and clinical workflow preferences. From changing colors and fonts to hiding visual elements and adjusting layouts for different devices, CSS customization provides extensive control over the Clinical Viewer's appearance.

These customizations are applied through stylesheet overrides that do not modify the core Clinical Viewer code, ensuring they can be maintained across system upgrades.

Stylesheet Modification

• Create custom CSS files that override default styles
• Place custom stylesheets in the appropriate configuration directory
• Use CSS specificity to override default styles without modifying core files
• Common customizations include:
• Header/footer colors and branding
• Font family and size adjustments
• Table row striping and hover effects
• Button styling and positioning

Data Styling

• Apply conditional styling to data based on values (e.g., critical lab results in red)
• Customize how coded values are displayed (code only, description only, or both)
• Format date/time displays according to organizational preferences
• Style different data categories with distinct visual treatments

Hiding Separators and Changing Headers

• Use CSS display:none or visibility:hidden to remove visual separators
• Override header label text using CSS content property or configuration settings
• Adjust header formatting (bold, color, size) to improve readability

Mobile and Responsive Layouts

• Configure responsive breakpoints for different screen sizes
• Adjust column layouts for tablet and mobile devices
• Consider touch-friendly sizing for interactive elements on mobile
• Test layouts on target devices to ensure usability

---

Overview

Patient information icons provide visual indicators in the Clinical Viewer's patient banner, alerting clinicians to important patient conditions, allergies, alerts, and other notable information at a glance. Icon configuration involves creating icon definitions, organizing them into icon profiles, and assigning those profiles to the Clinical Viewer. Icons can be standard (built-in) or custom (organization-defined).

Well-configured icons improve clinical safety by making critical patient information immediately visible without requiring the clinician to navigate to specific charts or chart items.

Creating and Modifying Icons

1. Access icon management in TrakCare Tools 2. Create a new icon or modify an existing one 3. Define the icon properties:

• Image: The visual icon (typically a small image file)
• Tooltip: Text displayed when hovering over the icon
• Trigger Condition: The data condition that causes the icon to display
• Priority: Display order when multiple icons are present

4. Test the icon with sample patient data

Icon Types

• Alert Icons: Indicate patient alerts (fall risk, isolation, code status)
• Allergy Icons: Show allergy status (known allergies, no known allergies, not documented)
• Condition Icons: Indicate specific clinical conditions (diabetes, pregnancy, infectious disease)
• Custom Icons: Organization-defined icons for any purpose

Icon Profiles

• Icon profiles are collections of related icons
• Create profiles for different clinical contexts (e.g., "Emergency Department Icons", "Inpatient Icons")
• Add individual icons to a profile
• Assign the profile to the Clinical Viewer chartbook or configuration
• Multiple icon profiles can be active simultaneously

Adding Icon Profiles to Clinical Viewer

1. Create the icon profile with desired icons 2. Navigate to the Clinical Viewer configuration 3. Add the icon profile to the chartbook or global configuration 4. Test that icons display correctly for patients with matching conditions 5. Verify tooltip text and icon appearance

---

Overview

Custom JavaScript elements allow organizations to add interactive behavior to the Clinical Viewer beyond what is available through standard configuration. JavaScript can be added to chart items and tables to respond to user actions, perform calculations, display custom widgets, or integrate with external systems. This capability provides maximum flexibility for specialized display requirements.

However, custom JavaScript should be used judiciously, as it can potentially interfere with the core Clinical Viewer functionality if not carefully implemented and tested.

Adding JavaScript to Chart Items

• JavaScript elements can be associated with specific chart items or tables
• Scripts execute in the context of the chart item's DOM element
• Access to the data displayed in the chart item is available through the DOM or data model
• Scripts can modify the display, add event handlers, or inject new elements

Use Cases for Custom JavaScript

• Calculated Fields: Compute derived values from displayed data (e.g., BMI from height and weight)
• Conditional Formatting: Apply complex formatting rules that go beyond CSS capabilities
• External Links: Generate links to external systems based on displayed data values
• Custom Widgets: Add interactive widgets (charts, graphs, toggles) to the display
• Validation Alerts: Display warnings or alerts based on data analysis

Best Practices

• Keep JavaScript minimal and focused on the specific requirement
• Use namespaced functions to avoid conflicts with core code
• Test thoroughly in all supported browsers
• Handle errors gracefully to prevent breaking the Clinical Viewer
• Document all custom JavaScript for maintenance
• Consider performance impact, especially for scripts that process large datasets
• Update and test custom scripts when the Clinical Viewer is upgraded

---

Overview

Filtering, grouping, and sorting configurations control how clinical data is organized and presented to clinicians in the Clinical Viewer. Default settings ensure that the most relevant data is immediately visible, while grouping organizes data into logical categories, and sorting arranges items in a clinically meaningful order. Custom list row filters provide programmatic control over which data rows are displayed.

Default Filtering Configuration

• Configure filters on chart items to show relevant subsets by default
• Common filters: active vs. historical, date ranges, status values
• Examples:
• Medications: Show active medications only (hide discontinued)
• Lab Results: Show last 30 days only
• Diagnoses: Show active problems (hide resolved)
• Filters can be toggled by users if permitted

Grouping Configuration

• Group data by category, facility, date period, or custom criteria
• Grouping adds visual separators and headers between groups
• Examples:
• Medications grouped by category (cardiovascular, endocrine, etc.)
• Lab results grouped by test type
• Encounters grouped by facility
• Configure group header display and expand/collapse behavior

Sorting Configuration

• Set default sort order for data within chart items
• Common sort options: date (ascending/descending), alphabetical, priority
• Multi-level sorting (primary sort, secondary sort)
• Examples:
• Lab results sorted by collection date descending (most recent first)
• Medications sorted alphabetically by drug name
• Diagnoses sorted by onset date

Custom List Row Filters

• Implement custom class methods for complex filtering logic
• Filters can evaluate multiple data fields and apply complex rules
• Associate the filter class with the chart item configuration
• Use for requirements that cannot be met with standard filter settings
• Examples:
• Show only medications prescribed by the current facility
• Filter results based on clinician specialty
• Apply organization-specific business rules to data display

---

Overview

Custom transforms modify how data appears in the Clinical Viewer without changing the underlying stored data. Transforms are applied during the data retrieval and display pipeline, allowing organizations to format values, combine fields, derive calculated values, or apply display rules that are specific to their clinical workflow. Transforms operate on the SDA data as it is retrieved from the ECR and prepared for display.

Creating Custom Transforms

1. Identify the data presentation requirement (formatting, combining fields, calculations) 2. Create a transform class that implements the required logic 3. Configure the transform to accept the source data and produce the display output 4. Register the transform with the Clinical Viewer configuration

Applying Transforms to Components

• Associate transforms with specific chart items or component types
• Configure which data fields the transform processes
• Set the transform's output format and target display element
• Transforms can chain (output of one transform feeds into another)

Transform Examples

• Date Formatting: Convert dates from stored format to organization-preferred display format
• Unit Conversion: Convert measurement units (e.g., Celsius to Fahrenheit)
• Field Combination: Combine first name + last name into a single display field
• Code Display: Show code description instead of code value, or both
• Calculated Values: Compute eGFR from creatinine, age, and gender

Verifying Transform Results

• Test transforms with sample patient data
• Compare transformed display values with source data to verify accuracy
• Check edge cases: missing data, null values, unexpected formats
• Verify that transforms work correctly across different data sources
• Test performance with large datasets

---

Overview

Layout import and export functionality allows organizations to transfer Clinical Viewer layout configurations between environments (development, test, production) and between instances. This capability supports a controlled deployment workflow where layouts are developed and tested in a non-production environment before being deployed to production. It also provides the ability to revert to default layouts when customizations cause issues.

Exporting Layouts

1. Access the export function in TrakCare Tools or the Layout Picker 2. Select the layouts to export (individual or batch) 3. Optionally include user group assignments in the export 4. Export generates a file (typically XML format) containing the layout definitions 5. Store exported files in version control for change tracking

Importing Layouts

1. Access the import function in the target environment 2. Select the layout file to import 3. Review the import preview (layouts to be created or updated) 4. Confirm the import operation 5. Verify imported layouts in the Layout Picker 6. Test imported layouts in the Clinical Viewer

User Group Migration

• User group definitions can be exported alongside layouts
• Ensure user groups exist in the target environment or are created during import
• Map user groups if naming conventions differ between environments
• Verify group-to-layout assignments after import

Reverting to Defaults

• Remove custom layout preferences to revert to system defaults
• Can be done at the user level (reset individual user) or group level (reset entire group)
• Access the preference removal function in the Layout Picker
• Useful for troubleshooting when custom layouts cause display issues
• Default layouts are preserved and always available as fallback

---

Overview

When custom SDA streamlet types are created (as covered in T11.2), they must also be configured for display in the Clinical Viewer. This involves creating SITE-Default configuration files that define the display properties, creating profiles that bind custom streamlet properties to display fields, and adding chart items for the custom streamlets to the appropriate chartbooks.

This configuration ensures that custom data stored in the ECR is accessible and visible to clinicians through the standard Clinical Viewer interface.

SITE-Default Configuration Files

• SITE-Default files define display configuration for streamlet types
• Create a SITE-Default file for each custom streamlet type
• Define which properties are displayed and their display order
• Specify column labels, formatting, and display types (text, date, code, etc.)
• Place configuration files in the appropriate Clinical Viewer configuration directory

Profile Configuration for Custom Streamlets

1. Create a new display profile for the custom streamlet type 2. Define the data fields to display (mapping to custom streamlet properties) 3. Configure column headers and display formatting 4. Set default sorting and filtering options 5. Register the profile in the Clinical Viewer configuration

Adding Custom Streamlets to Chartbooks

1. Create a chart item that uses the custom streamlet display profile 2. Add the chart item to the appropriate chart in the target chartbook 3. Configure the chart item's display name and position 4. Set any chart item-specific options (number of rows, grouping, filtering) 5. Test the display with sample data

End-to-End Verification

• Verify that custom streamlet data is stored correctly in the ECR
• Confirm that the SITE-Default file is properly configured
• Test that the display profile retrieves and formats data correctly
• Check that the chart item appears in the Clinical Viewer at the expected location
• Verify that detail drill-down works for custom streamlet records

---

Overview

Security groups and access profiles control which users can see which chartbooks and what level of access they have to clinical data in the Clinical Viewer. This security layer ensures that different clinical roles see appropriate chartbooks configured for their workflow, and that access to sensitive data is properly controlled. Chartbook access management is integrated with the broader UCR security model.

Assigning Chartbooks to Security Groups

1. Define security groups that correspond to organizational roles (e.g., "Physicians", "Nurses", "Pharmacists") 2. Assign chartbooks to security groups through the Clinical Viewer administration 3. A security group can have multiple chartbooks assigned (users can switch between them) 4. A chartbook can be assigned to multiple security groups 5. Configure the default chartbook for each security group

Creating Access Profiles

• Access profiles define what data types and operations are available to a user group
• Configure read access to specific streamlet types
• Restrict access to sensitive data categories (behavioral health, HIV, substance abuse)
• Set feature permissions (print, export, annotation)
• Associate access profiles with security groups

User Role Assignment

1. Create or identify the appropriate security role 2. Assign the role to the corresponding security group 3. Add users to the role through the user management interface 4. Users inherit the chartbook assignments and access profiles of their group 5. Users with multiple roles may have access to multiple chartbooks

Best Practices

• Follow the principle of least privilege (give minimum necessary access)
• Align security groups with organizational roles and responsibilities
• Review and update group memberships regularly
• Test access configurations with representative users from each role
• Audit chartbook access to verify compliance with access policies
• Document the mapping between security groups, chartbooks, and access profiles

---