僅為 提供

Enterprise 帳戶管理員可以針對企業需求建立自訂的發行與淘汰工作流程。Onshape 為您提供我們自己的發行與淘汰工作流程的 JSON 檔案，可做為您自訂符合公司需求工作流程的起步。您也可以使用我們的 JSON 來做為建立您自己 JSON 檔案的起點。

提醒您，目前選取的發行與淘汰工作流程 (管理員所選的) 會掌管藉由所選流程新建立的發行候選。如果您在發行的過程中變更了工作流程，則該發行會根據發行建立時的工作流程進行。新選取的工作流程只會掌管選擇之後建立的發行候選。

還有一件事要提醒您：Onshape 自訂工作流程不允許循環的過程。

您可以解除發佈一個工作流程，將其從作用中的工作流程清單中移除。

您可以加入任意數量的工作流程到流程集合中以供選擇。如果需要，您也可以取代現有的自訂工作流程。

建議您將工作流程的定義檔案保存在一個 Onshape 文件中以便存取。

自訂的過程中有三個主要的步驟，分別詳細說明如下：

  1. 將 Onshape 預設工作流程下載至您的硬碟或其他便於存取之處。
  2. 建立新的 Onshape 文件與匯入工作流程檔案。
  3. 選擇性使用 FeatureScript 來自訂工作流程以於某些發行動作中更新項目屬性。
  4. 編輯與發佈工作流程。
  5. 選擇性地偵錯自訂工作流程。

當您設定包含兩層的自訂工作流程，且第二層不是必須的情況下 (意即第二層是選擇性使用的)，如果在發行套件中沒有指定核准者，Onshape 會自動從「待決中」轉換至「已發行」。您不需要為此設定任何項目，唯一的要求是使用兩層的工作流程，第二層是選用的，然後在發行候選的「核准者」欄位中沒有指定任何核准者。

下載 Onshape 預設工作流程檔案：

  1. 導覽至您的Enterprise 設定，然後選擇發行管理。
  2. Confirm that Enable managed workflows is checked, then click View in document.

    發行工作流程，在文件中檢視

    會在公開文件內的另一個分頁上開啟工作流程檔案。

  3. Click Download, enter a new name for the file.

    在下載分頁之後，您可以關閉該分頁。

  1. In your enterprise, navigate to the Documents page, select Create > Document, then select OK. (In this example, the document name is Company Customized Workflows)
  2. In the new document, click the Plus icon 加號圖示 at the bottom and select Import:

在功能表中強調顯示了 [匯入]

  1. 選擇您剛下載的工作流程檔案，然後按一下 [開啟]。
  2. 在您的文件中會出現另一個分頁，有著您匯入檔案的名稱。請選擇該分頁來開啟它：

自訂工作流程的範例

您可以使用 FeatureScript 工作流程動作來以程式設計方式更新發行項目上的屬性 (作為工作流程轉換的一部分)。藉由在同一工作區的 Feature Studio 中指定自訂的工作流程做為工作流程定義，可以在該 Feature Studio 中將一個函數執行為動作，以決定套用至每個項目上的屬性更新。

若要在自訂工作流程中使用這個功能，請將 updateItemPropertiesFromFeatureScript 工作流程動作當做一個轉換動作，或在狀態上的 entry 或 exit 動作。動作採用參數：

  • FeatureStudio ID - The Feature Studio must reside in the same workspace as the customized release workflow definition

  • A function name exported by that Feature Studio - This function must take a single argument that has type: map. The Map type passed into the function when it is executed contains this data:

{
// The full detailed release package, including all items and properties
// (as it would be returned by the getReleasePackage REST API)
"releasePackage": BTReleasePackageInfo,
 
// The user performing the transition
"currentUser": BTUserSummaryInfo,
 
// The user who originally created the Release candidate
"releaseCreator": BTUserSummaryInfo,
 
// The transition being executed, as it appears in the workflow definition
"transition": BTTransitionDef,
 
// The current UTC date/time, as an ISO date string
"currentDate": string
}

函數必須返回格式的映射 (map)：

{[key: string]: {[key: string]: any}}

主要的映射 (map) 是以發行項目 ID 來建立索引的，內部的映射是從中繼資料屬性 ID 到所需的新值。例如，如果函數返回下列的映射：

{
"item1": {
"57f3fb8efa3416c06701d616": "New value",
"customIntProperty": 42
},
"item2": {
"57f3fb8efa3416c06701d617": "Some other value"
}
}

