カスタマイズしたリリースワークフローの作成
のみ使用可能
Enterprise の管理者は、Enterprise のニーズに合わせてカスタマイズしたリリースワークフローおよび廃止ワークフローを作成できます。Onshape では、当社のリリースワークフローおよび廃止ワークフローの JSON ファイルを、Company のニーズに合わせてワークフローをカスタマイズするための開始場所として提供しています。また、独自の JSON ファイルを作成するための始点として、当社 JSON を使用することができます。
現在選択されているリリースおよび廃止のワークフロー (管理者が選択) は、選択したプロセスを通じて新しく作成されたリリース候補を管理します。リリースが処理中であるときにワークフローを変更すると、そのリリースは作成されたワークフローに従います。新しく選択されたワークフローは、選択後に作成されたリリース候補のみを管理します。
もう 1 つの内容: Onshape カスタマイズワークフローでは、現在、循環プロセスを許可していません。
ワークフローを非公開にして、アクティブなワークフローリストから削除できます。
ワークフローのレパートリーに任意の数だけ追加して選択することができます。必要に応じて、既存のカスタマイズされたワークフローを置き換えることもできます。
アクセスを容易にするため、すべてのワークフロー定義ファイルを 1 つの Onshape ドキュメントに保存することをお勧めします。
カスタマイズプロセスには、次の主要な手順があります。各手順について以下に詳しく説明します。
- Onshape の既定のワークフローをハードドライブまたはその他の簡単にアクセスできる場所にダウンロードします。
- 新しい Onshape ドキュメントを作成し、ワークフローファイルをインポートします。
- オプションで FeatureScript を使用してワークフローをカスタマイズし、リリースアクション時にアイテムプロパティを更新します。
- ワークフローを編集して公開します。
- オプションで、カスタマイズしたワークフローをデバッグできます。
2 つの層を含むカスタムリリースワークフローを設定し、第 2 層は必須ではない (つまり、2 番目の層は任意) 場合、リリースパッケージに承認者が指定されていなければ、Onshape は [保留中] から [リリース済み] に自動的に移行します。これには設定は不要です。唯一の要件は、2 層ワークフローがあること、第 2 層は任意であり、リリース候補の [承認者] フィールドに承認者が指定されていないことです。
Onshape の既定のワークフローファイルをダウンロードするには、次の手順に従ってください。
- Enterprise 設定ページに移動し、[リリース管理] を選択します。
- [管理ワークフローを有効にする] がオンになっていることを確認し、[ドキュメントで表示] をクリックします。
ワークフローファイルは、別のタブのパブリックドキュメントで開きます。
- [ダウンロード] をクリックし、ファイルの新しい名前を入力します。
タブがダウンロードされたら、そのタブを閉じることができます。
- Enterprise で、[ドキュメント] ページに移動し、[ドキュメント] > [作成] を選択し、[OK] を選択します (この例では、ドキュメント名は Company カスタマイズワークフローです)。
- 新しいドキュメントで、下部にあるプラスアイコン をクリックし、インポートを選択します。
- ダウンロードしたワークフローファイルを選択し、[開く] をクリックします。
- ドキュメントには、インポートしたファイルの名前が付いた別のタブが表示されます。以下でそのタブを選択して開きます。
FeatureScript ワークフローアクションを使用すると、ワークフロートランジションの一部として、リリースアイテムのプロパティをプログラムによって更新できます。カスタマイズしたワークフローをワークフロー定義と同じワークスペース内の Feature Studio に向けると、その Feature Studio 内の機能を、各リリースアイテムに適用するプロパティの更新を決定するアクションとして実行できます。
これをカスタムワークフローで使用するには、updateItemPropertiesFromFeatureScript ワークフローアクションを移行アクションとして使用するか、状態に対する開始アクションまたは終了アクションとして使用します。アクションには次のパラメータがあります。
-
FeatureStudio ID - Feature Studio は、カスタマイズされたリリースワークフロー定義と同じワークスペースに存在する必要があります。
-
Feature Studio からエクスポートされた関数名 - この関数は、type: map をもつ単一の引数を取る必要があります。関数の実行時に関数に渡される Map 型には、次のデータが含まれます。
{
// すべてのアイテムとプロパティを含む、完全な詳細リリースパッケージ
// (GetReleasePackage REST API から返されるのと同様)
"releasePackage": BTReleasePackageInfo,
// The user performing the transition
"currentUser": BTUserSummaryInfo,
// リリース候補を最初に作成したユーザー
"releaseCreator": BTUserSummaryInfo,
// ワークフロー定義の表示どおりに実行中のトランジション
"transition": BTTransitionDef,
// 現在の UTC 日付/時刻を ISO 日付文字列で指定します
"currentDate": string
}
この関数は次の形式のマップを返す必要があります。
{[key: 文字列]: {[key: 文字列]: 任意}}
メインマップは Release アイテム ID でキー設定され、内部マップはメタデータプロパティ ID から希望する新しい値になります。たとえば、関数が次のマップを返すとします。
{
"item1": {
"57f3fb8efa3416c06701d616": "New value",
"customIntProperty": 42
},
"item2": {
"57f3fb8efa3416c06701d617": "Some other value"
}
}
ID が「item1」のリリースアイテムでは、「Title 1」プロパティが「新しい値」という文字列に設定され、仮定のカスタムプロパティ (上記の customIntProperty) は数値 42 に設定されます。IDが「item2」のアイテムでは、「Title 2」プロパティが「その他の値」という文字列に設定されます。
リリースパッケージの完全な情報は関数への入力として提供されるため、必要に応じて追加のフィルタリングと計算を行うことができます。たとえば、図面であるアイテムにのみプロパティを適用したり、特定のカテゴリを持つアイテムにのみプロパティを適用したり、他のプロパティ値からプロパティ値を計算したりします。
FeatureScript 自体は、リリースパッケージに変更を適用しないことに注意してください。入力データに加えた変更は FeatureScript の実行後は存続しません。代わりに、関数によって返される値によって、システムにどのような変更を行うかを伝えます。
返されるマップの値の型は、対応するメタデータプロパティの値型と一致する必要があります (“update metadata” API に送信されるため)。値が無効な場合は、プロパティの更新に失敗します。
User-type メタデータプロパティは、次の形式のオブジェクトの配列を受け入れます。
{"id": [userId]}
User-type のワークフロープロパティには、ユーザー ID が「entryID」フィールドにあるオブジェクトの配列が含まれます。したがって、ワークフロープロパティからメタデータプロパティにユーザーを追加するには、値を正しい形式に変換する必要があります。
User-type メタデータプロパティはユーザー ID のみを受け入れ、チーム ID やロール ID は受け付けません。User-type ワークフロープロパティを User-type メタデータプロパティに適用するには、ワークフロープロパティ内のユーザーであるエントリ (「entryType」が 0 のユーザー) のみを使用します。
PropertyID または返されたオブジェクトの値が正しくないためにプロパティの更新が失敗すると、ワークフローアクションが失敗し、ワークフロー開発者がデバッグで使用できるように失敗がログに記録されます (後述のワークフローのデバッグを参照)。
FeatureScript の実行中にエラーが発生した場合や、返されたオブジェクトの形式が正しくない場合にもアクションは失敗します。たとえば、返されたオブジェクトが、アイテム ID をプロパティの更新にマッピングしていない場合などです。
アクションが失敗した場合は、システムのバグではなく、ワークフローの FeatureScript のバグが原因である可能性があります。この場合、HTTP 応答とともにエラーメッセージが返され、ワークフロー管理者に連絡するようユーザーに指示されます。ワークフロー開発者は、ワークフロー監査ログを使用して障害を特定し、デバッグできます (下記のワークフロー監査ログを参照)。必要に応じて、ワークフロー開発者は Onshape でサポートチケットを作成できます。
これは Onshape Enterprise の新しいグローバル権限で、カスタマイズされたリリースワークフローの公開とデバッグが可能になります。この権限を持つユーザーはワークフローを公開でき、リリース候補をデバッグモードで作成するオプションが常に与えられます (後述のワークフローのデバッグを参照)。
循環ワークフローは許可されていません。
ワークフローを公開できるのは、「ワークフローの管理」グローバル権限を持つユーザーだけです。グローバル権限についての詳細は、グローバル権限の理解を参照してください。
以下で説明するように、カスタムワークフローを編集します。
- JSON ワークフローファイルを編集します。編集すると、右側の図に変更が反映されます。
- 図は動的でドラッグ可能であるため、構造に目的のワークフローが反映されない場合は、カーソルを使用して調整します。
- 編集内容に満足し、ワークフローを Enterprise で使用できるようにするには、[公開] をクリックして [カスタムワークフローを公開] ダイアログを開きます。
公開前に修正が必要なエラーがあると、ダイアログの上部に警告が表示されます。
[キャンセル] をクリックしてダイアログを閉じます。
エラーを修正します。
もう一度 [公開] をクリックしてダイアログを開きます。
-
[名前]、[説明]、[ワークフロータイプ] を入力します。
-
[ワークフローを置き換える] ドロップダウンで、次のいずれかを実行します。
-
これが新しいワークフローの場合は、[なし] を選択します。
-
既存のワークフローを置き換えるには、置き換えたいワークフローを選択します。選択した代替の [名前] フィールドと [説明] フィールドには自動的に入力されます。既存の値をそのまま使用することも、新しい値を入力することもできます。
-
-
パブリッシュ をクリックします。
ワークフローが非公開になると、次のことが起こります。
-
このワークフローをリリース管理で使用して新しいリリースパッケージを作成することはできなくなりました。
-
このワークフローを使用するすべての設定が、Onshape の既定のワークフローにリセットされます
-
削除されたワークフローに現在あるリリース/廃止候補は、引き続き正常に機能します。非公開のワークフローを使用する既存のリリースパッケージと提出済みのリリースパッケージは影響を受けません。カスタムワークフローを使用して既存のリリースパッケージを開いて表示し、廃止したり、保留中のリリースを移行したりすることは引き続き可能です。
ワークフローを非公開にできるのは、ワークフローの管理権限 ([Enterprise 設定] > [グローバル権限]) を持つユーザーのみです。
ワークフローを非公開にするには:
-
名前またはアカウントユーザーアイコン () をクリックします。[ドキュメント] ツールバーの右上にある [Enterprise 設定] > [リリース管理] を選択します。
-
ワークフローのドロップダウンから、非公開にするリリースワークフローを選択します。
-
ワークフロードロップダウンの右側にある [ドキュメントで表示] リンクをクリックします。ワークフロードキュメントが現在のブラウザタブで開きます。
-
ドキュメント上部にある [非公開] ボタンをクリックします。
-
[ワークフローを非公開にする] ダイアログが開くので、[非公開] ボタンをクリックします。
既定のワークフローを非公開にすると、既定のワークフローは Onshape の既定にリセットされます。
「ワークフローの管理」グローバル権限を持つユーザーは、デバッグモードを使用して開発中のワークフローをテストできます。
このワークフローは、パーツ/アセンブリのリリース時に [リリースワークフローを選択] ダイアログで使用できるように、先に公開しておく必要があります (新しいワークフローに問題がなければ、Enterprise 設定に戻り、ワークフローをアクティブにできます)。
公開された一般的なワークフローは、ワークフロー定義が保存されているドキュメントのバージョン (JSON ファイル) をポイントします。公開されたワークフローを使用しているリリースは、そのバージョンで定義されているワークフローに従います。デバッグモードでは、公開されたバージョンに関連付けられているドキュメントワークスペースに存在するワークフローが使用されます。ワークフローは、公開されたバージョンの上にワークスペースが 1 つだけ存在する場合にのみデバッグモードで開始されるため、あいまいさが解消されます。
デバッグモードでは、ワークフロー開発中のイテレーションを高速化できます。ワークフローが期待どおりに機能しないことがわかった場合は、ワークスペースの新しいアクションで使用するワークフロー JSON または Feature Studio を変更できます。新しいリリースをすぐに開始すると、ワークフローの開発者は、新しいバージョンのワークフローを先に公開しなくても効果を確認できます。
ワークフローをデバッグするには:
-
[デバッグモード] ボックスをオンにします (上の図を参照)。
-
[OK] をクリックします。
-
このダイアログでは、右上隅のオーバーフローメニューボタン ()、[監査ログの表示] の順に選択して、ワークフローオブジェクトとその重要なイベント (作成や移行など) の監査証跡を表示できます。
-
また、[ワークフローを表示] を選択して、ワークフローを図として表示し、下図のように最後の状態を強調表示することもできます。
ワークスペースでデバッグモードのワークフローに加えた変更は、既に進行中のリリースには影響しません。デバッグリリースは作成時にワークスペースのマイクロバージョンにロックされます。変更の結果を確認するには、新しいリリースを作成する必要があります。この手順により、ワークフロー定義の変更によって進行中のリリースが壊れたり破棄されたりするのを防ぎます。
カスタムワークフローを公開したら、必要に応じて属する Enterprise 内で複数のアクティブなワークフローを有効にできます。複数のアクティブなワークフローをユーザーが使用できる場合、ユーザーはリリース候補の作成時に使用するワークフローを選択できます。
管理者は、使用するワークフローと適用される条件についてユーザーを教育する責任があります。
複数のワークフローを有効にするには、次の手順に従います。
- 上記の手順に従って、複数のカスタムワークフローを作成し、Onshape で公開します。
- Enterprise 設定の [リリース管理] ページで、[管理対象ワークフロー] セクションでカスタムワークフローの [アクティブ] ボックスをオンにしてアクティブにします。
-
ワークフロープレビューアイコン () をクリックすると、ワークフローを示す図のドロップダウンが展開されます。図の下には、現在のワークフロープロセスの説明が表示されます。
- [リリース設定を保存] をクリックして、Enterprise のリリース管理設定に加えた変更を保存します。
ユーザーがリリース候補を作成すると、その時点で (ドロップダウンから) ワークフローを選択する機会が与えられます。
リリースワークフローまたは廃止ワークフローをカスタマイズするための構文を以下に示します。大文字化が重要であることに注意してください。
次のルールに留意してください。
形式
- name: 文字列
- propertyId: 文字列
- valueType: string|ENUM
- defaultValue?: 任意
- usersOnly?: ブール演算
- teamsOnly?: ブール演算
- enumValues?: list
制限事項
- プロパティ ID は一意である必要があります (Onshape のハードコードされた名前、説明、またはコメントプロパティ ID と一致しないことも必要です)
- valueType は BTMetadataValueType の名前である必要があります (BLOB と OBJECT を除く)
- valueType が ENUM の場合、enumValues を指定する必要があります。また、プロパティには 1 つまたは複数の enumValues が含まれる必要があります。各 enumValues には、必須の value 要素が必要です。label 要素はオプションです。
- defaultValue が指定されている場合は、enumValues の 1 つの値フィールドと一致する必要があります。
- UsersOnly と teamsOnly は相互に排他的であり、USER プロパティに対してのみ有効です。
- DefaultValue (存在する場合) は、ValueType で示される正しいタイプと一致する必要があります
- STRING: 文字列
- BOOL: ブール演算
- INT: 整数
- DOUBLE: 十進数
- USER: 文字列 []
- DATE: ISO 日付文字列
- BLOB と OBJECT は現在サポートされていません
- USER タイプのプロパティ値は、ユーザー、チーム、ロール ID のリストです
形式
- name: 文字列
- displayName: 文字列
- approverSourceProperty?: 文字列
- notifierSourceProperty?: 文字列
- entryActions?: アクション []
- exitActions?: アクション []
- editableProperties?: 文字列 []
- 値には以下が含まれます。
承認者
オブザーバー
- 値には以下が含まれます。
- requiredProperties?: 文字列 []
- requiredItemProperties?: 文字列 []
制限事項
- 名前は一意である必要があります
- approverSourceProperty および notifierSourceProperty が存在する場合は、ワークフローのプロパティ ID であり、USER タイプのプロパティを指す必要があります。
- 1 つの状態では、承認者として特定のプロパティを使用できます。
- 任意の数の状態は、その通知者として指定されたプロパティを使用することができます。
- editableProperties と requiredProperties は、同じワークフロー内のプロパティ ID である必要があります。
- requiredItemProperties は、Company の有効なメタデータプロパティ ID である必要があります (OnShape の組み込みプロパティまたはカスタムプロパティ。計算されたプロパティを除く)。
ID の詳細は、プロジェクトロールおよびアクセス権管理とその管理についてを参照してください。
形式
- name: 文字列
- displayName: 文字列
- type: 文字列
- sourceSestate: 文字列
- targetState: 文字列
- uiHint?: string (default: "primary")
- actions?: アクション []
- requiredProperties?: 文字列 []
制限事項
- 名前は一意である必要があります。
- タイプは、SUBMIT、APPROVE、または REJECT のいずれかである必要があります
- sourceState と targetState は、ワークフロー内の 2 つの異なる状態である必要があります。
- 任意のソース状態からの APPROVE タイプのトランジションが、最大 1 つあります。
- APPROVE タイプのトランジションの場合、SourceState には approverSourceProperty が必要です。
- uiHint が存在する場合、「プライマリ」、「成功」、または「危険」のいずれかである必要があります (これらはリリースダイアログのボックスやその他のエンティティの色であり、Onshape によってハードコードされています)。
トランジションタイプ
送信
- リリースで構成されたパーツのサムネイル生成の開始、リンクされたドキュメント ID やバージョン ID の接続など、セットアップからワークフローに移行する場合に、リリースでさまざまな「初期化」を実行します。
- SUBMIT トランジションを実行できるのは、リリース作成者だけです。
- 初期状態からのトランジションは、[送信] にする必要があります。
- 初期トランジションでない送信には特別な機能はありません。
承認
- ユーザーを承認済みとしてマークします (リリースダイアログでトークンが緑に変わります)。
- Company のポリシーを [すべての承認者からの承認が必須です] に設定している場合、すべての承認者が承認するまでトランジションは行われません。
- アイテムのアセンブリコンテンツまたは図面コンテンツ参照を生成します。
- この種類のトランジションは 1 つの状態から許可されます。
- 承認できるのは、現在の状態の承認者 (または管理者) だけです。
拒否
- 拒否したとしてユーザーをマークします (リリースダイアログでトークンが赤に変わります)。
- 拒否できるのは、現在の状態の承認者 (または管理者) だけです。
形式
- name: 文字列
- params?: {[key: 文字列]: 任意}
制限事項
- 名前は、事前定義済みのアクション名のいずれかに一致する必要があります (下記の許可されたアクションを参照)
- アクションの中には、状態またはトランジションでのみ許可されるアクションもあれば、順序の制限事項があるものもあります。
許可されたアクション
- sendEmailNotifications - トランジション (モバイルプッシュ通知を含む) のメール通知を送信します。
- 許可: トランジションのみ
- パラメータ: なし
- sendUserNotifications - トランジションについてユーザー通知を送信します。
- 許可: トランジションのみ
- パラメータ: なし
- markItemsPending - リリース内のすべてのアイテムのメタデータの状態を保留に変更します。
- 許可: 状態またはトランジション
- パラメータ: なし
- 廃止ワークフローでは許可されません。
- リリースワークフローで、markItemsReleased または markItemsRejected の後に実行できません。
- markItemsRejected - リリース内のすべてのアイテムのメタデータの状態を [拒否済み] に変更します。
- 許可: 状態またはトランジション
- パラメータ: なし
- 廃止ワークフローでは許可されません。
- リリースワークフローで、markItemsReleased 後または markItemsPending の前ではできません
- releaseItems - リリース内のすべてのアイテムのメタデータの状態を [リリース済] に変更し、それらのリビジョンを作成します (Company ポリシーで指定されている場合、他のリビジョンは自動的に廃止されます)。
許可: 状態またはトランジション
パラメータ: なし
廃止ワークフローでは許可されません。
- obsoleteItems - パッケージ内のすべてのアイテムのメタデータの状態を [廃止] に変更し、対応するリビジョンを廃用します。
- 許可: 状態またはトランジション
- パラメータ: なし
- リリースワークフローでは許可されません
- UpdateItemPropertiesfromFeatureScript - これを使用して、FeatureScript のフィーチャーをトランジションアクションとして、または状態のエントリアクションまたは終了アクションとして使用します。
- 状態またはトランジションで許可されます
- パラメータマップ (この型を持つ単一の引数)
カスタムワークフローを定義するときに、[Enterprise 設定] > [リリース管理] ページで定義されている特定の Enterprise リリース設定を上書きするように設計されたオプションセクションを含めることができます。これらのオーバーライドオプションについて以下に説明します。
"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": (リリースダイアログのリリースノートラベルまたはオブセレクションの注記を上書きします)
}
このセクションとすべてのフィールドはオプションです。Company 設定を上書きしたいサブセットはどれでも選択できます。コードに含まれていないフィールドは、既定で Enterprise 設定の仕様になります。
リビジョンスキーマ ID は、Enterprise 設定 > リリース管理ページの読み取り専用テキストボックスから取得できます。
すべてのワークフローオブジェクトは、作成や移行など、存続期間中の重要なイベントの監査証跡を作成します。このログは、次を使用して取得できます:
GET /api/workflow/obj/<object id>/auditlog
問題の検査とデバッグを行うために、リリースのリンクからそのコールの出力を表示できます。
監査ログのレスポンスには、オブジェクトワークフローに関する基本情報 (公開されたワークフローのバージョンやデバッグモードのワークフローかどうかなど) と、オブジェクトワークフローに対してログに記録されたすべてのイベントが含まれます。
各ログエントリには以下が含まれます。
-
タイムスタンプ
-
型 (btWorkflowAuditEntryType 序数である整数で表される)
-
イベント発生時のワークフローの状態、遷移、アクション。
また、必要に応じて、イベントタイプ固有の情報を追加するためのフィールドもいくつかあります。
監査イベントには次の種類があります。
-
オブジェクトが作成されました - オブジェクトが作成されると、そのオブジェクトについて最初に記録されるイベントです。
-
オブジェクトが破棄されました - オブジェクトに対して特別な破棄アクションを実行した場合。
-
オブジェクトが削除されました - オブジェクトが削除されたとき。通常は、クリーンアップサーバーの設定で古いとみなされたことが原因です (削除されたオブジェクトの監査ログは削除されません)。
-
プロパティが更新されました - オブジェクトのワークフロープロパティを変更したとき。これは、たとえばリリースパッケージの package-level プロパティの場合です。個々のアイテムのメタデータプロパティは含まれません。
-
これには、変更された (ワークフロー定義の) プロパティ ID (古い値と新しい値を含む) が含まれます。
-
-
コメントを追加しました - 新しく追加されたコメントの ID が含まれます。
-
ユーザーを承認しました - ユーザーが現在の状態に対して承認アクションを実行したとき。これは、会社のリリース設定に応じて、トランジションを伴う場合と伴わない場合があります。
-
これには、アクションが実行された承認者リストのユーザー、チーム、ロール ID が含まれます。つまり、承認されたユーザーの代理です。
-
-
ユーザーが拒否しました - ユーザーが現在の状態に対して拒否アクションを実行した場合。
-
これには、アクションが実行された承認者リストのユーザー、チーム、ロール ID が含まれます。つまり、拒否されたユーザーの代理です。
-
-
移行開始
-
トランジションが完了しました
-
移行に失敗しました - エラーメッセージまたはサポートコード (該当する場合) が含まれます。
-
アクションが開始されました
-
アクションが完了しました
-
アクションが失敗しました - これには、エラーメッセージまたはサポートコード (該当する場合) が含まれます。
-
FeatureScript を実行しました - これには、FeatureScript 実行からのコンソール出力が含まれます。
-
これには、FeatureScript の実行によって返された通知も含まれます (例外が発生した場合は例外も含まれます)。
-
FeatureScript 関数から返された値が含まれます。
-
-
アイテムメタデータの更新に失敗しました - リリースパッケージアイテムメタデータの更新リクエストが移行中に失敗した場合。
-
これには、失敗したメタデータプロパティ ID、失敗したアイテムのメタデータ href、およびエラーメッセージが含まれます。
-
FeatureScript アクション中に発生する場合を除き、通常はトランジションが失敗します。組み込みのアクションは正常に実行する必要がありますが、FeatureScript から追加のプロパティを設定すると、移行の続行が許可されている間は失敗することがあります。
-