Omnichannel CRM — leads, accounts and opportunities
| Feature Name | Omnichannel CRM |
| Feature ID | CrestApps.OrchardCore.Omnichannel.Crm |
| Depends on | Omnichannel 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.
| Kind | Parts | Notes |
|---|---|---|
| Contact | OmnichannelContactPart without LeadPart | Unchanged. |
| Lead | OmnichannelContactPart and LeadPart | Reachable like a contact; listed under Leads, not Contacts. |
| Account | AccountPart | From the Accounts feature, which the CRM depends on. Holds its children through Orchard's ListPart. |
| Opportunity | OpportunityPart | Attach 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
LeadPartandOpportunityPartdefinitions. - The
Accounttype 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
Accountimport column come from that feature too.
- On a site that ran the CRM before accounts had a feature of their own,
CrmAccountsFeatureMigrationsenables the Accounts feature. The site'sAccounttype and its accounts were created under the same names and are kept as they are. - The
LeadIndexandOpportunityIndextables.LeadIndexcarries an index onContentType,IsConverted,LatestandPublished(IDX_LeadIndex_ContentType_Converted), which the count of the Leads list reads. ContentTypeandIsConvertedcolumns onOmnichannelContactIndex, 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.
| Setting | Purpose |
|---|---|
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.
| Setting | Purpose |
|---|---|
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 fromOmnichannelContactIndex, 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.ConvertedContactItemIdis 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
contentTypeIdroute 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:orrating:), each with a plain value (noNOT,ORorAND). - 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,pageandpagesize.
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:
- contacts;
- open leads;
- 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.
-
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.
-
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.
-
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.
-
Opportunity. It is created optionally, with the contact as primary contact, in the account.
-
Activities. Finished activities move to the contact and keep
ConvertedFromLeadItemId. Open activities move, or are cancelled. -
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
| Interface | Use it to |
|---|---|
ILeadConversionHandler | Run code before (ConvertingAsync) and after (ConvertedAsync) a conversion, for example to copy extra data or notify another system. |
ILeadConversionRepointer | Move records your module keeps against the lead's id to the contact. Messaging, callbacks and voicemail use this. |
ISubjectActionHandler | Add 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.ContentItemis the contact, so content tasks that follow act on the customer.- The input also carries
Lead,LeadContentItemId,ContactContentItemId,AccountContentItemId,OpportunityContentItemIdandContactCreated. - 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.
- The model is given what qualified means: the load's
- On
ConvertLead: true, the lead is converted throughIUnattendedLeadConverterbefore 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:
| Type | Flags | Notes |
|---|---|---|
| Open | neither | Only an open status can be the default (IsDefault). |
| Closed | IsClosed | Activity loads skip it unless a load picks this status. |
| Converted | IsClosed and IsConverted | Set 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):
| Column | Also accepted as | Import |
|---|---|---|
LeadStatus | Status, Lead Status | By status name. |
LeadSource | Source, Lead Source | By lead source name; a name that matches no lead source is ignored. |
LeadList | List, List Name, ListName | The list or import the lead arrived in. |
Company | Company Name, CompanyName, Organization | Free text. |
Rating | Lead Rating | One of the choices of the lead's Rating field, such as Hot, Warm or Cold. |
LeadOwner | Owner, Lead Owner | By user name. |
IsConverted, ConvertedUtc, ConvertedContactItemId | Export only. A converted lead in an import file is left unchanged. | |
LastScrubbedUtc | Export 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
| Permission | Display name | Allows |
|---|---|---|
ConvertLead | Convert leads | Converting a lead. Implied by Manage activities (ManageActivities). |
EditConvertedLead | Edit converted leads | Changing a lead after it was converted. Without it, a converted lead is read-only. |
ManageLeadStatuses | Manage lead statuses | Editing the Lead Status catalog. |
ManageOpportunityStages | Manage opportunity stages | Editing 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.