那麼對 ID 是 “item1” 的發行項目，“Title 1” 屬性會被設定為字串 “New value”，一個假定的自訂屬性 (上方的 customIntProperty) 會被設定為數字 42。對 ID 是 “item2” 的項目，“Title 2” 屬性將會被設定為字串 “Some other value”。

會將完整的發行套件資訊以輸入項提供給函數，因此如果需要可以進行額外的篩選與計算。例如，僅將一個屬性套用至是工程圖的項目上，或僅套用至有某些類別的項目上，或是從其他屬性值來計算一個屬性值。

請特別注意，FeatureScript 本身不會套用任何變更到發行套件中；對輸入資料的任何修改將無法於 FeatureScript 的執行中存活，而是由函數返回的值來告知系統要做出的變更。

在返回映射 (map) 中值的類型必須與相對應中繼資料屬性的值類型相符 (其會被送至 “update metadata” API 中)；無效的值將會導致屬性的更新失敗。

User-type 中繼資料屬性接受物件陣列的型式：

{"id": [userId]}

User-type 工作流程屬性包含一個物件的陣列，其中使用者 ID 是在 “entryId” 的欄位。因此，若要將來自工作流程屬性的使用者加入至中繼資料屬性中，則必須將值轉換為正確的格式。

User-type 中繼資料屬性僅接受 ID，而不接受團隊或角色 ID。若要將一個 User-type 工作流程屬性套用至一個 User-type 中繼資料屬性，請僅使用在工作流程屬性中是使用者的項目 – 也就是有 0 的 “entryType”。

If any property updates fail due to a bad propertyID or value in the returned object, the workflow action will fail and the failures will be logged for workflow developers to use to debug (see Workflow debugging, below).

如果在 FeatureScript 執行的過程中發生錯誤，或返回物件的格式錯誤，則動作也會失敗。例如，如果返回的物件不是項目 ID 對屬性更新的映射。

If the action fails, it is likely because of a bug in the workflow FeatureScript rather than a bug in the system. In this case, you will receive an error message returned with the HTTP response directing you (or your users) to contact the workflow administrator. The workflow developer can use the workflow Audit log to identify and debug the failure (see Workflow Audit logging, below). If necessary, the workflow developer can create a support ticket with Onshape.

This is a new global permission in Onshape Enterprise which allows publishing and debugging customized release workflows. Users with this permission can publish workflows, and will always be given the option to create a Release candidate in debug mode (see Workflow debugging, below).

不允許循環的工作流程。

Only users with the Manage Workflows global permission can publish workflows. For more information on Global permissions, see Understanding Global Permissions.

如下所述編輯自訂工作流程：

  1. 對 JSON 工作流程進行編輯。在您編輯時，右側的圖表會反映出所做的變更。
  2. 圖表是動態式且可拖曳的，因此如果結構沒有反映出您所要的工作流程，請使用滑鼠游標來調整。
  3. Once you are satisfied with your edits and want to make your workflow available for use in the enterprise, click Publish to open the Publish custom workflow dialog:

    「發佈自訂工作流程」對話方塊

    這個對話方塊會警示您在發佈之前需要修正的所有錯誤，訊息會出現在對話方塊的上方：

    發佈自訂工作流程錯誤

    1. 按一下 取消 來關閉對話方塊。

    2. 更正錯誤。

    3. 再按一下 發佈 來開啟對話方塊。

  4. 提供「名稱」、「說明」與「工作流程類型」。

  5. 在「取代工作流程」下拉清單中執行下列操作之一：

    1. 如果這是一個新的工作流程，請選擇 [無]。

    2. 若要取代一個現存的工作流程，則選擇您想要取代的工作流程。系統會自動填入所選置換的「名稱」與「說明」欄位。您可以保留現有的值或輸入新的值：

      置換自訂工作流程

  6. Click Publish.

解除發佈工作流程後，會發生下列的情況：

  • 工作流程將無法再用於發行管理中以建立新的發行套件。

  • 會將使用已移除工作流程的任何設定重設回 Onshape 預設的工作流程

  • 目前在經移除工作流程中的發行/淘汰候選將繼續正常運作。使用已解除發佈工作流程的現有發行套件與已送交的發行套件仍維持不受影響。您仍可以使用自訂的工作流程與轉換待決發行來開啟、檢視與淘汰現有的發行套件。

只有擁有管理工作流程權限 (在 [Enterprise 設定] > [整體權限] 之下) 的使用者可以解除發佈工作流程。

