Administrators of enterprises can create customized release and obsoletion workflows specific to the enterprise needs. Onshape provides a JSON file of our release and obsoletion workflows as a starting place for customizing the workflow to suit your company's needs. You can also use our JSON as a starting point for creating your own JSON file.

This functionality is currently available only on browser.

Bear in mind that the currently selected release and obsoletion workflow (chosen by the administrator) governs newly created release candidates through the selected process. If you change the worfklow while a release is in-process, that release follows the workflow under which it was created. The newly selected workflow will govern only release candidates created after it was selected.

One more thing: Onshape customized workflows currently do not allow cyclical processes.

At this time, you are not able to delete a workflow, but you are able to add as many as you want to your workflow repertoire to select from. You are also able to replace an existing customized workflow, if necessary.

We recommend keeping all of your workflow definition files in one Onshape document for ease of access.

The customization process has these major steps, each explained in detail below:

  1. Download the Onshape default workflows to your hard drive or other easily accessible location.
  2. Create a new Onshape document and import the workflow files.
  3. Optionally customize a workflow with FeatureScript to update item properties upon some release action.
  4. Edit and publish the workflows.
  5. Optionally debug a customized worfklow.

Automatic transition for two-tiered workflowsCopy link

When you set up a custom release workflow that includes two tiers, and the second tier is not required (that is, the second tier is optional) Onshape will automatically transition from Pending to Released if there is no approver specified in the release package. No setup is required for this, the only requirements are that you have a two-tier workflow, the second tier is optional and there are no approvers specified in the Approver field in the release candidate.

Download the Onshape default workflowsCopy link

To download the Onshape default workflow files:

  1. Navigate to your Company/Enterprise settings and select Release management.
  2. Confirm that Enable managed workflows is checked, then click View in document.

    The workflow file opens in a public document in another tab.

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

    You can close that tab once the tab is downloaded.

Create a new Onshape document and import the workflow filesCopy link

  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 Plus sign icon at the bottom and select Import:

Import highlighted in menu

  1. Select the workflow file you just downloaded and click Open.
  2. Another tab appears in your document, with the name of the file you imported. Select that tab to open it:

Example of a custom workflow

Customize with FeatureScriptCopy link

You can use FeatureScript workflow actions to programmatically update properties on Release items as part of a workflow transition. By pointing the customized workflow at a Feature Studio in the same workspace as the workflow definition, a function in that Feature Studio can be executed as an action which determines the property updates to apply to each Release item.

To use this in a custom workflow, use the updateItemPropertiesFromFeatureScript workflow action as a transition action,or an an entry or exit action on a state. The action takes the parameters:

  • 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
}

The function must return a map of the form:

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

The main map is keyed by Release item ID, and the inner map is from metadata property ID to a desired new value. For example, if the function returns the following map:

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

Then on the Release item with ID “item1”, the “Title 1” property will be set to the string “New value”, and a hypothetical custom property (customIntProperty, above) will be set to the number 42. On the item with ID “item2”, the “Title 2” property will be set to the string “Some other value”.

The full release package information is provided as input to the function, so additional filtering and computation can be done as desired. For example, applying a property only to items that are drawings, or only to items that have a certain category, or computing a property value from some other property value.

It is important to note that the FeatureScript itself does not apply any changes to the release package; any modifications made to the input data will not survive the FeatureScript execution. Instead, it is the value returned by the function that tells the system what changes to make.

Edit and publish the workflowsCopy link

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

Edit the custom workflow according to the guidelines below:

  • As you edit, the diagram on the right will reflect the changes made in your JSON.
  • The diagram is dynamic and draggable, so if the structure does not reflect your intended workflow, use your cursor to adjust it.
  • Cyclical workflows are not allowed.
  • Once you are satisfied with your edits and want to make your workflow available for use in the enterprise, click to open the Publish custom workflow dialog:

Publish. . .

Publish custom workflow dialog

This dialog will alert you of any errors that may have to be fixed before publishing. (After you click Publish, if there are errors in your workflow code are displayed at the top of this dialog. Cancel the dialog, fix the errors and click Publish again to open this dialog). Once your workflow is error-free: provide a name, description, and workflow type. If this is a brand new workflow, not replacing another workflow, select None in the Replace workflow dropdown. If you wish to replace an already-existing workflow, select the one you wish to replace.

Click Publish.