Health Cloud Timeline
This skill activates when a practitioner needs to configure the Industries Enhanced Timeline in Health Cloud — adding custom object records, clinical events, or activity history to the patient or member timeline view. It covers TimelineObjectDefinition metadata setup, timeline category configuration, component placement, and migration away from the legacy managed-package Timeline component.
Before Starting
Gather this context before working on anything in this domain:
- Confirm the org has a Health Cloud or Industries license that includes the Timeline permission. Without this,
TimelineObjectDefinition records cannot be created and the Industries Timeline component will not render.
- Identify whether the page currently uses the legacy Timeline component (from the
HealthCloud managed package, typically installed as HealthCloud.Timeline) or the Industries Timeline component (industries:timeline or forceContent:timeline in the page layout). These two components use completely different configuration mechanisms.
- Determine the relationship path from each target object back to the Account object. Enhanced Timeline requires every displayed object to be related to the patient/member through Account — direct or through a related Account lookup. Objects without an Account relationship path cannot be surfaced.
- Check the API version in use.
TimelineObjectDefinition metadata is available at API v55.0 and later. Orgs deploying via older tooling or scratch org definitions with older API versions will get metadata errors.
Core Concepts
TimelineObjectDefinition Metadata Type
TimelineObjectDefinition is the metadata type that tells the Industries Enhanced Timeline which objects to query and how to display their records. Each definition maps one object to the timeline and configures:
| Field | Purpose |
|---|
| Object API name | The Salesforce object whose records appear as timeline entries |
| Date field | Which date/datetime field determines where the record appears on the timeline axis |
| Title field | Field shown as the entry headline |
| Description field | Optional secondary text |
| Timeline category | The filter group label (appears in the filter picklist on the timeline component) |
| Icon | SLDS utility icon name to display alongside entries |
TimelineObjectDefinition records are org-wide metadata; they are not record-type-specific. Once deployed, all instances of the Industries Timeline component in the org will include records from that object definition unless filtered by category at the component level.
Account Relationship Requirement
The Enhanced Timeline queries objects by traversing the relationship graph from the patient's Account record. Every object surfaced on the timeline must have a lookup or master-detail relationship that connects it to Account — either a direct AccountId field or a chain of lookups that resolves to Account. Objects related only to Contact, Case, or other non-Account objects cannot be displayed. This is the single most common configuration mistake.
For Health Cloud clinical objects (e.g., PatientHealthCondition, EhrPatientMedication, ClinicalEncounter), the Account relationship is built into the Health Cloud data model and can be referenced directly. For custom objects, verify the relationship chain before writing the TimelineObjectDefinition.
Timeline Categories
Timeline categories are the filter labels that appear in the Industries Timeline component's filter picklist. A practitioner creates category values in Setup and then assigns each TimelineObjectDefinition to one category. Well-designed categories group related clinical events (e.g., "Medications", "Encounters", "Labs") so the clinician can filter the timeline to relevant event types without scrolling through unrelated entries.
Categories are configured in Setup > Timeline > Categories, not in the metadata file itself. If a TimelineObjectDefinition references a category name that does not exist as a configured category value, the timeline will silently omit the filter option — a hard-to-diagnose display gap.
Legacy vs. Enhanced Timeline Components
The original Health Cloud managed package shipped a Timeline component under the HealthCloud namespace. This component is deprecated as of Health Cloud v236 (Summer '22). Salesforce has directed customers to migrate to the Industries Timeline component, which is backed by TimelineObjectDefinition metadata.
Key differences:
| Aspect | Legacy Timeline (HealthCloud.Timeline) | Enhanced Timeline (Industries Timeline) |
|---|
| Configuration | Custom Settings and list views | TimelineObjectDefinition metadata |
| Object support | Limited to Health Cloud clinical objects | Any object with Account relationship |
| API version | Not metadata-API-configurable | API v55.0+ |
| Filter UI | Hardcoded categories | Configurable timeline categories |
| Future support | Deprecated — no new features | Actively developed |
Common Patterns
Pattern 1: Adding a Custom Object to the Patient Timeline
When to use: An org has a custom object (e.g., Patient_Visit__c) with an Account__c lookup field, and the care team needs visit records to appear chronologically on the patient record timeline.
How it works:
- Confirm
Patient_Visit__c has an Account__c lookup to Account (or AccountId standard field).
- In Setup > Timeline > Categories, create a category named "Visits" if it does not exist.
- Create a
TimelineObjectDefinition metadata record:
<?xml version="1.0" encoding="UTF-8"?>
<TimelineObjectDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
<active>true</active>
<baseObject>Patient_Visit__c</baseObject>
<dateField>Visit_Date__c</dateField>
<descriptionField>Visit_Notes__c</descriptionField>
<icon>event</icon>
<isActive>true</isActive>
<label>Patient Visit</label>
<labelPlural>Patient Visits</labelPlural>
<nameField>Name</nameField>
<timelineCategory>Visits</timelineCategory>
</TimelineObjectDefinition>
- Deploy via SFDX or Metadata API. Verify in Setup > Timeline that the definition appears and is active.
- Open the patient record and confirm the Industries Timeline component shows visits in the expected date range.
Why not the alternative: Manually customizing page layouts with related lists is not equivalent — related lists show records in a table, not chronologically alongside other clinical events. The timeline provides the unified chronological view clinical staff need to understand care history at a glance.
Pattern 2: Migrating from Legacy to Enhanced Timeline
When to use: The org was provisioned before Health Cloud v236 and uses the legacy HealthCloud.Timeline component. Clinical data appears on the timeline today, but the component is deprecated and no longer receives updates.
How it works:
- Audit which objects currently appear on the legacy timeline using the Health Cloud Custom Settings under
HealthCloud__Timeline__c or equivalent.
- For each object, confirm its relationship path to Account.
- Create
TimelineObjectDefinition records for each object, matching category labels to the existing filter structure so end users experience minimal change.
- Add the Industries Timeline Lightning component to the patient page layout (App Builder > drag
Industries Timeline from component panel).
- Remove the legacy
HealthCloud.Timeline component from the same page layout.
- Validate in a sandbox with representative patient records before deploying to production.
Why not the alternative: Leaving both components on the page layout simultaneously causes duplicate entries and performance issues. The two components query independently and do not deduplicate records.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|
| Adding a standard Health Cloud clinical object (EhrPatientMedication, PatientHealthCondition) | Create TimelineObjectDefinition referencing the standard Health Cloud object | These objects already have Account relationships built into the Health Cloud data model |
| Adding a custom object with no Account relationship | Add Account lookup to the custom object first, then create TimelineObjectDefinition | Enhanced Timeline cannot surface the object without Account path |
| Org uses legacy HealthCloud.Timeline | Full migration to Industries Timeline + TimelineObjectDefinition | Legacy component is deprecated; no new features or bug fixes will be delivered |
| Need to filter timeline by event type per user role | Configure timeline categories and use component-level category filtering | Categories are the supported filter mechanism; record type filters on the component are not available |
| Object is related to Contact only, not Account | Evaluate adding an Account lookup or using a junction object | There is no workaround; Account relationship is mandatory for Enhanced Timeline |
Recommended Workflow
Step-by-step instructions for an AI agent or practitioner working on this task:
- Verify license and permissions — Confirm the org has Health Cloud or an Industries license that includes Timeline. Check that the running admin user has the "Industries Timeline" permission. Without these, Setup > Timeline will not appear.
- Audit object relationships — For each object to be surfaced, trace the relationship path to Account. Document the lookup field name used. Flag any objects that do not have an Account path before proceeding.
- Create timeline categories in Setup — Navigate to Setup > Timeline > Categories and add any new category values needed (e.g., "Medications", "Encounters", "Labs", "Custom Visits"). Note the exact label spelling — it must match the
timelineCategory field in the metadata exactly.
- Author and deploy TimelineObjectDefinition metadata — Create one XML file per object in the
timelineObjectDefinitions/ metadata folder. Set active to true, choose the correct date field, and assign the correct timeline category. Deploy via SFDX (sf project deploy start) or Metadata API.
- Place the Industries Timeline component on the page layout — In App Builder, open the patient or member record page and add the
Industries Timeline component. If the legacy component is present, remove it in the same deployment to avoid duplicate entries.
- Validate with representative records — Open 2–3 patient records that have data in each configured object. Confirm entries appear in the correct date order, under the correct category, with the correct icon and label.
- Document the configuration — Record each TimelineObjectDefinition, its object, date field, and category in the org's admin runbook. Future administrators will need this to diagnose gaps or add new object types.
Review Checklist
Run through these before marking work in this area complete:
Salesforce-Specific Gotchas
Non-obvious platform behaviors that cause real production problems:
-
Legacy component deprecation is silent in production — The legacy HealthCloud.Timeline managed-package component continues to function after deprecation; Salesforce does not force-remove it. Orgs discover the deprecation only when they hit a bug that Salesforce will not fix or when a new Health Cloud release breaks the component. Proactive migration to the Industries Timeline is the only safe path.
-
Category name mismatch silently drops timeline entries — If the timelineCategory value in a TimelineObjectDefinition does not match an active category in Setup > Timeline > Categories (case-sensitive, exact match), the object's records will not appear in the filter picklist and will render uncategorized or not at all depending on component settings. There is no deployment-time validation of this mismatch.
-
Account relationship is strictly required — Contact-only objects cannot appear — Practitioners who design custom Health Cloud objects with only a Contact lookup (no Account lookup) cannot surface those objects on the Enhanced Timeline regardless of workarounds. The component's query engine anchors to Account. Retrofitting an Account lookup onto an existing object with data requires a data migration and re-deployment.
Output Artifacts
| Artifact | Description |
|---|
timelineObjectDefinitions/*.timelineObjectDefinition | Deployable metadata XML files, one per object surfaced on the timeline |
| Timeline category configuration | Category values added in Setup > Timeline > Categories |
| App Builder page layout | Patient/member record page with Industries Timeline component placed and legacy component removed |
| Migration checklist | Tracking sheet for legacy-to-enhanced migration covering each previously configured object |
Related Skills
health-cloud-patient-setup — Person Account and patient record type setup required before timeline configuration makes sense; the timeline anchors to the patient's Account record