创建自定义发布工作流程

在设置包含两个层的自定义发布工作流程，而且第二层不为必需（即，第二层为可选）时，如果在发布套件中未指定审批者，Onshape 将自动从“待决中”转换到“已发布”。不需要对此进行设置，只需满足以下要求：拥有两层工作流程，第二层为可选，而且在发布候选的“审批者”输入框中未指定审批者。

要下载 Onshape 默认工作流程文件：

1. 导航到您的企业设置，然后选择发布管理。
2. 确认已选中“启用受管工作流程”，然后单击“在文档中查看”。

   

   工作流程文件在另一个选项卡的公开文档中打开。

3. 单击“下载”，输入文件的新名称。
   

   下载选项卡后，您可以关闭该选项卡。

1. 在您的企业中，导航到“文档”页面，选择“创建”>“文档”，然后选择确定。（在此示例中，文档名称是公司自定义工作流程）
2. 在新文档中，单击底部的加号图标 ，然后选择“导入”：

3. 选择刚下载的工作流程文件，然后单击“打开”。
4. 另一个选项卡显示在文档中，其中包含您导入的文件的名称。选择该选项卡将其打开：

您可以在工作流程转换过程中使用 FeatureScript 工作流程操作以编程方式更新发布项的特性。通过将自定义工作流程指向与工作流程定义相同的工作区中的 Feature Studio，该 Feature Studio 中的函数可以作为一项操作来执行，该操作可确定要应用于每个发布项的特性更新。

要将其用于自定义工作流程，请将 updateItemPropertiesFromFeatureScript 工作流程操作用作转换操作，或者状态的进入或退出操作。操作采用以下参数：

• FeatureStudio ID - Feature Studio 必须与自定义发布工作流程定义位于同一工作区中

• 由该 Feature Studio 导出的函数名称 - 此函数必须接受类型为映射的单个参数。在执行函数时传递给函数的映射类型包含以下数据：

{

// 完整详细的发布套件，包括所有条目和特性

//（因为它将由 getReleasePackage REST API 返回）

"releasePackage": BTReleasePackageInfo,

// 执行转换的用户

"currentUser": BTUserSummaryInfo,

// 最初创建发布候选的用户

"releaseCreator": BTUserSummaryInfo,

// 正在执行的转换，正如它出现在工作流程定义中一样

"transition": BTTransitionDef,

// 当前的 UTC 日期/时间，采用 ISO 日期字符串的形式

"currentDate": string

}

函数必须返回以下形式的映射：

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

主映射由发布项 ID 进行键控，而内部映射是指从元数据特性 ID 映射到所需的新值。例如，如果函数返回以下映射：

{

"item1": {

"57f3fb8efa3416c06701d616": "New value",

"customIntProperty": 42

},

"item2": {

"57f3fb8efa3416c06701d617": "Some other value"

}

}

然后，对于 ID 为“item1”的发布项，“标题 1”特性将设置为字符串“新值”，一个假设的自定义特性（即上面的 customIntProperty）将设置为数字 42。对于 ID 为“item2”的条目，“标题 2”特性将设置为字符串“其他某个值”。

系统会将完整的发布套件信息作为输入提供给函数，因此可以根据需要执行额外的筛选和计算。例如，只将一个特性应用于与工程图相关的条目或只应用于具有特定类别的条目，或者根据其他某个特性值来计算一个特性值。

请务必注意，FeatureScript 本身不会对发布套件应用任何更改；对输入数据做出的任何修改都不会在 FeatureScript 执行之后继续存在，而是由函数返回的值来告知系统要做出的更改。

特性值类型

返回的映射中的值类型必须与相应元数据特性的值类型相符（系统会将其发送到“更新元数据”API）；无效值会导致特性更新失败。

用户类型元数据特性接受以下形式的对象数组：

{"id": [userId]}

用户类型工作流程特性包含对象数组，其中用户 ID 在“entryId”输入框中。因此，要将用户从工作流程特性添加到元数据特性，必须将值转换为正确的格式。

用户类型元数据特性仅接受用户 ID，而不接受团队或角色 ID。要将用户类型工作流程特性应用于用户类型元数据特性，请仅使用工作流程特性中的用户条目，即“entryType”为 0 的条目。

如果任何特性更新因返回的对象中 propertyID 或值错误而失败，那么工作流程操作也会失败，并且系统会记录失败信息，以便工作流程开发者用其进行调试（请参见下面的工作流程调试）。

如果在 FeatureScript 执行过程中出错或返回的对象格式错误（例如，如果返回的对象不是条目 ID 到特性更新的映射），操作也会失败。

如果操作失败，很可能是因为工作流程 FeatureScript 中存在错误，而不是系统中存在错误。在这种情况下，您会收到与 HTTP 响应一起返回的错误消息，引导您（或您的用户）与工作流程管理员联系。工作流程开发者可以使用工作流程核查日志来找出和调试故障（请参见下面的工作流程核查日志记录）。如有必要，工作流程开发者可以向 Onshape 提交技术支持工单。

管理工作流程全局权限

这是 Onshape Enterprise 中的一项新的全局权限，允许发布和调试自定义发布工作流程。具有此权限的用户可以发布工作流程，并且始终可以选择在调试模式下创建发布候选（请参见下面的工作流程调试）。

不允许周期性工作流程。

只有拥有 “管理工作流程” 全局权限的用户才能发布工作流程。有关全局权限的更多信息，请参阅了解全局权限。

如下所示编辑自定义工作流程：

1. 编辑 JSON 工作流程文件。在您编辑时，右边的图表会反映所做的更改。
2. 该图表为动态，且可以拖动，因此如果结构不能反映您的预期工作流程，请使用光标进行调整。
3. 对编辑表示满意并希望将工作流程设为可供企业使用后，您可单击发布以打开“发布自定义工作流程”对话框：

   

   该对话框会提醒您任何需要在发布之前修复的错误，这将显示在对话框的顶部：

   

   1. 单击取消以关闭对话框。

   2. 修复错误。

   3. 再次单击发布以打开对话框。

4. 提供名称、说明和工作流程类型。

5. 在“替换工作流程”下拉列表中，执行以下操作之一：

   1. 如果这是一个新工作流程，请选择“无”。

   2. 如需替换已经存在的工作流程，选择您想要替换的工作流程。将自动填充所选的替换名称和说明输入框。您可以保留现有值或输入新值：

      

6. 单击发布。

取消发布工作流程后，会发生以下情况：

• 该工作流程不再可用于在发布管理中创建新的发布包。

• 使用已删除的工作流程的所有设置都将重置为 Onshape 默认工作流程

• 当前处于已删除工作流程中的发布/过时候选可以继续正常工作。使用未发布工作流程的现有发布包和已提交的发布包不受影响。您仍然可以使用自定义工作流程和过渡待定发布来打开、查看和淘汰现有发布包。

Only users who have Manage workflows permissions (under Enterprise settings > Global permissions) can unpublish a workflow.

取消发布工作流程：

1. 单击“文档”工具栏右上角的您的姓名或帐户用户图标 ()，然后选择“企业设置” > “发布管理”。

2. 从工作流程下拉菜单中选择要取消发布的发布工作流程。

3. 单击工作流程下拉菜单右侧的“在文档中查看”链接。工作流程文档将在当前浏览器选项卡中打开。

4. 单击文档顶部的取消发布按钮。

   

5. 取消发布工作流程对话框打开。单击取消发布按钮。

取消发布默认工作流程会将默认工作流程重置为 Onshape 的默认工作流程。

具有“管理工作流程”全局权限的用户可以使用调试模式测试开发中的工作流程。

必须先发布工作流程，这样在发布零件/装配体时该工作流程才会在“选择发布工作流程”对话框中可用。（在对新工作流程感到满意之后，您可以返回 Enterprise 设置，将该工作流程设为活动状态。）

典型的已发布工作流程指向工作流程定义所在文档（JSON 文件）的一个版本。使用该已发布工作流程的发布版遵循在该版本中定义的工作流程。相反，调试模式使用与已发布版本关联的文档工作区中存在的工作流程。请注意，仅当已发布版本之上正好只有一个工作区时，工作流程才会在调试模式下开始，这样可以避免模棱两可的情况发生。

调试模式允许在工作流程开发过程中进行快速迭代。如果您发现工作流程未按预期运行，您可以在工作区中对新操作所使用的工作流程 JSON 或 Feature Studio 进行更改。立即开始新发布可让您（工作流程开发者）看到效果，而无需先发布工作流程的新版本。

要调试工作流程，请执行以下操作：

1. 选中“调试模式”框（如上图中所示）。

2. 单击“确定”。“创建发布候选”对话框打开：

   

3. 在此对话框中，您可以选择右上角的溢出式菜单按钮 ()，然后单击“查看审计日志”以查看工作流对象及其重要事件（例如创建和过渡）的审计记录。

4. 您也可以选择“查看工作流程”来以图表的形式查看工作流程，其中最新的状态会亮显，如下面的图表所示：

   

在工作区中对调试模式下的工作流程所做的更改不会影响任何已在进行中的发布。调试发布在创建时锁定到工作区的微型版本。要查看更改所产生的结果，您需要创建一个新发布。此过程可防止对工作流程定义所做的更改破坏正在进行中的发布，还能防止其被舍弃。

发布自定义工作流程后，您可以根据需要在 Enterprise 中启用多个活动的工作流程。当多个活动的工作流程对用户可用时，用户可以在创建发布候选时选择要遵循的工作流程。

管理员需要负责指导用户应在什么条件下使用哪些工作流程。

要启用多个工作流程：

1. 遵循以上说明创建多个自定义工作流程，并在 Onshape 中发布它们。
2. 在企业设置的发布管理页面中，通过选中每个工作流旁边的“启用”复选框，从“管理工作流程”部分中选择要启用的自定义工作流程：

   

3. 单击工作流程预览图标 工作流程预览图标 () 可展开描绘工作流程的图示说明的下拉菜单。图示下方是对当前工作流程的说明：

   

4. 确保单击保存发布设置，以便保存您已对企业发布管理的设置进行的更改。

当您的用户创建发布候选时，将有机会选择工作流程（通过下拉菜单）：

自定义发布或淘汰工作流程的语法如下所示。请注意，务必大写。

请记住以下规则。

特性

格式

• name: string
• propertyId: string
• valueType：string|ENUM
• defaultValue?: any
• usersOnly?: boolean
• teamsOnly?: boolean
• enumValues?：list

限制

• 特性 ID 必须唯一（并且不匹配 Onshape 的硬编码名称、说明或评论特性 ID）
• valueType 必须是 BTMetadataValueType 的名称（不包括 BLOB 和 OBJECT）
• 如果 valueType 为 ENUM，则必须指定 enumValues，并且特性必须包含一个或多个 enumValues。每个 enumValues 必须具有必填的值元素。表元素是可选的。
• 如果提供了 defaultValue，它应与一个 enumValues 的值输入框相匹配。
• usersOnly 和 teamsOnly 互相排斥，仅对 USER 特性有效
• defaultValue（如果存在）必须与 valueType 指示的正确类型匹配
  • STRING: string
  • BOOL: boolean
  • INT: integer
  • DOUBLE: decimal
  • USER: string[]
  • DATE: ISO date string
  • 目前不支持 BLOB 和 OBJECT
• USER 类型特性值是用户、团队和/或角色 ID 的列表

状态

格式

• name: string
• displayName: string
• approverSourceProperty?: string
• notifierSourceProperty?: string
• entryActions?: Action[]
• exitActions?: Action[]
• editableProperties?: string[]
  • 值可能包括：

    • 审批者

    • 观察者

• requiredProperties?: string[]
• requiredItemProperties?: string[]

限制

• 名称必须唯一
• approverSourceProperty 和 notifierSourceProperty（如果存在）必须是工作流程的特性 ID，并且必须指向 USER 类型特性
• 一个状态最多可以使用指定的特性作为其审批者。
• 任何数量的状态都可以使用指定的特性作为通知。
• editableProperties 和 requiredProperties 必须是同一工作流程中的特性 ID。
• requiredItemProperties 必须是公司的有效元数据特性 ID（Onshape 内置特性或自定义特性，不包括计算特性）。

有关 ID 的更多信息，请参阅了解和管理项目角色和权限方案。

转换

格式

• name: string
• displayName: string
• type: string
• sourceState: string
• targetState: string
• uiHint?: string (default: "primary")
• actions?: Action[]
• requiredProperties?: string[]

限制

• 名称必须唯一。
• 类型必须是“APPROVE”、“REJECT”或“SUBMIT”之一。
• sourceState 和 targetState 必须是工作流程中的两个不同状态。
• 最多可能有一个来自任何源状态的 APPROVE 类型转换。
• 对于 APPROVE 类型转换，sourceState 必须具有 approverSourceProperty。
• uiHint（如果有）必须是“主要”、“成功”或“危险”（这些是发布对话框中的框和其他图元的颜色，并且由 Onshape 硬编码）。

转换类型

提交

• 退出设置，然后进入工作流程时，在发布中执行各种“初始化”，例如在发布中启动已配置零件的缩略图生成，连接链接的文档/版本 ID 等。
• 只有发布创建者才能执行 SUBMIT 转换。
• 应从初始状态外转换为 SUBMIT。
• 不是初始转换的 SUBMIT 没有任何特殊能力

批准

• 将用户标记为已核准（在发布对话框中将令牌变为绿色）。
• 如果公司策略设置为需要所有审批者，则在所有审批者都批准之前不会执行转换。
• 生成条目的装配体/工程图内容参考。
• 只允许一种状态转换为此类型。
• 只有当前状态（或管理员）的审批者才能批准。

拒绝

• 将用户标记为已拒绝（在发布对话框中将令牌变为红色）。
• 只有当前状态（或管理员）的审批者才能拒绝。

操作

格式

• name: string
• params?: {[key: string]: any}

限制

• 名称必须与我们的预定义操作名称匹配（请参阅下文的允许的操作）
• 某些操作可能仅允许在状态或转换上使用，有些可能有订阅限制。

允许的操作

• sendEmailNotifications - 发送转换的电子邮件通知（包括移动推送通知）。
  • Allowed on: transitions only
  • Parameters: none
• sendUserNotifications - 发送转换的用户通知。
  • Allowed on: transitions only
  • Parameters: none
• markItemsPending - 将发布中所有条目的元数据状态更改为“待决中”。
  • 允许用于：状态或转换
  • Parameters: none
  • 不允许在淘汰工作流程上使用。
  • 在发布工作流程中，不可能在 markItemsReleased 或 markItemsRejected 之后。
• markItemsRejected - 将发布中所有条目的元数据状态更改为“已拒绝”。
  • 允许用于：状态或转换
  • Parameters: none
  • 不允许在淘汰工作流程中使用。
  • 在发布工作流程中，不可能在 markItemsReleased 之后或 markItemsPending 之前
• releaseItems - 将发布中的所有物项的元数据状态更改为“已发布”并为其创建修订（如果在公司策略中指定，则自动淘汰其他修订）。

  Allowed on: states or transitions

  Parameters: none

  不允许在淘汰工作流程上使用。

• obsoleteItems - 将包中所有条目的元数据状态更改为“淘汰”并淘汰其相应的修订。
  • 允许用于：状态或转换
  • Parameters: none
  • 不允许在发布工作流程上使用
• updateItemPropertiesFromFeatureScript - 使用此项可将 FeatureScript 特征用作转换操作，或者用作状态的进入或退出操作。
  • 允许用于：状态或转换
  • 参数：映射（具有此类型的单个参数）

定义自定义工作流程时，可以包括“选项”部分，该部分旨在替代公司设置>发布管理页面上定义的特定公司发布设置。这些替代选项说明如下：

"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, （在“发布”对话框中替代发布注释标签或淘汰版本名称）

"descriptionOverride"：（在“发布”对话框中替代发行说明标签或淘汰版本注释）

}

本部分和所有输入框均可选。您可以选择要用来替代公司设置的任何子集。代码中未包括的任何输入框将默认为企业设置中的规格。

可以从“企业设置”>“发布管理”页面上的只读文本框中获取修订方案 ID：

所有工作流程对象都会创建其生命周期内重大事件（例如创建和转换）的核查轨迹。检索此日志的方法是使用

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

您可以通过发布中的链接来查看该调用的输出，以便检查和调试问题。

核查日志响应包含有关工作流程对象的所有基本信息（包括它的已发布工作流程版本，以及它是否为调试模式工作流程），以及为其记录的所有事件。

每个日志条目都包含：

• 时间戳

• 一个类型（由一个整数表示，该整数是一个 BTWorkflowAuditEntryType 序数）

• 事件发生时的工作流程状态/转换/操作。

在适用的情况下，还有一些其他输入框用来提供额外的事件类型特有信息。

核查事件的类型如下：

• 对象已创建 - 在创建对象时为其记录的第一个事件。

• 已舍弃对象 - 当对对象执行特殊的舍弃操作时。

• 对象已删除 - 当对象被移除时，被移除通常是由于对象存在时间足够长而被清理服务器捕获（不会删除已删除对象的核查日志）。

• 特性已更新 - 当对象的工作流程特性发生更改时。这针对发布套件的包级特性，而不是各个条目的元数据特性。

  • 这包括已更改的特性 ID（来自工作流程定义），包含其旧值和新值。

• 已添加评论 - 注明新添加的评论的 ID。

• 用户已批准 - 当用户针对当前状态执行审批操作时。这可能会伴随着转换，也可能不会伴随着转换，具体取决于公司发布设置。

  • 这包括执行操作所针对的审批者列表中的用户/团队/角色 ID，也就是说，用户是代表谁执行审批的。

• 用户已拒绝 - 当用户针对当前状态执行拒绝操作时。

  • 这包括执行操作所针对的审批者列表中的用户/团队/角色 ID，也就是说，用户是代表谁拒绝的。

• 转换已开始

• 转换已完成

• 转换失败 - 这包括错误消息或支持代码（如果适用）。

• 操作已开始

• 操作已完成

• 操作失败 - 这包括错误消息或支持代码（如果适用）。

• FeatureScript 已执行 - 这包括执行 FeatureScript 所产生的任何控制台输出。

  • 这包括通过执行 FeatureScript 返回的任何通知（如果发生了异常，也会包括在内）。

  • 包括从 FeatureScript 函数返回的值。

• 条目元数据更新失败 - 当发布套件条目元数据更新请求在转换过程中失败时。

  • 这包括失败的元数据特性 ID、失败条目的元数据超文本参考以及错误消息。

  • 通常会导致转换失败，除非发生在 FeatureScript 操作期间。内置操作需要成功，但从 FeatureScript 设置额外的特性可能会失败，同时允许继续转换。