Skip to main content
Version: Latest
Technical ManualLooking for step-by-step instructions? In the User Manual: Leads, Accounts and OpportunitiesContactsLoad Activities

Omnichannel CRM — leads, accounts and opportunities

Feature NameOmnichannel CRM
Feature IDCrestApps.OrchardCore.Omnichannel.Crm
Depends onOmnichannel Management, OrchardCore.Lists, OrchardCore.Title

The Omnichannel CRM feature adds leads, accounts and opportunities, as sales teams know them, to the Omnichannel CRM. None of them is a new storage model. Each is an ordinary content type, recognised by the parts it carries. The admin screens (lead lists and search terms, the Convert screen, AI lead conversion on a load, the Convert Lead subject action, lead statuses, lead sources, opportunity stages, imports and exports) are described step by step in Leads, Accounts and Opportunities in the User Manual.

With the feature off, nothing changes: every type with OmnichannelContactPart is a contact, as before.

Record kinds​

A type's parts decide what it is. The rules live in OmnichannelRecordKinds.

KindPartsNotes
ContactOmnichannelContactPart without LeadPartUnchanged.
LeadOmnichannelContactPart and LeadPartReachable like a contact; listed under Leads, not Contacts.
AccountAccountPartFrom the Accounts feature, which the CRM depends on. Holds its children through Orchard's ListPart.
OpportunityOpportunityPartAttach it to one type per kind of deal.

Contacts and opportunities are account children: they can belong to an account. Leads never do. The CRM registers this as an IAccountChildTypeRule (CrmAccountChildTypeRule), and the Accounts feature keeps every account type's list in line with it.

Because a lead keeps OmnichannelContactPart, every channel works on it with no second code path. That covers the dialer, SMS, do-not-contact checks, time zones and phone verification. The same compliance checks apply to leads and contacts.

What the feature creates​

The feature's migration runs once per tenant and never changes a type that already exists.

  • The LeadPart and OpportunityPart definitions.
  • The Account type comes from the Accounts feature.
    • Its list contains every contact and opportunity type, and one added later joins the list automatically.
    • An administrator can remove a type from the list, and it is not added back.
    • The account picker, the account search and the Account import column come from that feature too.
  • On a site that ran the CRM before accounts had a feature of their own, CrmAccountsFeatureMigrations enables the Accounts feature. The site's Account type and its accounts were created under the same names and are kept as they are.
  • The LeadIndex and OpportunityIndex tables. LeadIndex carries an index on ContentType, IsConverted, Latest and Published (IDX_LeadIndex_ContentType_Converted), which the count of the Leads list reads.
  • ContentType and IsConverted columns on OmnichannelContactIndex, backfilled from existing rows.
  • A seeded Lead Status catalog and Opportunity Stage catalog.

The Omnichannel CRM starter recipe (OmnichannelCrmStarter) turns the feature on and adds a Lead type, a Contact type and a SalesOpportunity type.

Parts and settings​

LeadPart​

Holds the lead's qualification state:

  • status, closed flag, source, list name, company, rating (Hot, Warm or Cold) and owner;
  • the conversion audit: when, by whom, and the contact, account and opportunity the lead produced;
  • LastScrubbedUtc: when an import last checked the lead's numbers against a do-not-call registry.
SettingPurpose
Converts into (TargetContactContentType)The contact type conversion creates. Empty means the person converting chooses.
Opportunity type (DefaultOpportunityContentType)The opportunity type offered first on conversion.

OpportunityPart​

Holds stage, open/closed/won flags, probability, amount, close date, owner, source, campaign, primary contact and the lead it came from. The account is the item's ContainedPart.

SettingPurpose
Stages (StageIds)The stages this opportunity type uses, from the Opportunity Stage catalog. Empty means every stage.

AccountPart​

A marker from the Accounts feature. Its setting records which types were added to the account's list, so a type an administrator removed is not added again.

The account page​

The CRM adds four tabs to an account's page, through AccountCrmTabsDisplayDriver:

  • Contacts: the contacts the account holds (ContainedPartIndex), by name, with their primary email and phone from OmnichannelContactIndex, and a New button per contact type the user may create, which opens the editor inside the account.
  • Opportunities: the opportunities with the account's OpportunityIndex.AccountContentItemId, open ones first by close date, with their stage, amount and close date.
  • Leads: the converted leads whose LeadIndex.ConvertedContactItemId is one of the account's contacts.
  • Activities: how many activities of the account's contacts are scheduled and completed, the next and the last, and List Activities for the account's activity page. It needs ListContactActivities.