解除發佈工作流程：

  1. 按一下右上方文件工具列中您的名字或帳戶使用者圖示 ()，然後選擇 [Enterprise 設定] > [發行管理]。

  2. 從工作流程下拉清單中選擇要解除發佈的發行工作流程。

  3. 按一下工作流程下拉清單右側的「在文件中檢視」連結。系統會在目前的瀏覽器分頁中開啟工作流程文件。

  4. Click the Unpublish button at the top of the document.

    從工作流程文件中按一下 [解除發佈]

  5. The Unpublish workflow dialog opens. Click the Unpublish button.

解除發佈工作流程對話方塊

解除發佈預設的工作流程會將預設工作流程重設為 Onshape 的預設。

有管理工作流程全域權限的使用者可以在開發的過程中使用偵錯模式來測試工作流程。

必須先發佈工作流程才能在發行零件/組合件時於「選擇發行工作流程」對話方塊中選擇工作流程 (在您對新工作流程感到滿意之後，可以回到 Enterprise 設定中來將工作流程設定為啟用的)。

「選擇發行工作流程」對話方塊

一個典型的已發佈工作流程會指向工作流程定義 (JSON 檔案) 所在處的一個文件版本。使用該發佈工作流程的發行會遵循定義於該版本中的工作流程。反之偵錯模式會使用存在於文件工作區與已發佈版本相關的工作流程。請注意，僅在已發佈版本之上只有一個工作區時，工作流程才會以偵錯模式開始，以避免模稜兩可的情況發生。

偵錯模式可允許在工作流程發展過程中的快速迭代。如果您發現工作流程未如預期運作，您可以變更工作流程 JSON 或改變在工作區中新動作採用的 Feature Studio。馬上開始一個新的發行可讓您 (工作流程開發人員) 查看變更的效果而無需先發佈工作流程的一個新版本。

偵錯工作流程：

  1. 核取 [偵錯模式] 方塊 (如上方圖片中所示)。

  2. 按一下 確定。

    建立發行候選對話方塊

  3. In this dialog, you can select the overflow menu button () at the top right corner >  View audit log to see an audit trail of the workflow objects and their significant events, for example, creation and transition.

  4. 您也可以選擇 [檢視工作流程] 來查看圖表型式的工作流程，如下方圖表中所示強調顯示最後的狀態：

    以圖表型式檢視自訂的工作流程，強調顯示最後的狀態

在工作區中對偵錯模式工作流程的變更不會影響到任何已在進行中的發行。會在建立時將偵錯發行鎖住為工作區的微版本。若要查看變更的結果，您需要建立新的發行。這個程序可避免對工作流程定義的變更侵入至進行中的發行，並避免發行遭到捨棄。

在您發佈了自訂工作流程之後，如果需要，可以在 Enterprise 中啟用多個作用中工作流程。當您的使用者可採用多個作用中工作流程時，可以選擇在建立發行候選時要遵循那個工作流程。

管理員有責任教育使用者應該使用那些工作流程，且說明使用的條件為何。

啟用多個工作流程：

  1. 根據上方的指示操作來建立多個自訂工作流程，並於 Onshape 中發佈。
  2. 在Enterprise 設定的發行管理頁面中，從管理的工作流程部分核取工作流程旁的「啟用」方塊以選擇要設定為啟用的自訂工作流程：

    Enterprise 設定：發行管理自訂工作流程

  3. Click the Workflow preview icon (Workflow preview icon) to expand a dropdown of an illustration depicting the workflow. Beneath the illustration is a description of the current workflow process:

    展開的自訂工作流程

  4. Make sure to click Save release settings to save the changes you've made to the Release management settings for the enterprise.

當您的使用者建立一個發行候選時，系統會在當下提供機會讓他們選擇一個工作流程 (從下拉清單中)：

選擇發行工作流程

下方說明自訂發行或淘汰工作流程的語法。請注意英文字母大寫是重要的。

請注意下列的規則。

格式

  • name: 字串
  • propertyId: 字串
  • valueType: string|ENUM
  • defaultValue?: 任何
  • usersOnly?: 布林值
  • teamsOnly?: 布林值
  • enumValues?: list

