Xrm.Page.data.process (用戶端參考)
發行︰ 2017年1月
適用於: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online
Xrm.Page.data.process 命名空間提供事件、方法和物件,與表單中的商務程序流程資料進行互動。
請參閱 Xrm.Page.ui.process (用戶端參考),取得與表單中的商務程序流程控制項進行互動之方法。
Xrm.Page.data.process 方法
ActiveProcess 方法
使用 getActiveProcess 擷取有關使用中程序之資訊,使用 setActiveProcess 將其他程序設定為使用中程序。ProcessInstance 方法
使用 getProcessInstances 擷取實體記錄的所有程序執行個體的相關記錄,以及使用 setActiveProcessInstance 將程序執行個體設定為使用中執行個體。ActiveStage 方法
使用 getActiveStage 擷取關於使用中階段的資訊,使用 setActiveStage 將已完成階段設定為使用中階段。您可以使用 setActiveStage 前往不同實體中的某一個階段。
getActivePath
使用此方法取得目前在使用中路徑的階段集合,具有與商務程序流程控制項中顯示階段互動的方法。使用中路徑表示,根據分支規則和記錄中的目前資料,程序控制項目前轉譯的階段。
getEnabledProcesses
使用此方法,以非同步方式擷取實體已啟用的商務程序流程,供使用者切換使用。getSelectedStage
使用此方法存取目前選取的階段。管理事件處理常式的方法
使用 addOnStageChange、removeOnStageChange、addOnStageSelected、removeOnStageSelected、addOnProcessStatusChange 和 removeOnProcessStatusChange 方法新增或移除商務程序流程控制項的事件處理常式。導覽方法
使用 moveNext 移至下一個階段,使用 movePrevious 移至上一個階段。您可以使用 movePrevious 前往不同實體中的前一個階段。
程序方法
使用程序方法來存取程序的屬性。執行個體方法
使用程序執行個體方法存取目前程序執行個體的屬性。階段方法
使用階段方法來存取商務程序流程中階段的屬性。步驟方法
使用步驟方法來存取商務程序流程中階段步驟的屬性。
ActiveProcess 方法
使用 getActiveProcess 擷取有關使用中程序之資訊,使用 setActiveProcess 將其他程序設定為使用中程序。
getActiveProcess
傳回 Process 物件,表示使用中程序。
var activeProcess = Xrm.Page.data.process.getActiveProcess();
傳回值
類型: 程序備註: 如需可以存取所傳回程序的屬性的方法,請參閱 程序方法。
setActiveProcess
將 Process 設為使用中程序。
如果程序有使用中執行個體,實體記錄就會透過執行個體識別碼載入。 如果目前程序沒有使用中執行個體,新的程序執行個體就會建立,且實體記錄會透過執行個體識別碼載入。 如果目前程序有多個執行個體,則會依照預設邏輯載入記錄與使用中程序的第一個執行個體,也就是每位使用者最近使用的程序執行個體。
Xrm.Page.data.process.setActiveProcess(processId, callbackFunction);
參數:
processId
類型:String備註: 成為使用中程序之程序的識別碼。
callbackFunction
類型:Function備註: 當作業完成時呼叫的函數。 其中一個字串值傳遞給這個回呼函數,指出作業是否成功。
值
描述
成功
作業成功。
無效
processId 並非有效或程序未啟用。
ProcessInstance 方法
使用 getProcessInstances 擷取實體記錄的所有程序執行個體的相關記錄,以及使用 setActiveProcessInstance 將程序執行個體設定為使用中執行個體。
注意
這些方法在 Dynamics 365 (Online 和內部部署) 的 2016 年 12 月更新 中推出。
getProcessInstances
傳回呼叫端使用者可存取的記錄實體的所有程序執行個體。
Xrm.Page.data.process.getProcessInstances(callbackFunction(object));
參數
類型:Function備註: 回呼函數會在物件上傳遞,且下列屬性和其對應的值為索引鍵:值配對。
CreatedOn
ProcessDefinitionID
ProcessDefinitionName
ProcessInstanceID
ProcessInstanceName
StatusCodeName
程序執行個體是根據使用者的權限篩選。
setActiveProcessInstance
將程序執行個體設為使用中執行個體。
Xrm.Page.data.process.setActiveProcessInstance(processInstanceId, callbackFunction);
參數:
processInstanceId
類型:String備註: 要設為使用中執行個體的程序執行個體識別碼。
callbackFunction
類型:Function備註: 當作業完成時呼叫的函數。 其中一個字串值傳遞給這個回呼函數,指出作業是否成功。
值
描述
成功
作業成功。
無效
processInstanceId 並非有效或程序未啟用。
ActiveStage 方法
使用 getActiveStage 擷取關於使用中階段的資訊,使用 setActiveStage 將不同階段設定為使用中階段。
getActiveStage
傳回 Stage 物件,表示使用中階段
var activeStage = Xrm.Page.data.process.getActiveStage();
傳回值
類型: 階段備註: 如需可以存取所傳回階段的屬性的方法,請參閱 階段方法。
setActiveStage
將已完成階段設為使用中階段。
注意
從 Microsoft Dynamics CRM Online 2015 更新 1 之後,您可以使用此方法在不同實體中設定階段。
只有實體的已完成階段才能使用此方法設定。
Xrm.Page.data.process.setActiveStage(stageId, callbackFunction);
參數:
stageId
類型:String備註: 要成為使用中階段的實體已完成階段的識別碼。
callbackFunction
類型:Function備註: 當作業完成時呼叫的選擇性函數。
如果作業順利完成,就會傳遞字串值「success」給回呼函數。
如果 stageId 代表無效階段,階段不會成為使用中階段,而且會傳遞指出原因的字串值給回呼函數。 可能傳回下表所列的值。
值
原因
invalid
可能傳回此值有三個原因:
stageId 參數是一個不存在的階段識別碼值。
使用中階段不是選定階段
記錄未儲存。
unreachable
階段在不同的路徑中。
dirtyForm
如果頁面中的資料未儲存,此值將傳回。
重要
在選取的階段和使用中階段相同時,才能使用此方法。 當您的程式碼從 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange 啟動,會選取目前階段。 當您的程式碼從 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected 啟動,應使用 Xrm.Page.data.process.getActiveStage 驗證選取的階段也是使用中階段。 針對其他表單事件,無法決定哪個階段是目前所選取。 為取得最佳結果,此方法應該只用於 OnStageChange 和 OnStageSelected 事件啟動之函數所呼叫的程式碼。
getActivePath
使用此方法取得目前在使用中路徑的階段集合,具有與商務程序流程控制項中顯示階段互動的方法。
使用中路徑表示,根據分支規則和記錄中的目前資料,程序控制項目前轉譯的階段。
var stageCollection = Xrm.Page.data.process.getActivePath();
範例:
如需使用此方法的範例,請參閱 範例:Xrm.Page.data.process.getActivePath。
傳回值
類型: 集合Remarks: 所有已完成階段、目前使用中階段,和根據分支規則滿足的條件,一組預測的未來階段之集合。 這可能是隨 Xrm.Page.data.process.getActiveProcess 一起傳回的階段的子集,因為它只納入依據程序中已發生的分支,代表從目前階段有效轉換的這些階段。
getEnabledProcesses
使用此方法,以非同步方式擷取實體已啟用的商務程序流程,供使用者切換使用。
Xrm.Page.data.process.getEnabledProcesses(callbackFunction(enabledProcesses));
參數
類型:Function備註: 回呼函數必須接受參數,包含有字典屬性的物件,其中屬性名稱是商務程序流程的 Id,而屬性的值是商務程序流程的名稱。
啟用的程序是根據使用者的權限篩選。 啟用的程序清單是使用者可以在 UI 看到相同的部分,若想手動變更程序。
範例:
如需使用此方法的範例,請參閱 範例:Xrm.Page.data.process.getEnabledProcesses。
getSelectedStage
使用此方法取得目前選擇的階段。
Xrm.Page.data.process.getSelectedStage()
傳回值
類型: 階段目前選擇的階段。
- 備註
如需可以存取所傳回階段的屬性的方法,請參閱 階段方法。
管理事件處理常式的方法
使用這些方法,新增或移除商務程序流程控制項的事件處理常式。
addOnStageChange
使用此方法,新增函數做為 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange 的事件處理常式,以在商務程序流程階段變更時呼叫。
Xrm.Page.data.process.addOnStageChange(handler);
參數
類型: 函數參考Remarks: 這個函數會加入至事件處理常式管線底端。 執行內容是自動設定為傳遞至事件處理常式的第一個參數。 如需詳細資訊,請參閱執行內容 (用戶端參考)。
如果您稍後要移除事件處理常式,應使用具名函數的參照而不是匿名函數。
removeOnStageChange
使用此方法,移除做為 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange 的事件處理常式的函數。
Xrm.Page.data.process.removeOnStageChange(handler);
參數
類型: 函數參考Remarks: 如果使用 addOnStageChange 方法設定匿名函數,就無法使用此方法移除它。
addOnStageSelected
使用此方法,新增 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected 的事件處理常式,以在商務程序流程階段選取時呼叫。
Xrm.Page.data.process.addOnStageSelected(handler);
參數
類型: 函數參考Remarks: 這個函數會加入至事件處理常式管線底端。 執行內容是自動設定為傳遞至事件處理常式的第一個參數。 如需詳細資訊,請參閱執行內容 (用戶端參考)。
如果您稍後要移除事件處理常式,應使用具名函數的參照而不是匿名函數。
removeOnStageSelected
使用此方法,移除做為 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected 的事件處理常式的函數。
Xrm.Page.data.process.removeOnStageSelected(function reference);
參數
類型: 函數參考Remarks:如果使用 addOnStageSelected 方法設定匿名函數,就無法使用此方法移除它。
addOnProcessStatusChange
使用此方法,新增函數做為 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnProcessStatusChange 事件的事件處理常式,以在商務程序流程狀態變更時呼叫。
Xrm.Page.data.process.addOnProcessStatusChange(handler);
參數
類型: 函數參考Remarks: 這個函數會加入至事件處理常式管線底端。 執行內容是自動設定為傳遞至事件處理常式的第一個參數。 如需詳細資訊,請參閱執行內容 (用戶端參考)。
如果您稍後要移除事件處理常式,應使用具名函數的參照而不是匿名函數。
此方法已在 Dynamics 365 (Online 和內部部署) 的 2016 年 12 月更新 中引進。
removeOnProcessStatusChange
使用此方法,移除做為 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnProcessStatusChange 事件的事件處理常式的函數。
Xrm.Page.data.process.removeOnProcessStatusChange(handler);
參數
類型: 函數參考Remarks: 如果使用 addOnProcessStatusChange 方法設定匿名函數,就無法使用此方法移除它。
此方法已在 Dynamics 365 (Online 和內部部署) 的 2016 年 12 月更新 中引進。
導覽方法
使用 moveNext 移至下一個階段,使用 movePrevious 移至上一個階段。 這兩種方法會讓 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange 發生。
moveNext
前進到下一個階段。
Xrm.Page.data.process.moveNext(callbackFunction);
參數
類型: 函數備註: 當作業完成時呼叫的選擇性函數。 其中一個字串值傳遞給這個回呼函數,指出作業是否成功。
值
描述
成功
作業成功。
crossEntity
下一個階段屬於不同實體。
結束
使用中階段是使用中路徑的最終階段。
無效
作業失敗,因為選取的階段與使用中階段不相同。
dirtyForm
如果頁面中的資料未儲存,此值將傳回。
重要
在選取的階段和使用中階段相同時,才能使用此方法。 當您的程式碼從 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange 啟動,會選取目前階段。 當您的程式碼從 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected 啟動,應使用 Xrm.Page.data.process.getActiveStage 驗證選取的階段也是使用中階段。 針對其他表單事件,無法決定哪個階段是目前所選取。 為取得最佳結果,此方法應該只用於 OnStageChange 和 OnStageSelected 事件啟動之函數所呼叫的程式碼。
movePrevious
移至上一個階段。 您可以使用 movePrevious 前往不同實體中的前一個階段。
Xrm.Page.data.process.movePrevious(callbackFunction);
參數
類型: 函數備註: 當作業完成時呼叫的選擇性函數。 其中一個字串值傳遞給這個回呼函數,指出作業是否成功。
值
描述
成功
作業成功。
crossEntity
上一個階段屬於不同實體。
開始
使用中階段是使用中路徑的第一個階段。
無效
作業失敗,因為選取的階段與使用中階段不相同。
dirtyForm
如果頁面中的資料未儲存,此值將傳回。
重要
在選取的階段和使用中階段相同時,才能使用此方法。 當您的程式碼從 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange 啟動,會選取目前階段。 當您的程式碼從 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected 啟動,應使用 Xrm.Page.data.process.getActiveStage 驗證選取的階段也是使用中階段。 針對其他表單事件,無法決定哪個階段是目前所選取。 為取得最佳結果,此方法應該只用於 OnStageChange 和 OnStageSelected 事件啟動之函數所呼叫的程式碼。
注意
您可以使用此方法前往不同實體中的某一個階段。
程序方法
程序包含商務程序流程資料。 使用這些方法來存取程序的屬性。
getId
傳回程序的唯一識別碼
var processId = procObj.getId();
傳回值
類型:String備註: 值代表 GUID 值的字串表示。
getName
傳回程序的名稱
var processName = procObj.getName();
- 傳回值
類型:String
getStages
傳回程序中階段的集合
var stageCollection = procObj.getStages();
傳回值
類型: 集合如需可以存取所傳回階段的屬性的方法,請參閱 階段方法。
isRendered
如果程序已呈現則傳回 true,否則為 false
var processRendered = procObj.isRendered();
傳回值
類型:Boolean備註: 如果使用的表單已經從 Microsoft Dynamics 365 舊版升級,但尚未升級使用新表單,商務程序流程控制項無法呈現。其他資訊:TechNet:將您的表單更新為 Microsoft Dynamics CRM 2013 或 Microsoft Dynamics CRM Online 2013 秋季版
執行個體方法
程序執行個體包含商務程序流程執行個體的資料。 使用這些方法來存取程序執行個體的屬性。
注意
執行個體方法已在 Dynamics 365 (Online 和內部部署) 的 2016 年 12 月更新 中推出。
getInstanceId
傳回程序執行個體的唯一識別碼。
Xrm.Page.data.process.getInstanceId();
傳回值
類型:String備註: 值代表 GUID 值的字串表示。
getInstanceName
傳回程序執行個體的名稱。
Xrm.Page.data.process.getInstanceName();
- 傳回值
類型:String
getStatus
傳回程序執行個體的目前狀態。
Xrm.Page.data.process.getStatus();
傳回值
類型:String備註: 此方法會傳回下列其中一個值:active、aborted 或 finished。
setStatus
設定使用中程序執行個體的目前狀態。
Xrm.Page.data.process.setStatus(status, callbackFunction);
參數:
status
類型:String備註: 值可以是 active、aborted 或 finished。
callbackFunction
類型:Function備註: 當作業完成時呼叫的選擇性函數。 此回呼函數會收到傳遞的新狀態做為字串值。
階段方法
階段包含商務程序流程中階段的資料。 使用這些方法來存取階段的屬性。
getCategory
傳回物件,具有會傳回商務程序流程類別的整數值的 getValue 方法。
var stageCategoryNumber = stageObj.getCategory().getValue();
傳回值
類型:Number備註: 如需可能值的清單,請參閱 afe17a4a-fdca-44b4-8c14-a19ba327662e#BKMK_StageCategory。
getEntityName
傳回階段相關實體的邏輯名稱。
var stageEntityName = stageObj.getEntityName();
- 傳回值
類型:String
getId
傳回階段的唯一識別碼
var stageId = stageObj.getId();
- 傳回值
類型:String
getName
傳回階段的名稱
var stageName = stageObj.getName();
- 傳回值
類型:String
getStatus
傳回階段的狀態
var stageStatus = stageObj.getStatus();
傳回值
類型:String備註: 此方法傳回 active 或 inactive。
getSteps
傳回階段中步驟的集合。
var stepsCollection = stageObj.getSteps();
傳回值
類型:Array如需可以存取步驟的屬性值的方法,請參閱 步驟方法。
步驟方法
步驟包含商務程序流程中階段步驟的資料。 使用這些方法來存取步驟的屬性。
getAttribute
傳回步驟相關屬性的邏輯名稱。
var stepAttributeName = stepObj.getAttribute();
傳回值
類型:String備註: 某些步驟不包含屬性值。
getName
傳回步驟的名稱。
var stepName = stepObj.getName();
- 傳回值
類型:String
isRequired
傳回步驟是否在商務程序流程中為必要項。
var stepIsRequired = stepObj.isRequired();
傳回值
類型:Boolean備註: 如果在商務程序流程編輯器中步驟標記為必要,則傳回 true,否則為 false。 此值與您在 Xrm.Page.data.entity 屬性 6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_RequiredLevel 方法可以變更的值之間沒有關聯。
另請參閱
為商務程序流程撰寫指令碼
Xrm.Page.ui.process (用戶端參考)
用戶端程式設計參考
表單指令碼快速參考
撰寫 Microsoft Dynamics 365 表單的程式碼
使用 Xrm.Page 物件模型
範例:Xrm.Page.data.process.getEnabledProcesses
範例:Xrm.Page.data.process.getActivePath
Microsoft Dynamics 365
© 2017 Microsoft. 著作權所有,並保留一切權利。 著作權