Each list shows 25 rows; the Records tab lists everything. A tab shows only the content types the user may view.

Leads list count​

Interaction Center > Leads is the Content Admin list of the lead types with converted:false. Content Admin counts its items with the query that lists them, which joins the document table, ContentItemIndex and LeadIndex and counts the distinct documents. On a large tenant that count outlived the command timeout.

The CRM feature wraps the registered IContentsAdminListQueryService with LeadContentsAdminListQueryService. When LeadListCountQueryFactory can count the same leads from LeadIndex alone, the list query is returned as a LeadListQuery: the list rows come from the Content Admin query, and the count from a count(*) on LeadIndex that seeks IDX_LeadIndex_ContentType_Converted. The lead index count is used only when all of these are true; otherwise the list keeps its own count:

  • The contentTypeId route value names only lead types, and the user has View all content (ViewContent) on each of them.
  • At least one lead term is used (lead-status:, converted:, source:, list:, owner: or rating:), each with a plain value (no NOT, OR or AND).
  • The status: term, when used, is Latest, Published, Unpublished or All versions.
  • There is no free-text search, no other term, and the request carries no query string value other than q, page and pagesize.

The list terms and the count use the same predicates (LeadListTermPredicates), so the count agrees with the rows.

Caller matching​

Inbound voice and SMS resolve a number in tiers:

  1. contacts;
  2. open leads;
  3. converted leads, which never match.

A number shared by a contact and a lead resolves to the contact on both channels.

Conversion​

ILeadConversionService.ConvertAsync converts one lead. The conversion screen and the Convert Lead subject action both call it.

  1. Guards. A lead that is already converted returns its earlier result. A lead with a live activity (reserved, dialing or in progress) cannot be converted, except for the activity being completed.

  2. Contact. The lead merges into the chosen existing contact, or a new contact is created.

    • A merge copies only the parts and fields the contact lacks.
    • Phone numbers and email addresses are added when the contact does not have them.
    • Do-not-contact flags are combined so that any opt-out wins.
  3. Account. The modes are none, a new account, an existing account, or automatic. Automatic finds the one account named like the lead's company, or creates it. A merged contact keeps the account it already has.

  4. Opportunity. It is created optionally, with the contact as primary contact, in the account.

  5. Activities. Finished activities move to the contact and keep ConvertedFromLeadItemId. Open activities move, or are cancelled.

  6. Re-pointers and handlers run, and the lead is closed with the converted status. The built-in re-pointers move:

    • the lead's message threads;
    • its open callbacks (pending, scheduled or in progress);
    • its unresolved voicemails.

    Finished callbacks and resolved voicemails stay with the lead as its history.

Report Builder​

Leads, accounts and opportunities are content items, so the Report Builder reads them through Orchard Core's Content items data source: one data set per content type, with the values of LeadPart and OpportunityPart, such as LeadPart.IsConverted, LeadPart.ConvertedAccountItemId or OpportunityPart.IsWon. An activity's ConvertedFromLeadItemId in the Omnichannel Activities data set names the lead it belonged to before the conversion. The site decides which content types are leads, so join that field to the ContentItemId of the lead type the report reads. See Report Builder data sets.

Extension points​

InterfaceUse it to
ILeadConversionHandlerRun code before (ConvertingAsync) and after (ConvertedAsync) a conversion, for example to copy extra data or notify another system.
ILeadConversionRepointerMove records your module keeps against the lead's id to the contact. Messaging, callbacks and voicemail use this.
ISubjectActionHandlerAdd a subject action type that runs on a disposition. Order decides when it runs among the actions of the same disposition; Convert Lead uses -100 so it runs first.

Workflows​

With Orchard Core Workflows on, the feature adds a Lead Converted event and a Convert Lead task, both in the Omnichannel CRM category.

  • Lead Converted starts for every conversion, whatever started it.
    • Workflow.Input.ContentItem is the contact, so content tasks that follow act on the customer.
    • The input also carries Lead, LeadContentItemId, ContactContentItemId, AccountContentItemId, OpportunityContentItemId and ContactCreated.
    • The workflow is correlated with the contact's id.
  • Convert Lead converts the lead its Liquid expression resolves to, by default {{ Workflow.Input.ContentItem.ContentItemId }}.
    • It uses the same unattended rules as the subject action: it merges only into a single matching contact.
    • Its outcomes are Converted, with the contact's id in Workflow.LastResult, and Failed.
    • A lead that was already converted counts as Converted and does not start Lead Converted again.