限制

  • 屬性 (Property) ID 必須是獨特的 (不與 Onshape 的硬式編碼名稱、說明、或評論屬性 ID 相符)
  • valueType 必須是 BTMetadataValueType 的名稱 (排除 BLOB 與 OBJECT)
  • 如果 valueType 是 ENUM，則必須指定 enumValues，且屬性包含一或多個 enumValues。每個 enumValues 必須有一個強制的「值」元素。可選擇性使用標籤元素。
  • 如果提供有 defaultValue，則其應與 enumValues 之一的值欄位相符。
  • usersOnly 與 teamsOnly 是互相排斥的，且僅對 USER 屬性有效
  • defaultValue, if present, must match the correct type indicated by valueType
    • STRING: 字串
    • BOOL: 布林值
    • INT: 整數
    • DOUBLE: 小數
    • USER: 字串[]
    • DATE: ISO 日期字串
    • 目前不支援 BLOB 與 OBJECT
  • USER-type 屬性值是使用者、團隊、和/或角色 ID 的清單

格式

  • name: 字串
  • displayName: 字串
  • approverSourceProperty?: 字串
  • notifierSourceProperty?: 字串
  • entryActions?: 動作[]
  • exitActions?: 動作[]
  • editableProperties?: string[]
    • Values may include:

      • approvers

      • 觀察人員

  • requiredProperties?: 字串[]
  • requiredItemProperties?: 字串[]

限制

  • 名稱 (name) 必須是獨一無二的
  • 如果有 approverSourceProperty 與 notifierSourceProperty 的話，則必須是工作流程的屬性 ID，且必須指向 USER-type 屬性
  • 最多一個狀態可以使用一個指定的屬性做為其核准者。
  • 隨意數量的狀態可以使用個指定的屬性做為其通知者。
  • editableProperties 與 requiredProperties 必須在在同一工作流程中的屬性 ID。
  • requiredItemProperties 必須是對您公司有效的中繼資料屬性 ID (Onshape 內建屬性或自訂屬性，排除計算屬性 )。

For more information on IDs, see Understanding and Administering Project Roles and Permission Schemes.

格式

  • name: 字串
  • displayName: 字串
  • type: 字串
  • sourceState: 字串
  • targetState: 字串
  • uiHint?: string (default: "primary")
  • actions?: 動作[]
  • requiredProperties?: 字串[]

限制

  • 名稱 (name) 必須是獨一無二的。
  • 類型必須是 “APPROVE”、“REJECT” 或 “SUBMIT” 之一。
  • sourceState 與 targetState 在工作流程中必須是兩個不同的狀態。
  • 最多有一個來自任何來源狀態的 APPROVE-type 轉換。
  • 對於 APPROVE-type 的轉換，sourceState 必須有一個 approverSourceProperty。
  • 如果有 uiHint 的話，必須是 “primary”、“success” 或 “danger” 其中之一 (這些是在發行對話方塊中的色彩方塊與其他項目，且是由 Onshape 硬式編碼的)。

轉換類型

送出

  • 當發行離開設定階段進入工作流程時，在發行上執行各種「初始化」，像是為發行中經組態零件開始產生縮圖，連接已連結文件/版本 ID 等等。
  • 只有發行的建立者可以執行 SUBMIT 轉換。
  • 離開初始狀態的轉換應為 Submit。
  • 不是初始轉換的 Submit 並沒有任何特殊的效能

核准

  • 將使用者標示為已核准 (發行對話方塊中權杖的變為綠色)。
  • If company policies are set to Require all approvers, the transition will not be performed until all approvers have approved.
  • 為項目產生組合件/工程圖內容參考。
  • 僅允許這個類型的一個轉換離開一個狀態。
  • 只有目前狀態的核准者 (或管理員) 可以核准。

拒絕

  • 將使用者標示為已拒絕 (發行對話方塊中權杖的變為紅色)。
  • 只有目前狀態的核准者 (或管理員) 可以拒絕。

格式

  • name: 字串
  • params?: {[key: 字串]: 任何}

限制

  • Name must match one of our predefined action names (see below, under Allowed Actions)
  • 某些動作僅允許在狀態或轉換上執行，某些可能有順序的限制。

允許的動作

  • sendEmailNotifications - Send email notifications for a transition (including mobile push notifications).
    • 允許於：僅轉換
    • 參數：無
  • sendUserNotifications - Send user notifications for a transition.
    • 允許於：僅轉換
    • 參數：無
  • markItemsPending - Change the metadata state of all items in the release to Pending.
    • 允許於：狀態或轉換
    • 參數：無
    • 在淘汰工作流程中不允許。
    • 在發行工作流程中於 markItemsReleased 或 markItemsRejected 之後是不可能。
  • markItemsRejected - Change the metadata state of all items in the release to Rejected.
    • 允許於：狀態或轉換
    • 參數：無
    • 在淘汰工作流程中不允許。
    • 在發行工作流程中於 markItemsReleased 之後或 markItemsPending 之前是不可能
    • releaseItems - Change the metadata state of all items in the release to Released and create revisions for them (auto-obsoleting other revisions if specified in company policy).

      Allowed on: states or transitions

      參數：無

      在淘汰工作流程中不允許。

  • obsoleteItems - Change the metadata state of all items in the package to Obsolete and obsolete their corresponding revisions.
    • 允許於：狀態或轉換
    • 參數：無
    • 在發行工作流程中不允許
  • updateItemPropertiesFromFeatureScript - Use this to use a FeatureScript feature as a transition action, or as an entry or exit action on a state.
    • 允許於：狀態或轉換
    • 參數：map (有這個類型的單一引數)

