使用程式碼處理商務程序流程
「商務程序流程」(Business Process Flow) 可讓您建立更有效率且更流暢的銷售、服務及其他商務程序。 它藉由將特殊控制項放在資料表表單頂端,來為商務程序建立視覺效果。 使用者將經由引導進行各個不同階段的銷售、行銷或服務程序,直到完成。 每個程序都支援多個階段和步驟。 您可以新增或移除步驟、變更階段的順序,或是將新的資料表新增至商務程序流程。
不同的商務程序流程執行個體可以針對相同的資料表資料列同時執行。 使用者可以在並行的商務程序執行個體之間切換,並且在程序中於目前階段恢復其工作。
本主題提供如何以程式設計方式處理商務程序流程的資訊。
Note
您不必撰寫代碼來處理商務程序流程。 如需使用 UI 來建立及管理商務程序流程的資訊,請參閱 商務程序流程概觀
商務程序流程的必要條件
自訂資料表及已更新 UI 表單的資料表可以參與商務程序流程。 已更新的 UI 資料表會將 IsAIRUpdated 屬性設定為 true
。
若要啟用商務程序流程的資料表,請將 IsBusinessProcessEnabled 屬性設定為 true
。
Important
啟用商務程序流程的資料表是一個單向程序。 該程序無法反向。
定義商務程序流程
您可以使用視覺化商務程序流程設計工具來定義商務程序流程。 詳細資訊:建立商務程序流程
根據預設,商務程序流程資料列是以 Draft
狀態建立。
商務程序流程定義會儲存在 workflow 資料表中,而商務程序流程的階段資訊會儲存在 processstage 資料表中。
啟用商務程序流程
使用程序流程之前,必須先將它啟用。 若要啟用,您必須具有 Workflow
資料表的 prvActivateBusinessProcessFlow
權限。 使用 UpdateRequest 訊息將 Workflow
資料表資料列的狀態設定為 Activated
。 其他資訊:使用更新執行特殊化作業
Note
您也可以使用商務程序流程設計工具來啟用商務程序流程。
商務程序流程資料表
一旦您藉由變更對應 Workflow
資料表資料列的狀態或使用商務程序流程設計工具來啟用商務程序流程定義,系統會自動使用下列名稱來建立自訂資料表,以便儲存所啟用的商務程序流程執行個體:<activesolutionprefix> _ <uniquename>,其中 uniquename 會衍生自您指定的名稱。
例如,如果您指定了 "My Custom BPF" 作為商務程序流程定義的名稱,並想要使用預設發行者 (new) 作為使用中解決方案,則為儲存程序執行個體所建立的自訂資料表名稱會是 "new_mycustombpf"。
如果 uniquename
值不適用於商務程序流程定義;例如,如果匯入的商務程序流程是舊版解決方案的一部分,則自訂資料表的預設名稱會是 "\<activesolutionprefix>_bpf_<GUID_BPF_Definition>
:
Important
範例商務程序流程資料列使用系統資料表來儲存對應的商務程序流程執行個體資料列。
不過,您所建立的任何新商務程序流程定義會使用自訂資料表來儲存其執行個體資料列,如先前所述。
您可以使用下列任何方式來擷取商務程序流程資料表的名稱:
使用 UI:使用自訂 UI,以瀏覽至您的商務程序流程資料表:
使用 Web API:使用下列要求:
要求
GET [Organization URI]/api/data/v9.0/workflows?$filter=name eq 'My Custom BPF'&$select=uniquename HTTP/1.1
回應
{ "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#workflows(uniquename)", "value":[ { "@odata.etag":"W/\"1084677\"", "uniquename":"new_mycustombpf", "workflowid":"2669927e-8ad6-4f95-8a9a-f1008af6956f" } ] }
使用組織服務:使用下列代碼範例:
QueryExpression query = new QueryExpression { EntityName = "workflow", ColumnSet = new ColumnSet("uniquename"), Criteria = new FilterExpression { Conditions = { new ConditionExpression { ColumnName = "name", Operator = ConditionOperator.Equal, Values = { "My Custom BPF" } } } } }; Workflow Bpf = (Workflow)_serviceProxy.RetrieveMultiple(query).Entities[0];
Note
商務程序流程資料表的 IsBPFEntity 屬性為 true
。 您可以藉由執行下列 Web API 要求,擷取執行個體中的所有商務程序流程資料表:
GET [Organization URI]/api/data/v9.0/EntityDefinitions?$select=SchemaName,LogicalName,DisplayName&$filter=IsBPFEntity eq true HTTP/1.1
管理商務程序流程安全性
在啟動商務程序流程時自動建立以儲存商務程序流程執行個體的自訂資料表會遵循標準安全性模型,就如同 Microsoft Dataverse 中的其他任何自訂資料表。 這意味著在這些資料表上授予的權限會定義商務程序流程使用者的執行階段權限。
自訂商務程序流程資料表的範圍是組織。 此資料表上的一般建立、擷取、更新及刪除權限會依據使用者獲指派的角色定義其權限。 根據預設,當商務程序流程自訂資料表建立時,只會授予 系統管理員 和 系統自訂員 安全性角色加以存取的權限,如有必要,您必須為其他安全性角色明確授予新商務程序流程資料表 (例如 我的自訂 BPF) 的權限。
建立、擷取、更新及刪除商務程序流程資料表資料列 (程序執行個體)
在啟動商務程序流程定義時自動建立的自訂資料表,會儲存商務程序流程定義的所有程序執行個體。 自訂資料表支援使用 Web API 和 CRM 2011 端點進行資料列 (程序執行個體) 的標準程式設計建立與管理。
Important
您只能透過 UI (用戶端) 或以程式設計方式使用本章節中的資訊,切換到資料表資料列的另一個程序執行個體。 您無法再使用 SetProcess
訊息 (SetProcess Action 或 SetProcessRequest),以程式設計方式為目標資料表資料列切換程序 (將另一個商務程序流程設為使用中的程序執行個體)。
讓我們考量下列範例:有一個跨資料表商務程序流程 "My Custom BPF",其中具有 3 個階段:S1:Account、S2:Account 與 S3:Contact。
擷取商務程序流程資料表的所有資料列 (執行個體)
如果您的商務程序流程資料表名稱為 "new_mycustombpf",請使用下列查詢擷取商務程序流程資料表的所有資料列 (程序執行個體):
GET [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1
此時,您可能無法在回應中取得任何執行個體,因為沒有任何執行個體。 本主題稍後將建立您的商務程序流程定義執行個體,請於之後再執行此要求。
Note
若要了解如何擷取您商務程序流程資料表的名稱,請參閱先前的章節:商務程序流程資料表。
建立商務程序流程資料表資料列 (程序執行個體)
如果您想要切換至資料表資料列的另一個商務程序流程而不使用 UI,請以程式設計方式建立商務程序流程資料表資料列 (程序執行個體)。
若要建立商務程序流程資料表資料列,您必須指定下列值:
藉由使用
@odata.bind
註釋設定單一值導覽屬性,來將商務程序流程資料表資料列關聯到主要資料表資料列。 若要找出指向您商務程序流程定義之主要資料表資料列的導覽屬性名稱,請使用 CSDL $metadata 文件。藉由使用
@odata.bind
註釋設定單一值導覽屬性,來將商務程序流程資料表資料列關聯到商務程序流程定義中指定的有效階段。 若要找出指向您商務程序流程定義之階段資料列的導覽屬性名稱 (通常是activestageid
),請使用 CSDL $metadata 文件。此外,您可以使用下列 Web API 要求,來擷取商務程序流程定義中所有階段的資訊,其中假設您的商務程序流程定義識別碼為 2669927e-8ad6-4f95-8a9a-f1008af6956f:
要求
GET [Organization URI]/api/data/v9.0/processstages?$select=stagename&$filter=processid/workflowid eq 2669927e-8ad6-4f95-8a9a-f1008af6956f HTTP/1.1
回應
{ "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#processstages(stagename)", "value": [ { "@odata.etag": "W/\"858240\"", "stagename": "S1", "processstageid": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b" }, { "@odata.etag": "W/\"858239\"", "stagename": "S3", "processstageid": "a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a" }, { "@odata.etag": "W/\"858238\"", "stagename": "S2", "processstageid": "19a11fc0-3398-4214-8522-cb2a97f66e4b" } ] }
接下來,使用下列要求建立您的商務程序流程定義執行個體,表示帳戶資料列 (ID=a176be9e-9a68-e711-80e7-00155d41e206),並將使用中階段設定為程序執行個體的第一個階段 S1 (ID=9a9185f5-b75b-4bbb-9c2b-a6626683b99b):
要求
POST [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
"bpf_accountid@odata.bind": "/accounts(a176be9e-9a68-e711-80e7-00155d41e206)",
"activestageid@odata.bind": "/processstages(9a9185f5-b75b-4bbb-9c2b-a6626683b99b)"
}
回應
HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/new_mycustombpfs(cc3f721b-026e-e811-80ff-00155d513100)
請注意,如果您想要建立商務程序流程定義執行個體,並將使用中階段設定為第一個階段以外的 其他 階段,您也必須在要求中提供 traversedpath
。 周遊的路徑是以逗點分隔的程序階段識別碼字串,代表瀏覽過的商務程序流程執行個體階段。 下列要求會建立客戶資料列的執行個體 (ID=679b2464-71b5-e711-80f5-00155d513100) 以及設定為第二階段 S2 的使用中階段 (ID=19a11fc0-3398-4214-8522-cb2a97f66e4b)。
POST [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
"bpf_accountid@odata.bind": "/accounts(679b2464-71b5-e711-80f5-00155d513100)",
"activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
"traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"
}
更新商務程序流程資料表資料列 (程序執行個體)
您可以更新程序執行個體來移至下一個或上一個階段、放棄程序執行個體、重新啟用程序執行個體或完成程序執行個體。
階段導覽
若要巡覽至不同的階段,您必須更新程序執行個體資料列,以變更其使用中階段識別碼,並據以更新周遊的路徑。 請注意,您只能在更新商務程序流程執行個體期間,移至下一個或上一個階段。
若要執行階段導覽,您需要所要更新之商務程序流程執行個體的識別碼。 若要擷取您商務程序流程的所有執行個體,請參閱稍早的 擷取商務程序流程資料表的所有資料列 (執行個體)。
假設您想要更新的程序執行個體識別碼為 dc2ab599-306d-e811-80ff-00155d513100,請使用下列要求將使用中階段從 S1 更新為 S2:
PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
{
"activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
"traversedpath": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"
}
變更程序執行個體的狀態:中止、重新啟用或完成
程序執行個體可以是下列其中一個狀態:使用中、已完成 或 已中止。 該狀態取決於程序執行個體資料列中的下列資料行:
statecode:顯示程序執行個體的狀態。
值 Label 0 作用中 1 非作用中 statuscode:顯示程序執行個體狀態的相關資訊。
值 Label 1 作用中 2 已完成 3 已中止
因此,若要 中止 程序執行個體,請使用下列要求適當地設定 statecode
和 statuscode
值:
PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
{
"statecode" : "1",
"statuscode": "3"
}
Note
您可以在任何階段中止程序執行個體。
同樣地,若要重新啟用程序執行個體,請將上述代碼中的 statecode
和 statuscode
值分別取代為 0 和 1。
最後,若要將程序執行個體狀態設定為 已完成 (只可能發生在程序執行個體的最後一個階段),請將上述程式碼中的 statecode
和 statuscode
值分別取代為 0 和 2。
跨資料表導覽
若要進行此範例中的跨資料表導覽,您必須將程序執行個體的使用中階段設定為最後一個階段 S3 (ID=a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a)、據以更新周遊的路徑,並根據商務程序流程定義將連絡人資料列設定為主要資料表資料列。
PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
{
"activestageid@odata.bind": "/processstages(a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a)",
"traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b,a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a",
"bpf_contactid@odata.bind": "/contacts(0e3f10b0-da33-e811-80fc-00155d513100)"
}
刪除商務程序流程資料表資料列 (程序執行個體)
使用下列 Web API 要求:
要求
DELETE [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1
回應
如果資料列存在,您會得到狀態為 204 的正常回應,表示刪除已成功。 如果找不到資料表,您會得到狀態為 404 的回應。
使用 RetrieveProcessInstances 和 RetrieveActivePath 訊息
使用 RetrieveProcessInstances
訊息 (RetrieveActivePath Function 或 RetrieveProcessInstancesRequest),針對跨所有商務程序定義的資料表資料列,擷取其所有的商務程序流程執行個體。 針對資料表所傳回的商務程序流程執行個體會依據執行個體的 modifiedon
資料行排序。 例如,最近修改的商務程序流程執行個體會是傳回集合中的 第一個 資料列。 最近修改之商務程序流程執行個體是 UI 上代表資料表資料列的使用中執行個體。
使用 RetrieveProcessInstances
訊息之後會針對資料表資料列傳回每個商務程序流程執行個體資料列,這些記錄將使用中階段的識別碼儲存在 processstageid
資料行中,以用來尋找使用中階段,然後移至上一個或下一個階段。 若要這樣做,您必須先使用 RetrieveActivePath
訊息 (RetrieveActivePath Function 或 RetrieveActivePathRequest) 尋找商務程序流程執行個體的使用中路徑,以及程序流程執行個體中可用的階段。
一旦您擁有商務程序流程執行個體的使用中階段和使用中路徑資訊,就可以使用該資訊移至使用中路徑的上一個或下一個階段。 向前瀏覽階段必須依序完成,也就是說,您應該只向前移至使用中路徑的下一個階段。
如需示範如何使用這兩種方法和使用組織服務之階段導覽的完整範例代碼,請參閱 範例:處理商務程序流程。
建立資料表資料列時套用商務程序流程
本節提供自動將商務程序流程套用至 Dataverse 中建立的新資料表資料列預設行為,以及如何加以覆寫來套用您所選新資料表資料列之商務程序流程的資訊。
根據預設,針對已定義多個商務程序流程的資料表,系統會使用下列多步驟邏輯,將商務程序流程套用至新的資料表資料列:
- 根據商務程序流程定義資料列的 Workflow.PrimaryEntity 屬性,識別適用於新資料表資料列的所有商務程序流程。
- 識別目前使用者可以存取的商務程序流程定義。 如需如何判斷及管理商務程序流程存取權的資訊,請參閱本主題稍早的 管理商務程序流程的安全性。
- 系統中的所有商務程序流程定義受都限於每個資料表的全域順序。 商務程序流程的順序會儲存在 Workflow.ProcessOrder 資料行中。 資料表的商務程序流程定義會依此順序排序,然後從中挑選具有最低順序值的定義。
- 最後,如果資料表資料列是從商務應用程式 (應用程式模組) 建立而來,則會多套用一層篩選,以挑選要自動套用至新資料表資料列的商務程序流程。 使用應用程式時,使用者只能存取透過指派給商務應用程式的資訊安全角色獲得其存取權的相關資料表、商務程序流程、檢視表和表單。
- 如果商務應用程式不含任何商務程序流程,則會依照直到步驟 3 前所述的方式套用商務程序流程。
- 如果商務應用程式有一個或多個商務程序流程,則只有應用程式中存在的商務程序流程才適用。 在這種情況下,當使用者在商務應用程式環境中工作時,會進一步將步驟 3 的商務程序流程清單篩選成屬於商務應用程式一部分、存在於應用程式模組內且依程序順序排序的商務程序流程。
- 如果資料表的商務應用程式或使用者有權存取的商務應用程式中沒有商務程序流程,則不會對新的資料表資料列套用商務程序流程。
您可以覆寫自動套用至新資料表資料列之商務程序流程的預設邏輯。 若要這樣做,請在建立新的資料表資料列時,將資料表的 ProcessId 資料行設定為下列其中一個值:
- 設定為 Guid.Empty,以略過設定新資料表資料列的商務程序流程。 如果您要大量建立資料表資料列,但不希望套用商務程序流程,您可能會想要這麼做。
- 將它設定為特定商務程序流程資料表 (作為資料表參考)。 在這種情況下,系統將會套用指定的商務程序流程,而不是預設邏輯。
如果您在建立新資料表資料列時未設定 ProcessId 資料行的值,系統會如先前所述套用預設邏輯。
Note
僅支援以程式設計方式來覆寫自動套用至新資料表資料列之商務程序流程的預設邏輯。 無法使用 UI 執行這個工作。
資料表中的舊版程序相關資料行
資料表上針對商務程序流程啟用的舊版程序相關資料行 (例如 ProcessId、StageId 和 TraversedPath) 已淘汰。 操作目標資料表資料列的這些舊版程序相關資料行無法保證商務程序流程狀態的一致性,而且 不是 支援的案例。 建議使用商務程序流程資料表的資料行,如稍早建立、擷取、更新及刪除商務程序流程資料表資料列 (程序執行個體)一節中所述
唯一的例外是在建立實體記錄時以程式設計方式修改 ProcessId 資料行,這會覆寫商務程序流程對新資料列的預設應用,如上一節建立資料表資料列時套用商務程序流程中所述。
用戶端對商務程序流程的程式設計功能支援
您可以使用用戶端物件,來與表單指令碼中的商務程序流程互動。 商務程序流程會在每次將程序套用至資料列、變更階段,或是其狀態變更為 Active
、Finished
或 Aborted
時,觸發用戶端事件。 詳細資訊:formContext.data.process (用戶端 API 參考)
程序、階段和步驟的數目上限。
每個資料表的已啟動商務程序流程的最大數目預設值為 10。 您可以使用 Organization.MaximumActiveBusinessProcessFlowsAllowedPerEntity
資料行來指定不同的值。 不過,如果值大於 10,當您切換程序或開啟已指派商務程序流程的資料列時,您可能會看到系統的效能降低。 如果程序跨越多個資料表,此情況可能會特別明顯。
下列設定無法自訂:
程序中每個資料表的階段數目上限為 30。
每個階段中的步驟數目上限為 30。
可參與程序流程的資料表數目上限為 5。
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應