Timeline
Timeline keeps what is said and what happens on a record: comments, internal notes and events, newest first, with who wrote them, the field changes they record and their attachments. Any module can give its records a timeline. Work order notes, order notes and the notes of accounts and contacts live in it.
| Feature | Id | Depends on |
|---|---|---|
| Timeline | CrestApps.OrchardCore.Timeline | nothing |
| Project | Holds |
|---|---|
CrestApps.OrchardCore.Timeline.Abstractions | TimelineEntry, TimelineVisibility, TimelineFieldChange, TimelineQuery, TimelinePage, TimelineResult, TimelineComposerKind, TimelineOptions, TimelineEntryIds, ITimelineService, ITimelineEntryHandler, ITimelineAccessProvider, ITimelineAccessService, TimelineConstants, TimelinePermissions and the registration helpers |
CrestApps.OrchardCore.Timeline.Core | TimelineEntryStore and its index (collection Timeline), DefaultTimelineService, DefaultTimelineAccessService and AddTimelineCore() |
CrestApps.OrchardCore.Timeline (module) | The Timeline view component, the add and redact endpoints, mentions, the migration and the recipe and deployment step |
Entries
| Member | Meaning |
|---|---|
Subject | The record, a RecordRef (Kind:Id) |
Kind | An open string: Comment, Note, Event, or a kind a module adds, such as a Reply |
Visibility | Public (everyone who may read the record, the customer included) or Internal |
Author | A PartyRef; empty for the site. AuthorName keeps a name only for an author no party source knows, such as a guest who wrote by e-mail |
Body | Plain text with line breaks |
Changes | { Field, From, To }, as people read them |
AttachmentIds | The entry's attachments |
Channel | Where it came in or went out, such as Email or Portal; empty for the admin |
ExternalId | The id it has outside the site, such as an e-mail's message id (indexed, up to 255 characters) |
RedactedUtc, RedactedBy | Set when the body was redacted |
Entries are kept as written. A body can only be redacted (ITimelineService.RedactAsync), which keeps the entry and its changes; the timeline card's Redact also deletes the entry's files.
Writing to a timeline
await timelineService.AddAsync(new TimelineEntry
{
Subject = new RecordRef(WorkOrdersConstants.RecordKind, workOrder.ItemId),
Kind = TimelineConstants.Kinds.Event,
Visibility = TimelineVisibility.Internal,
Author = new PartyRef(PartyKinds.User, userId),
Changes = [new TimelineFieldChange { Field = "Status", From = "New", To = "In progress" }],
});
AddAsync refuses an entry without a record, a kind, or a body, change or attachment, one whose body is longer than 20,000 characters, and one whose record, kind, channel or author is longer than the 64 characters the index holds. ITimelineEntryHandlers (AddTimelineEntryHandler<T>()) may refuse an entry in AddingAsync and act on it in AddedAsync, RedactedAsync, UpdatedAsync and DeletedAsync. ListAsync(TimelineQuery) pages a record's entries newest first (entries of the same time in a fixed order), with or without internal entries and for some kinds only.
The files of entries are indexed too, one row per file (TimelineAttachmentIndex: the attachment, the entry, its record, kind, visibility, author name, time and whether it was redacted), so a record lists all its files without reading its entries. ITimelineFileService.ListAsync(TimelineFileQuery) pages them newest first for one or more records (such as a ticket and the tickets merged into it), with the internal entries' files only of the records in InternalSubjects and never those of redacted entries; the caller decides, through ITimelineAccessService, which records' internal files the reader may see. Tickets' Files card is built on it. When the index was added, the Timeline.IndexFiles resumable step saved the existing entries with files again to index them.
Admin/timeline/entry/{id}?kinds= opens an entry's record at the page of its timeline that shows the entry (counting the newer entries of the kinds the timeline shows that the reader may read) and jumps to it: each entry on the card has the element id timeline-entry-{id} and is highlighted when it is the page's target.
Other paths:
ImportAsyncbrings in history that happened elsewhere, such as notes an older version kept on a record. It checks and stamps an entry likeAddAsyncbut keeps a long body whole and tells no handler, so nothing is announced. An entry whose id is already stored is left as it is: give the entry an id made from where it came from withTimelineEntryIds.FromSource(...), and importing again adds nothing.UpdateAsync(entryId, change)saves a change that doesn't rewrite what an entry says: thechangecallback gets aTimelineEntryChangeswith only the entry's properties (a delivery status a channel keeps), its channel and theExternalIdit was sent under;FindByExternalIdAsyncfinds the entry again. ANoticeproperty (TimelineConstants.Properties.Notice) is shown as a warning badge beside the entry, such as that an e-mail with it wasn't delivered; remove it when it no longer applies. Entries read throughFindAsync,FindByExternalIdAsyncandListAsyncare copies, so changing one never reaches the stored entry.DeleteAllAsync(subject)removes a deleted record's timeline and tells the handlers of each entry, so its files go too. A content item's timeline (and a ticket's) is deleted when the item is removed for good, by the resumable Timeline.DeleteRecords step (TimelineDeletionStep.RequestAsync), which the removal asks for in its own transaction: the request can't be lost, and a run that fails runs again on the next pass instead of leaving the entries and files behind.- A file is stored before the entry that keeps it, so a request that fails after storing it leaves the file behind. The Remove files no timeline entry kept background task (every hour,
TimelineOrphanFileSweeper) removes the files of records of the kinds with a timeline access provider that no entry keeps a day after they were stored (IAttachmentService.ListUploadedBeforeAsync, read against the file index); newer files are left alone, as their request may still be running. Files of those kinds belong to timeline entries, so a module that attaches files to such records outside a timeline must keep them in an entry.
Access
ITimelineService doesn't check who may read or write; a page that acts for a user asks ITimelineAccessService, which asks the ITimelineAccessProvider registered for the record's kind. A kind without a provider is refused, so a record's timeline is never shown by mistake. For many records at once, ITimelineAccessService.GetVisibleAsync(user, subjects, visibility) asks each kind's provider once through ITimelineAccessProvider.GetVisibleAsync(user, subjectIds, visibility); by default that asks CanViewAsync for each record, so a provider over a large store overrides it with one query (Tickets reads its ticket index through the reader's scope; content items are loaded in one query).
public sealed class WorkOrderTimelineAccess : ITimelineAccessProvider
{
public string SubjectKind => WorkOrdersConstants.RecordKind;
public Task<bool> CanViewAsync(ClaimsPrincipal user, RecordRef subject, TimelineVisibility visibility, CancellationToken cancellationToken = default) => ...;
public Task<bool> CanAddAsync(ClaimsPrincipal user, RecordRef subject, string kind, TimelineVisibility visibility, CancellationToken cancellationToken = default) => ...;
}
services.AddTimelineAccessProvider<WorkOrderTimelineAccess>();
Content items (the record kind Content, such as accounts, contacts and leads) come with a provider. Staff, who read and write internal entries, are the people who may edit the item itself (so a rule that decides per item, such as content access control, is honored) and every item of the type: owning an item isn't enough, so on a type its owners may edit, an owner doesn't read the staff's notes. Public entries are read by everyone who may view the item, which on many sites is every registered user, so a content type's timeline takes them only when a module opts the type in:
services.AllowPublicTimelineEntries("Project");
A visitor who isn't signed in reads nothing, even on a site where anyone may view content. The work order and order providers let an entry go only on a record that exists.
RedactTimelineEntries (Redact timeline entries) lets a user redact an entry on any record they may read; administrators have it by default.
The timeline card
A module shows a record's timeline on its own page by invoking the view component by name:
@await Component.InvokeAsync("Timeline", new { subject = $"WorkOrder:{Model.WorkOrder.ItemId}", title = T["Notes"].Value })
The card renders nothing when the user may not read the timeline. It shows the entries the user may read, 50 at a time with Older and Newer links, with the author's current name from the party directory, the time in the user's time zone, the field changes and an Internal badge. Its composer offers one button for each kind in TimelineOptions.ComposerKinds the access provider lets the user add: Add note (an internal Note) and Add comment (a public Comment) by default. The composer posts to Admin/timeline/add and comes back to the page, with the tenant's path base; a refused file or entry keeps what was typed. Redact asks for confirmation, then posts to Admin/timeline/redact/{id}. Optional arguments are returnUrl and kinds (comma-separated kinds to show).
A module adds a button for its own kind of entry:
services.AddTimelineComposerKind(new TimelineComposerKind
{
Kind = "Reply",
Visibility = TimelineVisibility.Public,
ButtonText = LocalizationSource.Create<Startup>("Reply"),
SubjectKinds = { "Inspection" },
});
The composer is the TimelineComposer shape, with the alternate TimelineComposer__{Kind} for one record kind. A module that needs more than a button, such as a reply that also changes the record's status, overrides it for its records and posts to its own action.
Mentions
With Orchard Core Notifications enabled, a user mentioned as @username in an entry gets a notification with a link to the record, unless they may not read the entry. The notification doesn't carry the entry's text, so a body redacted later isn't kept in it. An e-mail address is not a mention.
Data set and erasure
With Data Pipelines Core on, the Timeline data source has a TimelineEntries data set (one row per entry: its record, kind, visibility, channel, text, author, attachments and changes count) for the Report Builder and data pipelines. Each record kind's access provider decides which rows a reader gets, so an entry of a record the reader can't see, or of a kind with no provider, is never shown. Rows are checked 500 at a time through the batched access. The text of a redacted entry is empty, including in runs after an entry already exported was redacted, and a pipeline that runs as its publisher checks the publisher's access again on every run.
For a request to erase a person's data, ITimelineService.ScrubAsync(subject, scrub) rewrites the body, the author's name and the recorded change values of every entry on a record through the function given, such as PersonalDataAnonymizeContext.Scrub. Nothing else of an entry changes. Tickets uses it for the tickets a person asked for.
Recipe and deployment step
The TimelineEntries step adds entries through the import path, such as history brought from another system: each is checked and stamped, nothing is announced, and an entry whose ItemId is already stored is left as it is.
{
"name": "TimelineEntries",
"Entries": [
{
"Subject": "WorkOrder:4abc0000000000000000000000",
"Kind": "Note",
"Visibility": "Internal",
"Author": { "Kind": "User", "Id": "4user000000000000000000000" },
"Body": "Customer asked for a morning visit.",
"CreatedUtc": "2026-11-02T14:30:00Z"
}
]
}
The Timeline entries deployment step exports every entry of the record kinds it names (SubjectKinds, such as WorkOrder,Order), oldest first. Both have schemas for CrestApps Recipes.