Configure and manage output formats for your reports through the Report Design Manager interface.

The Report Design Manager is your central hub for configuring how reports are presented to users. Here you link specific output formats (renderers) to reports, configure template settings, and manage the availability of different output options across your organization.

Table of Contents

Understanding Report Designs

What is a Report Design?

A Report Design is a configuration that connects:

• A specific report definition (your data and logic)

• A renderer type (how to format the output)

• Custom settings (templates, properties, parameters)

• User access permissions (who can use this format)

Report Design vs Report Definition

Report Definition

• Contains: Data logic, cohorts, indicators, parameters

• Defines: What data to collect and how to calculate it

• Created by: Report builders in the reporting interface

Report Design

• Contains: Output formatting instructions

• Defines: How data should be presented to users

• Created by: Administrators in the Design Manager

Relationship

Built-in vs Custom Designs

Built-in Designs

Always Available:

• Web Display (default for all reports)

• Standard Excel, CSV, HTML exports

Characteristics:

• No configuration required

• Work with any report

• Limited customization options

Custom Designs

Created Through Design Manager:

• Excel templates with custom layouts

• HTML templates with specific styling

• Custom CSV formats

• Specialized XML outputs

Characteristics:

• Require configuration and setup

• Linked to specific reports

• Highly customizable

• Can include advanced features

Accessing Design Manager

Navigation Path

1. Log into OpenMRS with administrative privileges

2. Navigate: Administration → Report Administration

3. Click: Report Designs

Required Permissions

• Manage Report Designs

• View Administration Functions

• Manage Reports (for full functionality)

Interface Overview

Main Design List

• All configured report designs displayed in table format

• Filter options by report or renderer type

• Quick actions for edit, delete, preview

Design Categories

• Standard Renderers: CSV, Excel, HTML, XML

• Template Renderers: Excel templates, Text templates

• Custom Renderers: Organization-specific formats

Creating Report Designs

Step-by-Step Process

Step 1: Access Creation Interface

1. Click: "Add Another" button in Report Designs

2. Select: Report definition from dropdown

3. Choose: Renderer type

Step 2: Basic Configuration

Step 3: Renderer-Specific Setup

Configuration varies by renderer type:

Standard Excel Renderer

CSV Renderer

HTML Renderer

Configuring Standard Renderers

Excel Export Design

Use Case: Professional reports with consistent formatting

Configuration Steps:

1. Select: "Excel Report Renderer"

2. Set Name: "Professional Excel Export"

3. Configure Options:

   Include Headers: Yes Date Format: dd/MMM/yyyy Number Format: #,##0.00 Sheet Names: Auto-generate from data set names

CSV Export Design

Use Case: Data analysis and external system integration

Configuration Steps:

1. Select: "CSV Report Renderer"

2. Set Name: "Data Analysis Export"

3. Configure Options:

   Field Delimiter: , (comma) Text Delimiter: " (quote) File Extension: .csv Encoding: UTF-8 Include Headers: Yes

Custom CSV Format

Use Case: Integration with specific external systems

Configuration Steps:

1. Select: "Delimited Text Report Renderer"

2. Set Name: "Government Reporting Format"

3. Configure Options:

   Field Delimiter: | (pipe) Text Delimiter: None File Extension: .txt Date Format: yyyy-MM-dd Header Row: Custom headers

Template-Based Designs

Excel Template Design

Prerequisites: Template file already created

Configuration Steps:

1. Select: "Excel-based Template"

2. Upload Template: Browse and select .xls file

3. Configure Template Properties:

   Template File: Upload your .xls template Expressions: - Prefix: # (default) - Suffix: # (default)

4. Set Repeating Sections (if needed):

   Sheet: 1 Row: 8 Dataset: patientList

5. Add Design Properties:

   Property Key: reportTitle Property Value: Monthly HIV Program Report

Text Template Design

Prerequisites: Template content prepared

Configuration Steps:

1. Select: "HTML/text-based template"

2. Paste Template Content: Full HTML/text template

3. Set Content Type: text/html, text/xml, text/plain

4. Configure Template Engine: Groovy or Velocity

Advanced Template Configuration

Excel Template Properties

Repeating Sections Configuration

For Row-Per-Patient Data:

For Multi-Location Reports:

For Multi-Sheet Reports:

Design Properties

Custom Properties for Templates:

Usage in Template:

Text Template Configuration

Template Engine Selection

Groovy Engine:

• More powerful scripting capabilities

• Full Java library access

• Better for complex data manipulation

• Syntax: <% code %> and $variable

Velocity Engine:

• Simpler syntax

• Faster for basic templating

• Limited programming features

• Syntax: #set($var = value) and $variable

Content Type Options

Managing Output Options

Controlling Available Formats

Default Behavior

Without custom report designs:

• Web Display: Always available

• Standard Exports: Excel, CSV, HTML, XML available for all reports

With Custom Designs

