Health Cloud Timeline

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:

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:

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:

1. Confirm Patient_Visit__c has an Account__c lookup to Account (or AccountId standard field).
2. In Setup > Timeline > Categories, create a category named "Visits" if it does not exist.
3. 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>

4. Deploy via SFDX or Metadata API. Verify in Setup > Timeline that the definition appears and is active.
5. 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:

1. Audit which objects currently appear on the legacy timeline using the Health Cloud Custom Settings under HealthCloud__Timeline__c or equivalent.
2. For each object, confirm its relationship path to Account.
3. Create TimelineObjectDefinition records for each object, matching category labels to the existing filter structure so end users experience minimal change.
4. Add the Industries Timeline Lightning component to the patient page layout (App Builder > drag Industries Timeline from component panel).
5. Remove the legacy HealthCloud.Timeline component from the same page layout.
6. 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

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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:

• All target objects have a confirmed Account relationship path (direct lookup or chain)
• All referenced timeline category values exist in Setup > Timeline > Categories with exact spelling match
• All TimelineObjectDefinition metadata records are set to active: true and deployed successfully
• Industries Timeline component is on the page layout; legacy HealthCloud.Timeline component is removed if present
• Timeline renders correctly on at least 2 representative patient records with real data
• API version in project configuration is v55.0 or later
• Admin runbook updated with new TimelineObjectDefinition entries and relationship field names

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. 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.

2. 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.

3. 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

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