Xrm.Page.data.process (用戶端參考)

 

發行︰ 2016年11月

適用於： Dynamics CRM 2015

在 Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新，Xrm.Page.data.process 命名空間提供事件、方法和物件，與表單中的商務程序流程資料進行互動。

請參閱 Xrm.Page.ui.process (用戶端參考)，取得與表單中的商務程序流程控制項進行互動之方法。

Xrm.Page.data.process 方法

• ActiveProcess 方法
  使用 getActiveProcess 擷取有關使用中程序之資訊，使用 setActiveProcess 將其他程序設定為使用中程序。

• ActiveStage 方法
  使用 getActiveStage 擷取關於使用中階段的資訊，使用 setActiveStage 將已完成階段設定為使用中階段。

  在 Microsoft Dynamics CRM Online 2015 更新 1 中，您可以使用 setActiveStage 前往不同實體中的某一個階段。

• getActivePath
  使用此方法取得目前在使用中路徑的階段集合，具有與商務程序流程控制項中顯示階段互動的方法。

  使用中路徑表示，根據分支規則和記錄中的目前資料，程序控制項目前轉譯的階段。

• getEnabledProcesses
  使用此方法，以非同步方式擷取實體已啟用的商務程序流程，供使用者切換使用。

• getSelectedStage
  已在 Microsoft Dynamics CRM Online 2015 更新 1 中新增，請使用此方法存取目前選擇的階段。

• 管理事件處理常式的方法
  使用 addOnStageChange、removeOnStageChange、addOnStageSelected 和 removeOnStageSelected 方法新增或移除商務程序流程控制項的事件處理常式。

• 導覽方法
  使用 moveNext 移至下一個階段，使用 movePrevious 移至上一個階段。

  在 Microsoft Dynamics CRM Online 2015 更新 1 中，您可以使用 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 並非有效或程序未啟用。

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 代表無效階段，階段不會成為使用中階段，而且會傳遞指出原因的字串值給回呼函數。 可能傳回下表所列的值。

  值	原因
  crossEntity	階段必須是目前實體的其中一個階段。
  invalid	可能傳回此值有三個原因： stageId 參數是一個不存在的階段識別碼值。 使用中階段不是選定階段 記錄未儲存。
  unreachable	階段在不同的路徑中。
  dirtyForm	如果頁面中的資料未儲存，此值將傳回。

  重要

  在選取的階段和使用中階段相同時，才能使用此方法。 當您的程式碼從 OnStageChange 事件 啟動，會選取目前階段。 當您的程式碼從 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()

• 傳回值
  **類型：**階段

  目前選擇的階段。

• 備註
  此方法已在 Microsoft Dynamics CRM Online 2015 更新 1 中新增。

  如需可以存取所傳回階段的屬性的方法，請參閱 階段方法。

管理事件處理常式的方法

使用這些方法，新增或移除商務程序流程控制項的事件處理常式。

addOnStageChange

使用此方法，新增函數做為 OnStageChange 事件 的事件處理常式，以在商務程序流程階段變更時呼叫。

Xrm.Page.data.process.addOnStageChange(handler);

• 參數
  **類型：**函數參考

  **Remarks:**這個函數會加入至事件處理常式管線底端。 執行內容是自動設定為傳遞至事件處理常式的第一個參數。 如需詳細資訊，請參閱執行內容 (用戶端參考)。

  如果您稍後要移除事件處理常式，應使用具名函數的參照而不是匿名函數。

removeOnStageChange

使用此方法，移除做為 OnStageChange 事件 的事件處理常式的函數。

Xrm.Page.data.process.removeOnStageChange(handler);

• 參數
  **類型：**函數參考

  **Remarks:**如果使用 addOnStageChange 方法設定匿名函數，就無法使用此方法移除它。

addOnStageSelected

使用此方法，新增 OnStageSelected 事件 的事件處理常式，以在商務程序流程階段選取時呼叫。

Xrm.Page.data.process.addOnStageSelected(handler);

• 參數
  **類型：**函數參考

  **Remarks:**這個函數會加入至事件處理常式管線底端。 執行內容是自動設定為傳遞至事件處理常式的第一個參數。 如需詳細資訊，請參閱執行內容 (用戶端參考)。

  如果您稍後要移除事件處理常式，應使用具名函數的參照而不是匿名函數。