AI conversion​

An automatic activity load of a lead type can let the AI convert the leads it qualifies. The option is stored on the load as LeadAIConversionSettings, copied onto each automated activity it loads and onto retries, and has four settings: Enabled, CreateOpportunity, OpportunityContentType and QualificationGuidance.

  • When an automated SMS conversation or AI call concludes and the activity's record is still an open lead, the conclusion prompt tells the model it is talking to a lead and asks for ConvertLead.
    • The model is given what qualified means: the load's QualificationGuidance, or else the subject goal.
    • A call nobody spoke on, or whose AI session was lost, is never converted.
  • On ConvertLead: true, the lead is converted through IUnattendedLeadConverter before the disposition's subject actions run, so they work on the contact.
    • That is the same converter the Convert Lead subject action and workflow task use: it merges only into a single matching contact, uses the automatic account mode, and moves open activities.
    • A failed conversion is logged and leaves the lead unchanged.
  • Saving a load that creates an opportunity is refused when neither the load nor the lead type names an opportunity type, because an unattended conversion that cannot find its opportunity type fails as a whole.

Lead status types​

A lead status is exactly one of three types, stored as the IsClosed and IsConverted flags so recipes and deployments carry them unchanged:

TypeFlagsNotes
OpenneitherOnly an open status can be the default (IsDefault).
ClosedIsClosedActivity loads skip it unless a load picks this status.
ConvertedIsClosed and IsConvertedSet only by conversion. Marking another status converted takes the type from the old one, which becomes Closed.

A status saved with IsDefault and either closed flag is rejected, so a recipe cannot make new leads start out closed.

Import and export columns​

Leads are imported and exported through Content Transfer (Bulk Import and Bulk Export), like contacts. LeadPartContentImportHandler adds these columns to a lead type's file (all of them are exported):

ColumnAlso accepted asImport
LeadStatusStatus, Lead StatusBy status name.
LeadSourceSource, Lead SourceBy lead source name; a name that matches no lead source is ignored.
LeadListList, List Name, ListNameThe list or import the lead arrived in.
CompanyCompany Name, CompanyName, OrganizationFree text.
RatingLead RatingOne of the choices of the lead's Rating field, such as Hot, Warm or Cold.
LeadOwnerOwner, Lead OwnerBy user name.
IsConverted, ConvertedUtc, ConvertedContactItemIdExport only. A converted lead in an import file is left unchanged.
LastScrubbedUtcExport only: when the lead's numbers were last checked against a do-not-call registry. An import that checks the registries sets it.

The import screen's lead options (skip numbers that belong to a contact or an open lead, and the list name, source, status and owner stamped on rows without their own) and the export's Leave out converted leads option are described in Import and export leads.

Recipes and deployment​

Both catalogs have a recipe step and a deployment step, matched by name on import:

{
"name": "OmnichannelLeadStatus",
"LeadStatuses": [
{ "Name": "Working - Contacted", "Order": 2 },
{ "Name": "Nurturing", "Order": 3 }
]
}
{
"name": "OmnichannelOpportunityStage",
"OpportunityStages": [
{ "Name": "Negotiation", "Order": 4, "Probability": 70 }
]
}

Permissions​

PermissionDisplay nameAllows
ConvertLeadConvert leadsConverting a lead. Implied by Manage activities (ManageActivities).
EditConvertedLeadEdit converted leadsChanging a lead after it was converted. Without it, a converted lead is read-only.
ManageLeadStatusesManage lead statusesEditing the Lead Status catalog.
ManageOpportunityStagesManage opportunity stagesEditing the Opportunity Stage catalog.

Listing and editing leads, accounts and opportunities uses the ordinary content permissions of each type; the Leads, Accounts, Opportunities and Lead Sources menu items need ListContent.

Reports​

The feature adds Lead funnel, Lead conversion by source and list and Opportunity pipeline to the Reports area, in the CRM & Campaigns category. They read the lead and opportunity indexes, are filtered by date range only, and require View Omnichannel reports (ViewOmnichannelReports). See the report catalog for the other CRM reports.