Skip to main content
Version: Latest
Technical ManualLooking for step-by-step instructions? In the User Manual: Agreements with accounts

Agreements

Agreements keeps the agreements you have with accounts, such as a support contract or a maintenance contract. One agreement can carry the terms of several modules at once: Work Orders' visit schedules and Tickets' service level sit on the same agreement, each module adding its own panel to the editor.

It is three projects:

ProjectHolds
CrestApps.OrchardCore.Agreements.AbstractionsAgreement, AgreementHours, AgreementBalance, AgreementUsage, IAgreementUsageProvider, IAgreementBalanceService, IAgreementObserver, IAgreementManager, AgreementsPermissions, AgreementsConstants
CrestApps.OrchardCore.Agreements.CoreThe YesSql store and AgreementIndex, the numbering and rules (AgreementHandler), AgreementBalanceService, AgreementLifecycle, AgreementPeriods, AddAgreementsCore()
CrestApps.OrchardCore.AgreementsThe Agreements feature: the admin list and editor, the account tab, the background task, the recipe and deployment step

The agreement​

ValueMeaning
NumberSA-00042, from the locked Agreements.Agreement sequence
Name, NotesWhat people call it, and notes for the people who work under it
StatusDraft, Active, Paused, Expired, Canceled. Only an active agreement in its period is in force (IsInForceOn)
AccountIdThe account it is with
StartDate, EndDate, TimeZoneIdIts period, counted in its time zone; no end runs until it is canceled
HoursKind (None, Block used until it runs out, MonthlyAllowance each calendar month), Hours, and RoundingMinutes (0, 6, 15 or 30) each entry of time is rounded up to
ExpiringNoticeDaysHow long before its end it is told to be about to end
PropertiesThe terms other modules keep on it

The handler checks the name, the dates, the notice (0 to 365 days), the hours (more than none, at most 100,000, when it covers hours) and the rounding, for the editor and recipes alike. Only a draft can be deleted; a copy starts as a draft.

Hours used and left​

Modules that work under an agreement register an IAgreementUsageProvider, which lists the time spent under an agreement in a range (AgreementUsage: who, when, how long, on what). IAgreementBalanceService.GetBalanceAsync works out the period that holds a day (the agreement's whole period for a block, the calendar month in its time zone for an allowance), asks every provider, rounds each entry up and returns the AgreementBalance: covered, used, left, the overage past what is covered (billable: work goes on), the share used and the entries. ListInForceAsync finds the agreements of an account in force on a day.

Life cycle​

The Agreements background task (hourly) runs AgreementLifecycle: an active agreement past its end becomes Expired; one within its notice tells every IAgreementObserver.OnExpiringAsync once; and one whose used hours pass 80% and 100% of the period's cover tells OnHoursUsedAsync once for each, starting again each period (HoursWarnings).

Pages​

Content > Agreements in the admin menu lists the agreements (the admin list's List and Grid layouts) with their status and hours; the editor has the general values, the Covered hours panel with how the hours stand now, and the panels other modules add through display drivers on Agreement. An account's page lists its agreements with the hours used, and links to a new agreement for it.

Reports​

With Reports on, two reports under Reports > Billing & Usage need ViewAgreements (AgreementReportsStartup). Both read each active agreement with covered hours, or the one chosen in their Agreement filter, as of the last day of the chosen days (today at the latest), in the period that holds that day: the whole agreement for a block, the month for an allowance.

  • Agreement Usage: for each agreement, the hours covered, used, left and past the cover, the share used (colored from 80% and at 100%), and the day the hours ran out or, at the pace from the period's start, are expected to (AgreementBurnDown.ProjectRunOut); then where the hours went, by usage provider.
  • Agreement Burn-down: a line chart of the hours left at the end of each day of the period against an even pace through it (a period without an end has no even line), with a table of the days for the chosen agreement; without a choice, the six agreements that used the most of their hours (AgreementBurnDown.Days).

Tickets adds Account Health (see Tickets).

Permissions​

PermissionAllows
ManageAgreementsCreate, change, copy and delete agreements
ViewAgreementsSee agreements and their hours (implied by the one above)

Recipe and deployment​

The Agreements step creates or updates agreements by ItemId, with every value above and the Properties of other modules; the deployment step exports them all.

{
"name": "Agreements",
"Agreements": [
{
"Name": "Gold support",
"Status": "Active",
"AccountId": "4d33nzx1h8tcms96qw9qsjn9xj",
"StartDate": "2026-11-01",
"TimeZoneId": "America/New_York",
"Hours": { "Kind": "MonthlyAllowance", "Hours": 10, "RoundingMinutes": 15 }
}
]
}

Extending agreements​

  • Keep your module's terms in Properties (agreement.Put(new MyTerms { ... })) and add a display driver on Agreement for their editor.
  • Register an IAgreementUsageProvider for the time your module spends under an agreement.
  • Register an IAgreementObserver to act when an agreement is about to end or passes a share of its hours.
  • Register an IAgreementTermsValidator to check your terms: the agreement's own rules call every validator, so the editor and recipes check the same set whichever feature carries the terms.

With Notifications on, AgreementAccountManagerNotifier sends the account's manager (AccountTeamPart.OwnerStaffId, through the staff directory, to their user) a notification when an agreement passes 80% and 100% of its hours and when it is about to end.

Tickets is a consumer: its terms are TicketAgreementTerms (the desks and ticket types it covers, the service-level policy of its tickets) with a Tickets panel, a new ticket takes the agreement that covers it, and its billable time counts against the hours (see Tickets).

Work Orders is one consumer: its visit schedules are WorkOrderAgreementTerms with a Visits panel, and the billable labor of its completed work orders counts against the hours (see Work Orders).