When you add custom report designs:

• Custom formats appear in output format dropdown

• Standard formats remain unless specifically disabled

• Users choose from all available options

Format Organization

Naming Strategy

Use descriptive names that indicate:

• Purpose: "Management Summary", "Data Analysis Export"

• Audience: "Clinical Staff Dashboard", "Government Report"

• Format: "Excel Template", "Mobile HTML View"

Examples:

Grouping Related Designs

For Complex Reports with Multiple Audiences:

User Experience Considerations

Output Format Selection

When users run reports, they see:

Loading and Performance

Consider user impact:

• Web Display: Instant results

• Standard Exports: Fast generation

• Custom Templates: May take longer

• Complex Templates: Consider caching

Advanced Configuration

Conditional Output Options

Role-Based Format Availability

Configure different formats for different user types:

Clinical Users:

• Web Display

• Patient List (Excel)

• Clinical Summary (HTML)

Management Users:

• Web Display

• Management Dashboard (HTML)

• Executive Report (Excel Template)

Data Analysts:

• All standard exports

• Data Analysis (CSV)

• Statistical Export (Excel)

Report-Specific Configurations

Patient-Level Reports

Appropriate formats:

• Excel for patient lists

• HTML for patient summaries

• CSV for data analysis

• Avoid: Complex templates (performance)

Indicator Reports

Appropriate formats:

• Excel templates for management

• HTML dashboards for monitoring

• Web display for interactive exploration

• Avoid: Large CSV exports (unnecessary)

Performance Optimization

Template Complexity Guidelines

Simple Templates (< 1 second):

• Basic data substitution

• Minimal calculations

• Small data sets (< 100 rows)

Moderate Templates (1-10 seconds):

• Basic repeating sections

• Simple charts/graphs

• Medium data sets (100-1000 rows)

Complex Templates (10+ seconds):

• Multiple repeating sections

• Complex calculations

• Large data sets (> 1000 rows)

• Multiple worksheets/pages

Caching Strategies

For Frequently Run Reports:

• Consider pre-generating during off-peak hours

• Cache results for common parameter combinations

• Use simpler formats for frequent access

Multi-Language Support

Template Localization

For International Deployments:

Content Translation

In Templates:

User Access Control

Permission-Based Access

Design Management Permissions

Creating/Editing Designs:

• Manage Report Designs

• Manage Reports

• View Administration Functions

Using Custom Formats:

• Run Reports

• View Reports

• Access to underlying report definition

Role-Based Format Control

Implementation Strategy

Option 1: Multiple Report Definitions

• Create separate reports for different audiences

• Link appropriate designs to each report

• Control access via report permissions

Option 2: Single Report, Multiple Designs

• One report definition with comprehensive data

• Multiple designs for different presentation needs

• All users see all format options

Option 3: Custom Role Checking

• Advanced: Custom renderers that check user roles

• Most flexible but requires development

Testing Access Control

Validation Process

1. Create test user accounts with different role combinations

2. Test report access with each account type

3. Verify format availability matches expectations

4. Check output quality for each user type

5. Document access patterns for future reference

Maintenance and Updates

Regular Maintenance Tasks

Monthly Reviews

• Check template performance - Monitor generation times

• Review user feedback - Address usability issues

• Update templates - Incorporate new requirements

• Clean up unused designs - Remove obsolete formats

Quarterly Assessments

• Evaluate format usage - Which designs are actually used?

• Performance optimization - Improve slow templates

• User training needs - Address knowledge gaps

• Technology updates - Leverage new features

Version Control

Template Updates

When modifying existing designs:

1. Backup current version - Export existing configuration

2. Test changes thoroughly - Use test environment

3. Document modifications - What changed and why

4. Communicate changes - Notify affected users

5. Monitor for issues - Watch for problems after deployment

Change Documentation

Backup and Recovery

Design Export

Regular backup process:

1. Export design configurations - Save settings and templates

2. Document dependencies - Note required modules/versions

3. Store template files - Keep copies of .xls and template files

4. Test restoration - Verify backups work

Disaster Recovery

If designs are lost:

1. Import saved configurations - Restore from backups

2. Re-upload template files - Restore custom templates

3. Test all formats - Verify functionality

4. Update documentation - Reflect any changes

Troubleshooting

Common Issues and Solutions

🚫 Design Not Appearing in Output Options

Symptoms: Custom format doesn't show in dropdown when running report

Common Causes:

• Design not linked to correct report definition

• User lacks required permissions

• Design configuration incomplete

Solutions:

1. Verify report linkage - Check Report Definition field

2. Check user permissions - Confirm user can access format

3. Complete configuration - Ensure all required fields filled

4. Test with admin account - Isolate permission issues

📊 Template Rendering Errors

Symptoms: Error messages when generating template-based reports

Common Causes:

• Corrupted template files

• Invalid template syntax

• Missing template dependencies

Solutions: