Onshape 提供您可立即开始使用的通用发布管理工作流程。此流程在典型发布工作流程中进行介绍。除此通用工作流程外，Onshape 还支持您设计和创建自己的自定义发布管理工作流程，然后发布该工作流程以供整个组织使用。您甚至可以创建多个工作流程，以满足贵组织中的特定发布管理需求。

若要访问此功能，必须为您指定您的 Onshape 企业的管理员角色。

Onshape 提供控制版本管理行为的许多选项。根据您的业务流程，这些设置可以定义为规定版本的行为方式、版本的条件以及可使用的修订方案等的默认规则。可以通过 Onshape 订阅中的“公司/Enterprise 设置”的“版本管理”页面设置这些选项。

在许多情况下，当在组织中实施多个发布流程时，不同流程可能需要不同的发布设置。通过实施还可在每个流程中替代默认设置的自定义发布流程，可以在每个发布流程中替代“发布管理设置”页面中定义的默认设置。

阅读以了解创建您自己的自定义版本管理工作流的流程，以及如何在 Onshape 中实施这些流程。

创建自定义工作流时涉及的方面

基本上，Onshape 使用 JSON 文件为版本和过时工作流定义工作流的布局和行为。

  1. 下载基本 Onshape JSON 文件
  2. 自定义文件，然后自定义在此主题中提供的 JSON 语法：
  3. 将自定义的 JSON 文件上传回 Onshape 文档
  4. 向贵组织发布自定义工作流

这些步骤将在下面详细介绍。

下载 JSON 文件

您可以在贵组织的 Onshape 域中找到基本 JSON 文件：

  1. 登录到您的 Onshape 帐户。
  2. 导航到“公司/Enterprise 设置”>“发布管理”页面。
  3. 在工作流程标题下，选择您要创建的工作流程类型：发布工作流程或淘汰工作流程。
  4. 在下拉列表中选择“Onshape 默认值...”。
  5. 单击下拉列表旁边的在文档中查看链接：

工作流程设置和启用托管工作流程的示例

由于 JSON 文件格式是文本格式，因此，一方面，它相当容易理解，但另一方面，它可能变得十分复杂，特别是当我们的工作流变得复杂时，更是如此。尽管 Onshape 会通知您文档的语法和格式中存在的一些错误，但这不可靠，许多选项尽管合法，但仍然可能导致您的工作流失败。

有关如何设置和使用多个 Onshape 工作流程的详细说明，请参见创建自定义发布工作流程主题。

根据贵组织的需求自定义 JSON

首先，我们来了解 JSON 是什么。JSON 表示 JavaScript Object Notation。它是用于存储和传输数据的轻量级格式。JSON 通常用于将数据发送到服务器和网页以及从服务器和网页发送数据。JSON 格式是“自说明性”，易于理解。

JSON 基于两种结构构建：

  • 名称/值对的集合。在不同语言中，这被视为对象、记录、结构、目录、哈希表、键列表或关联数组。
  • 值的顺序列表。在大多数语言中，这被视为一个数组、矢量、列表或顺序。

这些是通用数据结构。几乎所有现代编程语言均以某种形式或另一种形式支持它们。使与编程语言可交换的数据格式也基于这些结构很有意义。

在 JSON 中，结构采用以下格式：

对象 是未排序的一组名称/值对。对象以左花括号“{”开头，以右花括号“}”结束。每个名称后面都有一个冒号“:”，名称/值对由逗号“,”分隔。

以下代表您将在 Onshape 工作流 JSON 中看到的内容。此示例定义员工对象：一个包含 3 条员工记录的数组（对象）：

{
"employees":[
{"firstName":"John", "lastName":"Doe"}，
{"firstName":"Anna", "lastName":"Smith"}，
{"firstName":"Peter", "lastName":"Jones"}
]
}

Onshape JSON 格式

在 Onshape 中，JSON 文件中有 4 个对象，如下所述：

  • 选项 - 定义版本设置
  • 特性 - 设置属性定义
  • 状态 - 控制节点定义
  • 转换 - 指定链接定义

发布设置是一组 10 个与文档发布相关的可能设置。所有这些设置均位于“公司/Enterprise 设置”的“发布管理”页面中，但是，JSON 工作流程文件中的定义将替代在“公司/Enterprise 设置”中定义的任何相应发布管理设置。

属性定义是在“发布候选”对话框中显示的属性。这些属性可以指定给工作流程中的一个或多个节点，可以是不同类型、强制性或可选，且可以包含默认值，例如“零件编号”。

节点定义用于定义工作流程中包含的节点的类型，以及哪些属性指定给节点。例如，“暂定”或“已发布”。

链接定义是在转换过程中可发生的自动化操作。它们不仅将节点连接在一起，而且定义在此特定转换中哪些属性显示在发布候选中。例如，向指定给下一项操作的用户发送电子邮件通知。

以下部分详细介绍了 Onshape 工作流文档中的不同部分以及不同属性的所有可能选项。

定义工作流 JSON

“选项”部分

JSON 文件的第一部分使工作流程具有管理发布条件的唯一设置。可以在“公司/Enterprise 设置” -→ “发布管理”页面上找到所有这些设置。请记住，在 JSON 工作流程中定义的设置会替代“发布管理”页面中的设置。

以下“选项”对象定义所有可能的名称/值对，但是，其中任何项均为可选。如果未定义，默认情况下将使用在“版本管理设置”页面上定义的值。例如：

"options": {
"revisionSchemeId": "5851740138fa98150a8f953e"，
"requireApprover": true，
"requireAllApprovers": true，
"disallowCreatorAsApprover": true，
"requireNote": true，
"autoObsolete": false,
"errorOnFeatureListErrors": true，
"errorOnRolledBack": false，
"errorOnAssemblyErrors": false，
"errorOnDrawingOutOfDate": true,
"errorOnAssemblyRefsOutOfDate": true,
}

以下部分详细介绍了其中每个选项。

revisionSchemeId

从“公司/Enterprise 设置”的“版本管理”页面中获取的唯一 ID。在下拉列表中选择修订方案类型，然后复制后续修订方案 ID 并插入到 JSON 的此字段中。

Onshape 提供不同类型的修订方案。它们可以是：

  • 按字母顺序
  • 数字
  • 自定义

许多组织将在预生产工作流程中使用数字方案，然后转换为基于 Alpha 的方案以用于后工程发布和更改流程。选中此选项将使工作流程替代发布设置中定义的默认值，并使用数字或基于 Alpha 的修订方案。

修订和零件编号设置

单击“复制到剪贴板”按钮，以便您可以在 JSON 工作流中使用相应的修订方案 ID。

requireApprover

在设置为“true”时，此选项可使“发布候选”对话框上的“审批者”输入框变为强制性输入框。此输入框与“发布管理设置”中的“在发布对话框中需要审批者的核准”直接相关。

requireAllApprovers

在许多工作流程中，组织中的不同组或人员可能需要平行审批。将此选项设置为“true”需要将所有组或人员指定为审批者以审批工作流程，然后才可以移至下一节点。

如果工作流程被任何审批者拒绝，它将立即移至“已拒绝”状态。

如果将此选项设置为“false”，则一个定义的组或人员接受发布以移至下一节点变已足够。在这种情况下，仅需要一个批准。

“创建发布候选”对话框，显示需要提供“发布名称”、“发行说明”和“审批者” 

disallowCreatorAsApprover

在许多组织中，启动版本流程的人员不能与批准版本流程的人员是同一人。当设置为“true”时，此选项可强制实施此策略，并禁止候选版本的创建者批准候选版本。

requireNote

在设置为“true”时，此选项会强制实施以下政策：在工作流程的每个阶段必须填充“注释”输入框。这表示工作流程的启动者必须输入发布注释，并且核准（或拒绝）该工作流程的每个人员必须输入评论。对话框中的发布注释输入框为必填输入框，如上图所示。

autoObsolete

将此选项设置为“true”会导致在发布给定条目的新修订时该条目的早期修订立即淘汰。Onshape 允许多个发布版同时处于活动状态，但有些组织要求在任何给定的时间仅零件、装配体或工程图的一个发布版处于活动状态。

以下四个选项与要发布文档的错误相关。对于每个选项，当版本条目中满足相应条件时，将该选项设置为“true”会在该条目中创建错误，并禁止提交候选版本。如果将该选项设置为“false”，在该条目中将仍存在警告，但仍然可以提交版本。

将这些选项设置为“true”会禁止提交候选版本。这些设置将替代在“公司/Enterprise 设置”→“版本管理”页面中定义的默认行为。

errorOnFeatureListErrors

如果在特征列表中存在任何错误，此选项可禁止发布零件。

errorOnRolledBack

如果 Part Studio 中的回滚栏不在特征列表的末端，此选项可禁止发布零件。

errorOnAssemblyErrors

如果部件包含任何错误，此选项可禁止发布此部件。

errorOnDrawingOutOfDate

如果工程图的版本不是最新的，此选项可禁止该版本。

“特性”部分

特性是可添加到“候选版本”对话框的属性。这些属性可以属于不同类型，具有默认值，并且可设置为强制性或可选。

以下是在 Onshape 工作流 JSON 文件的特性中定义的不同属性的示例。

"properties": [
{
"name": "Compliance Approval"，
"propertyId": "comp_app"，
"valueType": "USER"，
"defaultValue": [
"5e5d30bbc7dcaf1000b61484"
]
},
{
"name": "Observers"，
"propertyId": "observers"，
"valueType": "USER"
},
{
"name": "Rejection Reason"，
"propertyId": "rejres"，
"valueType": "STRING"
},
{
"name": "ECR"，
"propertyId": "ecr"，
"valueType": "STRING"，
"defaultValue": ""
},
]

此部分详细介绍了可用于特性对象的不同属性及其值。

名称

名称特性的值可以是任何字符串。此属性显示在“发布候选”对话框中各自输入框的上方，如下所示：

显示“发布候选”对话框中名称属性值的示例 

propertyId

propertyId 值可以在 JSON 关联环境中定义为唯一字符串。此值在其他对象中用于定义哪些属性将在工作流中的哪个阶段可用。

建议定义对您有意义的特性 ID，以便以后可以轻松参考它，例如，使特性 ID 自解释，例如“rejection_reason”或“Engineering_approver”。

特性 ID 必须唯一（且不得与 Onshape 的硬编码名称、说明或零部件特性 ID 一致）。

valueType

此属性的值定义要在“发布候选”对话框中显示的输入框的类型。可在此处使用的值类型为：

  • 用户 - 创建可在其中选择用户、团队和角色的输入框。此类型的属性的默认值必须为一组用户、团队或角色 ID。
  • STRING - 正常的文本输入框。
  • INT - 整数值（整数）。
  • DOUBLE - 十进制值。
  • DATE - 提供数据选择控制。
  • ENUM - 提供选择控件，其预填充定义的值，用户可以从其选择一个值。使用此类型的属性还必须提供输入框的值列表。以下是 ENUM 格式的示例：
{
"name": "Inventory Disposition: (Scrap, Return to Supplier (RTS), Rework, Use As Is)",
"propertyId": "disposition"，
"valueType": "ENUM"，
"enumValues": [
{
"value": "Scrap"
},
{
"value": "Return to Supplier (RTS)"
},
{
"value": "Rework"
},
{
"value": "Use As Is"
}
],
"defaultValue": "Use As Is"
},
defaultValue

defaultValue 提供使用其预填充要定义的输入框的值。此处定义的值必须与 valueType 属性中选择的输入框类型相匹配。

对于 USER 类型的特性，默认值必须是用户/团队/角色 ID 的列表，如下所示。对于所有其他类型，它是单个值（数字或字符串）。

“valueType”: “USER”，
"defaultValue": [
"5e5d30bbc7dcaf1000b61484"，
"5e5d30bbc7dcaf99634a82219"
]

可以在“公司/Enterprise 设置”的“用户”或“团队”页面中找到用户和团队 ID。在用户或团队上单击鼠标右键，并从关联菜单中选择“编辑”选项，然后使用 ID 输入框旁边的“复制到剪贴板”按钮复制值。

“编辑用户”对话框的示例，“用户 ID”输入框旁边有“复制到剪贴板”选项

“状态”部分

状态定义工作流程中的实际节点，即发布套件在发布流程中移动的状态。当套件到达这些状态节点时，将会被指定在“名称”特性中定义的状态，如下所示：

以下是某些状态的示例：

"states": [
{
"name": "IN_PROGRESS"，
"displayName": "Create Engineering Release"，
"entryActions": []，
"exitActions": []
},
{
"name": "PENDING",
"displayName": "Project Admin Approval "，
"approverSourceProperty": "pr_appr"，
"editableProperties": [
"pr_appr"
],
"entryActions": [
{
"name": "markItemsPending"
}
],
"exitActions": []
}
]

名称

此属性用作状态节点的唯一标识符。它可以是任意字符串，只要在工作流中是唯一的即可。

“审阅发布”对话框中状态节点的唯一标识符的示例 

displayName

displayName 属性值是工作流图中显示的名称。它可以是说明该节点是什么的任何字符串。根据工作流的复杂性，多个状态可能具有相同的显示名称，即使其名称 (ID) 不同，也是如此。

approverSourceProperty

此特性表明“属性”对象中定义的哪个属性（如果有）将用作状态的审批者。此特性的值必须是 USER 类型属性的 propertyId。该属性中的用户和团队将会收到发布进度的通知，并且必须批准该发布，才能移出该状态。

属性 状态 
{
"name": "Compliance Approval",
"propertyId": "comp_app",
"valueType": "USER"
}
 
{
"name": "PENDING",
"displayName": "Compliance Approval",
"approverSourceProperty": "comp_app"
}
 

notifierSourceProperty

与 approverSourceProperty 类似，此属性是 USER 类型特性的 propertyId，用于定义当工作流达到此状态时将通知谁（如果有）。这与用户或用户组相同，他们可能遵循版本，但不一定参与其中。

entryActions
和 
exitActions

Onshape 工作流使某些预定义的操作在工作流中的特定点执行。这些操作可能更新条目的元数据，或者向利益相关者发送通知。当版本进入或退出某一状态时，将会发生状态进入和退出操作。

此文档的“操作”部分中详细介绍了操作。

editableProperties

此特性允许定义可在工作流程的此阶段编辑的属性列表。此特性的值必须是在工作流程中定义的属性的 propertyId 列表。

属性对象和状态对象及其关系的示例 

requiredProperties

此属性定义一列强制性的属性值，并且必须填充，版本才能退出此状态。与 editableProperties 一样，此属性的值是一列  propertyIds。

如果 propertyId 标记为必填，它会自动变为可编辑。

requiredItemProperties

自定义特性设置，选择了“大小”属性

此属性是元数据属性 ID 的列表（它位于“公司/Enterprise 设置”的“自定义特性”页面中，不是工作流程属性），必须在发布候选中的每个条目上填充，才能继续。若要获得属性 ID，请双击“自定义特性”页面上的属性，并使用 ID 输入框旁边的“复制到剪贴板”按钮。您必须是公司管理员，才能执行此操作。

以下是使用自定义特性的状态对象的示例：

{
"name": "PENDING",
"displayName": "Project Admin Approval "，
"approverSourceProperty": "pr_appr"，
"editableProperties": [
"pr_appr"
],
"entryActions": [
{
"name": "markItemsPending"
}
],
"exitActions": []，
"requiredItemProperties" : [
"5d655b8dbce891151cf7d9d9",
"5d0be2b3374eae12dd6eda1c"
]
}

“转换”部分

转换是将状态连接在一起。当用户在版本对话框中单击“提交”或“批准”等按钮时，它们处理状态与所发生事件之间的交互。

以下是转换对象的示例。

{
"name": "ADVANCE_TO_QA_APPROVAL"，
"displayName": "Advance"，
"type": "APPROVE"，
"uiHint": "success"，
"sourceState": "PENDING_OPERATIONS_APPROVAL"，
"targetState": "PENDING_QA_APPROVAL"，
"actions": [
{
"name": "sendUserNotifications"
},
{
"name": "sendEmailNotifications"
}
]
}

以图形方式表示为：

状态和转换的图形表示

以下内容详细介绍了转换对象中可用的选项，并展示转换与状态相关的方式。

名称

这应该是唯一说明性名称，可帮助您轻松识别此转换对象的用途，而不必查看该对象的起始和结束位置。在更复杂的流程中，将有许多转换，甚至更多状态 - 这会造成 JSON 非常长且可能引起混淆。通过使用说明性名称，您可以简化 JSON，并帮助消除错误。

displayName

displayName 是在工作流图上显示的值。如上所示，转换显示名称定义为“Advance”。显示名称除了应该具有说明性且表示转换外，没有其他特定的规则。

类型

它定义状态之间的转换的类型。有三种可能的类型，如下所示：

  • 提交
  • 批准
  • 拒绝

第一次转换始终为一种类型，即“提交”，后续转换应为类型“批准”或“拒绝”。

以下部分详细介绍了每个类型选项：

  • 提交
    • 退出设置，然后进入工作流程时，在发布中执行各种“初始化”，例如在发布中启动已配置零件的缩略图生成，连接链接的文档/版本 ID 等。
    • 只有发布创建者才能执行 SUBMIT 转换。
    • 应从初始状态外转换为 SUBMIT。
    • 不是初始转换的提交不具有任何特殊功能。
  • 批准
    • 将用户标记为已批准候选版本（在“版本”对话框中将标记变为绿色）
    • 如果将公司策略设置为“需要所有审批者的核准”，则直到所有审批者均已核准，才会执行转换。
    • 生成条目的装配体/工程图内容参考。
    • 只允许一种状态转换为此类型。
    • 只有当前状态（或管理员）的审批者才能批准。
  • 拒绝
    • 将用户标记为已拒绝候选版本（在版本对话框中将标记变为红色）。
    • 只有当前状态（或管理员）的审批者才能拒绝。

uiHint

此项目定义图形显示中下一个节点的颜色，以及在“版本”对话框中相应的按钮。这些是当前可用于此属性的三个值，它们是 Bootstrap UI 样式：

  • “primary” – 蓝色
  • “success” – 绿色
  • “danger” - 红色

sourceState
& 
targetState

sourceState 属性是从其启动此转换的状态对象的名称。targetState 属性是转换要到达的状态对象的名称。

为了提供连贯性和减少可能的错误，命名非常重要；由于此原因，强烈建议将说明性名称用于状态对象。对于较大的工作流，可能很快变得复杂且容易出错。下图显示了状态对象和源与目标状态属性之间的映射。

状态对象和转换对象及其关系的示例 

操作

与状态一样，转换除了包含将发布候选移至下一状态的操作外，还包含执行的其他操作。此属性通过与状态的 entryActions 和 exitActions 属性相同的方式定义一组操作。转换的操作在源状态的 exitActions 和目标状态的 entryActions 之前执行。

“操作”部分

此部分详细介绍了可指定给“状态”和“转换”的操作。尽管其中大多数操作对于这两项是共同的，但有些操作在操作排序和放置位置方面有限制。

操作表示为具有单一属性“name”的 JSON 对象。

以下是有关进入或退出操作状态的示例：

{
"name": "PENDING_ENGINEERING_APPROVAL"，
"displayName": "Pending engineering approval"，
"approverSourceProperty": "engineers"，
"entryActions": [
{
"name": "markItemsPending"
}
],
"exitActions": []
}
在转换中，可以按如下所述定义它们：
"actions": [
{
"name": "sendUserNotifications"
},
{
"name": "sendEmailNotifications"
}
]

以下是当前可用的操作：

  • markItemsPending - 将发布中所有条目的元数据状态更改为“暂定”。此操作在淘汰工作流程中不受支持，且不能用于 markItemsRejected 或 releaseItems 操作之后。
  • markItemsRejected - 将发布中的所有条目的元数据状态更改为“已拒绝”。此选项在淘汰工作流程中不受支持，且不能用于 markItemsRejected 操作之后或 releaseItems 操作之前。
  • releaseItems - 将发布中的所有物项的元数据状态更改为“已发布”并为其创建修订（如果在公司策略或特定于工作流程的操作中指定了自动淘汰，将使其他修订自动淘汰）。此选项不适用于淘汰工作流程。
  • obsoleteItems - 将包中的所有条目的元数据状态更改为“淘汰”，从而使其相应的修订淘汰。此选项不适用于发布工作流程。
  • sendUserNotifications - 在 Onshape 通知面板中发送指示转换已发生的消息，包括打开发布候选的链接。仅转换支持此操作。
  • sendEmailNotifications - 发送包含链接的电子邮件通知，以在 Onshape 中打开发布候选。仅转换支持此操作。

Both of the above notification actions send notifications to the creator of the release candidate, as well as the approvers and notifiers of the source and target states (if any), as specified in those states’ approverSourceProperty and notifierSourceProperty attributes. For approvers, the notifications will contain a call to action to approve the release candidate.

提示与技巧

Onshape 工作流设计者可以帮助

如果您在 Onshape 中编辑 JSON，您将会看到工作流被表示为包含节点（阶段）和边（转换）的图形，当您更改 JSON 时，它会实时更新。编辑器将亮显 JSON 格式错误。

如果您具有首选编辑器，可以在该程序中编辑 JSON，然后上传到 Onshape。图形设计者仍然会亮显任何错误。

Onshape 工作流设计者将捕捉 JSON 格式错误以及某些类型的构造错误，例如无效 ID。但是，举例来说，它不会告知您使用了错误的转换类型 - 这就是测试很重要的原因！

使用说明性名称和 ID

当工作流变得更复杂时，将很难跟踪您用于不同对象的 ID，例如特性。在将状态对象与转换对象 sourceState 和 targetState 属性值连接时，这可能变得尤为复杂。

通过使用说明性且始终唯一的名称，您可以简化 JSON 和消除任何可能的错误。

拼写和大小写有影响

在 JSON 中，对象名称和属性名称以及某些值经过硬编码且区分大小写。例如，属性“sourceState”与“sourcestate”不相同。像这样的排印错误会导致工作流失败。

本主题自始至终使用正确的语法，您应从这里或者从 Onshape 提供的一个示例工作流复制并粘贴这些关键字。

测试您的工作流

在用于生产环境中之前，请在测试零件上运行您的工作流，并确保它工作。确保您在工作流中使用的版本首选项提供预期行为。

让在工作流中指定给不同阶段的组接受版本。

创建过时工作流

本主题介绍如何创建版本工作流。用于创建过时工作流的流程是相同的，但它没有 releaseItems 操作，而是在状态对象上具有 obsoleteItems 输入操作。在发布工作流时，请选择“过时工作流”单选按钮选项，而不是选择“发布”对话框中的“版本工作流”选项。这些工作流将显示在版本设置中的“过时工作流”选项卡下。

在过时工作流中，您可以通过此语法将条目标记为重新发布：

{
"name": "Mark revision as re-releasable",
"propertyId": "os-mark-rereleasable",
"valueType": "BOOL"
}

删除工作流

当前，即使您删除包含工作流 JSON 文档的 Onshape 文档，该工作流将仍然保留在版本设置中可用工作流的列表中 - 您可以取消选中该工作流，以便在创建候选版本时它不用于选择。尽管这不是最佳选项，但有一个创建测试工作流然后将其更新为发布版本的最佳做法。

包含工作流 JSON 文件的文档的行为方式与任何 Onshape 文档完全相同。这表示仅当您位于工作空间（通常为“主”）中时才能编辑该文档。您可以从工作空间发布工作流文档，这将创建该文档的版本。在发布时，您能够覆盖现有工作流。

此方法使您可以在发布满足贵组织需求的工作流之前，尝试不同的选项和工作流。