Configuring Arena and Onshape

Users and permissions

The required users and their permissions in each product are:

• Onshape - Enterprise Administrator

• Arena - Arena Administrator

The Onshape and Arena Administrator accounts configuring the connection must use the same email and have a full Arena user license with Arena workspace read and write permissions. Logging into the target Arena workspace at least once is required, prior to configuration.

The Onshape Administrator and Arena Administrator do not have to be the same person.

Configuration process

This process is performed by the Onshape Enterprise Administrator:

1. In Onshape, navigate to the Enterprise settings page, then select the Arena tab from the menu on the left.

2. In the page that appears to the right of the menu, enter the following information:

   1. Check the Enable Onshape Arena connection checkbox.

   2. Enter the Arena Workspace ID.

   3. Skip the Arena Workspace name: This read only field is populated upon successful connection once the Save changes button is clicked.

   4. Enter the API web token acquired from Arena Support.

   5. Enter the Arena API URL (as supplied by the steps outlined in the Arena Workspace configuration process.

   At this point Onshape contacts Arena with the supplied credentials and activates a log in to Arena. Upon successful connection, the Arena Workspace Name field is filled.

   If you experience any issues connecting to the Arena workspace, please contact Onshape or Arena Support.

   Once the connection has been successfully saved and established, it cannot be changed or edited without contacting Onshape Support.

   If there is a need to switch the target Arena Workspace for the connection, for example from an Arena Sandbox Workspace to an Arena Production Workspace, we recommend you contact support to request an Onshape enterprise sandbox that you can connect to an Arena sandbox for testing. This ensures any testing remains completely outside production. See Arena Workspace configuration process for more information.

3. Enter the General sync settings. Refer to the Arena page for more information on each option.

   Pay special attention to the Sync Onshape release management with Arena changes setting. If checked, an Onshape Release candidate and associated parts, Assemblies, and drawings are synced with an open and unlocked Arena Change. The Arena change then drives the approval process, and once approved in Arena, a notification is sent to Onshape, and the Onshape Release candidate is approved.

   When checked, the Onshape Arena release workflow is made active in the Release management settings.

   Uncheck this option to Sync Parts, Assemblies, and BOMs only, or check to additionally Sync Release Management.

   If you are syncing with Release management, also consult the following sections: Arena configuration for syncing with Release management and Onshape configuration for syncing with Release management.

To connect Arena part numbers, you must first map Onshape categories to Arena categories. This task is performed in Onshape and explained in this topic.

Introduction

Mapping Onshape categories and custom properties to Arena categories and custom attributes allows Onshape users to enter custom property values in Onshape that will be added to Items in Arena created through syncing from Onshape.

This mapping is particularly useful when the Arena definition for an Item includes required attributes. For example, if an Arena category definition, named 'Light', includes a required attribute of Light Color, then failing to provide a value for the attribute Light Color in Onshape results in failure to create the 'Light' Item in Arena.

Mapping the Light category to Onshape and mapping the Light Color attribute to an Onshape property, enables an Onshape user to provide a value for Light Color and consequently, Items of this type can be created in Onshape.

Categories and Attributes are first defined in Arena and then only the ones that are applicable to the Onshape environment should be mapped to Onshape. Not all categories need to be mapped and not all attributes within a category need to be mapped.

Wherever an Attribute is mapped it is implicitly declared that Onshape is the master system for this attribute value. Using the above example, if an Onshape part with Category 'Light' is synced to Arena, and has the value for 'Light Color' set to 'Red', then this color will be 'Red' in Arena after the sync. If an Arena user changes this attribute value to 'Blue', for example, the next time the part is synced from Onshape, 'Blue' is overwritten with the value set in Onshape ('Red').

Required information

Required item	Source
Arena category and attribute names	Your Arena workspace
Onshape category and property names	Onshape workspace

Users and permissions

The required users and their permissions in each product are:

• Onshape - Enterprise user with administrator permissions

• Arena - Arena Administrator (someone with a workspace policy allowing editing of categories and attributes in the workspace settings)

Onshape mapping process

This process is performed by the Onshape enterprise Administrator:

1. In Onshape, navigate to the Enterprise settings page, then select the Arena tab on the left.

2. Navigate to the Mappings section of the page:

   

   • The Arena category column (far left) lists all the categories defined in Arena. This list is read from Arena as the page loads, as long as the Sync is enabled toggle is enabled (blue).

   • The Onshape category column (middle) indicates the name of the category as defined in Onshape. If the Arena category has not been mapped to an Onshape category, Not Mapped appears in that column instead of the category name.

   • The Mapping column (far right) displays either an informative message or a pencil icon to allow the Administrator to create or edit the mapping.

Editing a mapping

To edit a mapping on the Mappings page:

1. Click the pencil icon on the far right of the Mappings page, that corresponds to the category you wish to map.

   

2. Use the Onshape category dropdown to map the target Arena category to an existing Onshape Category.

   This field is pre-populated if an Onshape Category with the same name as the Arena category already exists in Onshape.

   If no such Onshape category exists, click the plus icon () to create a new Onshape category to automatically map to this Arena category, then click the Create button:

   

Once a Category has been mapped, the Administrator can map Onshape properties to Arena Attributes.

Attribute mapping follows a similar pattern to Category mapping: if an existing Onshape property with the same name and type as the Arena Attribute is found, the Onshape property field is pre-populated. Using the plus icon () for an attribute drop-down opens the Create dialog, allowing the Administrator to quickly create an Onshape property using the Arena attribute as a template.

Tips

• Not all attributes in a category need to be mapped.

• In Arena there are parent categories designated as Structural, and used to group similar categories that inherit properties from the parent. These parent categories must be mapped in Onshape before the child categories can be mapped. Since Onshape does not have a Structural category designation, you need to remove the scope from the Onshape categories mapped to the Arena structural categories so that they are not user selectable. This makes the Onshape category behave like a structural category in Arena. See Creating a category for more information.

• The Onshape Arena connection does not assign a scope to an Onshape category created while mapping to an Arena structural category.

• When a category in Arena is renamed, a new category ID is created. In Onshape, this category ID is not updated. and because Onshape looks for the previous category ID, the mapping is broken. This is indicated in the Arena settings > Mappings by displaying an Invalid mapping error to the right of the Category in the Mapping column (see image below). The Administrator should delete this mapping (which frees up the Onshape category) and then re-map the Onshape category to the new Arena category:

  

  All categories that have an Invalid mapping are found at the bottom of the mappings table.

The Onshape Material and the Onshape Mass properties are special cases that are properties of the Onshape category “Onshape Part” and these can also be mapped to Arena attributes. This topic explains how to make sure these are mapped to the appropriate Arena attributes.

Users and permissions

The required users and their permissions in each product are:

• Onshape - Enterprise user with administrator permissions

• Arena - Arena Administrator

Materials and Mass mapping process

In Onshape:

1. Navigate to Enterprise settings > Categories tab.

2. Locate and click on the appropriate category, in this example "Mechanical Parts". The following page appears:

   

3. Under Parent categories, make sure that the parent category of Onshape Part is selected. (This ensures that the Mechanical Parts category inherits the properties of the Onshape Part parent category.

   Onshape Categories can have more than one Parent so, in this case, the category Mechanical Parts could have parents of Part and Onshape Part. You can also, make Onshape Part a parent of Part.

4. Click Save changes.

In Arena:

1. Create two Arena single line text attributes Materials and Mass.

2. Assign the Materials and Mass text attributes to the Arena category Part > Mechanical.

In Onshape:

1. In the Enterprise settings > Arena page, under Mappings,

2. In the Arena category column, select Mechanical Parts.

3. Confirm that the corresponding Onshape category column contains Mechanical Parts.

4. Click the pencil icon to check that the Arena attributes are mapped:

   1. The Mass (global) Arena Attribute maps to the Onshape Mass property.

   2. The Materials (global) Arena Attribute maps to the Onshape Material property.

   3. If you have made changes, click Update mapping.

During sync, the Onshape Material Name is populated into the Arena Materials attribute and the calculated mass of the part (based on the material density and part volume) is populated into the Arena Mass attribute. Note that Mass is a text attribute in Arena that includes the mass and the unit of measure in the text value.

Mass units are synced in the units set in the Onshape user's User preferences.

The Onshape Arena Connection supports Category-based Item numbering, which must be configured in Arena prior to enabling Arena Part Number Generation.

Required information

Required item	Source
Onshape Category Mechanical (example category)	Onshape
Category-based Item numbering	Configured in Arena

Users and permissions

The required users and their permissions in each product are:

• Onshape - Enterprise user with administrator permissions

• Arena - Arena Administrator

Configuring part numbers process

This process requires set up in both Arena and Onshape.

In Arena:

1. Define an Arena Number Format.

2. Associate the Number Format to one or more Arena categories.

   When any of those categories are mapped to an Onshape category, and the Onshape user assigns one of those categories to an Onshape Part, Assembly, Drawing or File, then auto generated Part Numbers sync from Arena.

In Onshape:

1. Go to Enterprise settings > Numbering schemes:

   

2. Set up a Numbering scheme for each of the 3 object types. Refer to Numbering schemes for a full explanation of this dialog.

3. Click Save changes to ensure all changes you've made are saved.

Save changes only saves the changes for the current tab being edited (Release objects, Standard content, or Items). Each tab's changes are independent.

When Onshape pulls a part number from Arena it is reserved in Arena; however, the Arena Item with that number is not created until the Onshape part is synced.

Limitations

• Although Arena allows up to 200 characters in an Item Number, an Onshape Part Number can contain only up to 128 characters, so make sure that the Arena Number format generates part numbers fewer than 128 characters in length.

• Arena Part Number Formats that are used by Onshape-mapped categories cannot include a free text field in the number format.

Common numbers across categories, above

Unique numbers within categories, above

The following configurations are required to enable synchronizing releases between an Onshape Release candidate and an Arena change. The Onshape Administrator should enable these settings:

• (Recommended) In Enterprise Settings > Numbering Schemes enable the Drawing can reuse part number from an assembly or part in the release setting. See Numbering schemes for more information.

• In Enterprise Settings > Release Management:

  • (Recommended) Check Enable managed workflows. See Setting up Release Management and Release management for more information.

  • (Required) Select the Onshape Arena release workflow as the default workflow.

  • (Recommended) Under Watermarks, check Show watermark for unreleased drawings if you want unreleased drawings to display a watermark. The watermark also displays on the PDF drawing that is sent to Arena upon submission of a release candidate. See Setting up Release Management: Watermarks for more information.

  • (Required) Under Obsoletion, check Automatically obsolete previous released revisions to make Onshape mimic the Arena behavior that automatically supersedes (obsoletes in Onshape) previous revisions when a new revision is released. See Setting up Release Management: Obsoletion for more information.

• In Enterprise Settings > Arena > General sync settings (see Arena for more information on each settting):

  • (Required) Check Sync Onshape release management with Arena changes.

  • (Recommended) Check Match release candidate name with Arena change.

  • (Recommended) Check Sync release notes with Arena properties.

The following configurations are required to enable synchronizing releases between an Onshape release and an Arena change. The Arena Administrator should enable these Workspace settings:

• (Recommended) Under Changes > Edit Configuration, enable Use Change Management for all stages. This results in a change being required to create a new revision of Items being promoted from Preliminary to In Design and In Design to In Production. For each stage, click the Select Behavior button and configure the routings to your specifications.

• (Required) Under Summary > Edit Settings > Files, set the Corrections to Files Allowed option to Yes, and allow removal of original content. This allows automatic updates (file corrections) of the Drawing's PDF file after the Change is approved in Arena. Once approved, the PDF is generated in Onshape, and the corresponding Item file attachment in Arena is automatically updated.

• (Recommended) Under Categories > Files, create 2 new Categories used for the 3D STEP files and 2D PDF drawings added to Items in the Arena change:

  • CAD Data

  • Drawing

  To create a category:

  1. Click the Add Category button ().

  2. Select a Parent.

  3. Enter CAD Data or Drawing for the name.

  4. (Optional) Add a description.

  5. Select the Active-This category is visible in the application radio button.

  6. Click the Create Category button.

     

  If these Categories are not created, associated file attachments are displayed as <uncategorized>.

• Define Arena File Formats for STEP and PDF files

• (Recommended) Under Lists, click the File Formats dropdown link. Create 2 new File Formats used for the 3D STEP and 2D PDF Drawing files associated with the Item Revision on a Change:

  • step

  • pdf

  If these file formats already exist, they do not need to be created.

  To create a file format:

  1. Click the Edit File Formats List button ().

  2. In the List Values field, enter step and pdf, each on their own separate line.

  3. Click the Save button.

     

The Onshape administrator can control which users have permission to sync to Arena through the Sync to Arena global permission:

1. Navigate to Enterprise settings > Global permissions.

   

2. Scroll to the bottom of the page, and double-click on Sync to Arena to open the Configure permission "Sync to Arena" dialog:

   

3. Specify Individuals (through email addresses) and Teams (already defined in your Onshape enterprise) to which to grant permission to Sync to Arena.

4. Click Add, then Close.