removeOnStageSelected

使用此方法，移除做為 OnStageSelected 事件 的事件處理常式的函數。

Xrm.Page.data.process.removeOnStageSelected(function reference);

• 參數
  **類型：**函數參考

  **Remarks:**如果使用 addOnStageSelected 方法設定匿名函數，就無法使用此方法移除它。

導覽方法

使用 moveNext 移至下一個階段，使用 movePrevious 移至上一個階段。 這兩種方法會讓 OnStageChange 事件 發生。

moveNext

前進到下一個階段。

Xrm.Page.data.process.moveNext(callbackFunction);

• 參數
  **類型：**函數

  **備註：**當作業完成時呼叫的選擇性函數。 其中一個字串值傳遞給這個回呼函數，指出作業是否成功。

  值	描述
  成功	作業成功。
  crossEntity	下一個階段屬於不同實體。
  結束	使用中階段是使用中路徑的最終階段。
  無效	作業失敗，因為選取的階段與使用中階段不相同。
  dirtyForm	如果頁面中的資料未儲存，此值將傳回。

重要

在選取的階段和使用中階段相同時，才能使用此方法。 當您的程式碼從 OnStageChange 事件 啟動，會選取目前階段。 當您的程式碼從 OnStageSelected 事件 啟動，應使用 Xrm.Page.data.process.getActiveStage 驗證選取的階段也是使用中階段。 針對其他表單事件，無法決定哪個階段是目前所選取。 為取得最佳結果，此方法應該只用於 OnStageChange 和 OnStageSelected 事件啟動之函數所呼叫的程式碼。

movePrevious

移至上一個階段。 在 Microsoft Dynamics CRM Online 2015 更新 1 中，您可以使用 movePrevious 前往不同實體中的前一個階段。

Xrm.Page.data.process.movePrevious(callbackFunction);

• 參數
  **類型：**函數

  **備註：**當作業完成時呼叫的選擇性函數。 其中一個字串值傳遞給這個回呼函數，指出作業是否成功。

  值	描述
  成功	作業成功。
  crossEntity	上一個階段屬於不同實體。
  開始	使用中階段是使用中路徑的第一個階段。
  無效	作業失敗，因為選取的階段與使用中階段不相同。
  dirtyForm	如果頁面中的資料未儲存，此值將傳回。

重要

在選取的階段和使用中階段相同時，才能使用此方法。 當您的程式碼從 OnStageChange 事件 啟動，會選取目前階段。 當您的程式碼從 OnStageSelected 事件 啟動，應使用 Xrm.Page.data.process.getActiveStage 驗證選取的階段也是使用中階段。 針對其他表單事件，無法決定哪個階段是目前所選取。 為取得最佳結果，此方法應該只用於 OnStageChange 和 OnStageSelected 事件啟動之函數所呼叫的程式碼。

注意

在 Microsoft Dynamics CRM Online 2015 更新 1 中，您可以使用此方法前往不同實體中的某一個階段。

程序方法

程序包含商務程序流程資料。 使用這些方法來存取程序的屬性。

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 CRM 舊版升級，但尚未升級使用新表單，商務程序流程控制項無法呈現。其他資訊：TechNet：將您的表單更新為 Microsoft Dynamics CRM 2013 或 Microsoft Dynamics CRM Online 2013 秋季版

階段方法

階段包含商務程序流程中階段的資料。 使用這些方法來存取階段的屬性。

getCategory

傳回物件，具有會傳回商務程序流程類別的整數值的 getValue 方法。

var stageCategoryNumber = stageObj.getCategory().getValue();

• 傳回值
  類型：Number

  **備註：**如需可能值的清單，請參閱 階段類別 (processstage_category)。

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 屬性 RequiredLevel 方法可以變更的值之間沒有關聯。

另請參閱

為商務程序流程撰寫指令碼
Xrm.Page.ui.process (用戶端參考)
用戶端程式設計參考
表單指令碼快速參考
撰寫 Microsoft Dynamics CRM 2015 表單的程式碼
使用 Xrm.Page 物件模型
範例：Xrm.Page.data.process.getEnabledProcesses
範例：Xrm.Page.data.process.getActivePath

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權