When defining a custom workflow, you can include an options section designed to override specific company release settings defined on the Enterprise settings > Release management page. These options for overriding are explained below:

"options": {
"revisionSchemeId": string,
"requireApprover": boolean,
"requireAllApprovers": boolean,
"disallowCreatorAsApprover": boolean,
"requireNote": boolean,
"autoObsolete": boolean,
"errorOnFeatureListErrors": boolean,
"errorOnRolledBack": boolean,
"errorOnAssemblyErrors": boolean,
"errorOnAssemblyRefsOutOfDate": boolean,
"errorOnDrawingOutOfDate": boolean,
"errorOnPartNumberPending": boolean,
"errorOnPendingTask": boolean,
"nameOverride": string, (overrides the Release name label, or Obseletion name, in the Release dialog)
"descriptionOverride": (overrides the Release notes label, or Obseletion notes, in the Release dialog)
}

這個部分與所有的欄位都是選擇性使用的。您可以選用任何子集來覆寫 Company 設定。並未包含在程式碼中的任何欄位會預設使用在 Enterprise 設定中的規格。

可從「Enterprise 設定」> 「發行管理」頁面的唯讀文字方塊中取得修訂方案 Id：

「修訂版與零件編號」中的「修訂方案」

所有工作流程物件會建立其存留期間重大事件的稽核記錄，例如，建立與轉換。可以使用下列的指令來取得這個記錄

GET /api/workflow/obj/<object id>/auditlog

您可以叫取發行中的一個連結來檢視記錄的輸出，在其中檢查與偵錯問題。

稽核記錄回覆中包含關於物件工作流程的基本資訊 (包括其發佈的工作流程版本與其是否是一個偵錯模式的工作流程) ，以及為其記錄的所有事件。

每個記錄項目包含：

  • 一個時間戳記

  • 一個類型 (由是 BTWorkflowAuditEntryType 序數的一個整數所代表)

  • 事件發生時的工作流程狀態/轉換/動作。

如果適用的話，也有其他事件類型特定 (event-type-specific) 資訊的額外欄位。

稽核事件的類型包括：

  • Object created - First event logged for an object, when it is created.

  • Object discarded - When the special Discard action is performed on the object.

  • Object deleted - When the object is removed, usually due to being old enough to be caught by the cleanup server ( the audit log for a deleted object is not deleted).

  • Properties updated - When workflow properties are changed on the object. This is for package-level properties on a release package (for example), not metadata properties on individual items.

    • 這包括已變更的屬性 ID (來自工作流程定義)，包含其舊的與新的值。

  • Comment added - Includes the ID of the newly added comment.

  • User approved - When a user performs the approval action for the current state. This may or may not be accompanied by a transition, depending on the company release settings.

    • 這包括動作執行的核准者清單中使用者/團隊/角色 ID，也就是使用者是代表誰核准的。

  • User rejected - When a user performs the reject action for the current state.

    • 這包括動作執行的核准者清單中使用者/團隊/角色 ID，也就是使用者是代表誰拒絕的。

  • 已開始的轉換

  • 已完成轉換

  • Transition failed - This includes an error message or support code, if applicable.

  • 已開始的動作

  • 已完成的動作

  • Action failed - This includes an error message or support code, if applicable.

  • FeatureScript executed - This includes any console output from the FeatureScript execution.

    • 這包括由 FeatureScript 執行所返回的全部注意事項 (如果發生了例外狀況也會包括)。

    • 包括來自 FeatureScript 函數的返回值。

  • Item metadata updates failed - When a release package item metadata update request fails during a transition.

    • 這包括失敗的中繼資料屬性 ID，失敗項目的中繼資料 hrefs 與錯誤訊息。

    • 除了發生在 FeatureScript 動作過程中，否則通常會導致轉換失敗。需要繼續內建的動作，但在允許轉換繼續時，設定其他來自 FeatureScript 的屬性可能會失敗。