Aras Office Productivity Connector Preferences

Aras Office Productivity Connector preference settings are managed within Aras Innovator, in the Administration section of the TOC.

To access these settings, use the following procedure:

1. Login to Aras Innovator as an administrator.
2. From the TOC, expand Administration, and select Preferences.
3. Click the Search Icon to execute a search and display a list of Identities.
4. In the search grid, double-click on the row containing the World identity. This opens the Preferences dialog for Aras Innovator.

5. Click on the Office PreferencesTab and double-click on Office Connector Settings within the tabular area at the bottom. This opens the Office Connector Settings webpage dialog.

The general settings are in the dialog’s top area and control some of the Aras Office Productivity Connector’s general behaviors.

• Viewable Generation: Automating the creation of viewable files, like PDF and PDF/A, from Office applications is one part of the Aras Office Productivity Connector functionality. Four options determine when viewable files are generated. If the first or second option is selected, the system always handles the generation automatically. If the third or fourth option is selected, a checkbox is added to the Aras ribbon that enables the choice to generate the viewable file.
• Remove Local File On Close: This setting does not apply to Aras Office Productivity Connector.
• Do Not Increment Link Item Version On Update: This setting is currently unavailable for Aras Office Productivity Connector.

The first tab within the Office Connector Settings dialog is Document Types. A Document Type refers to the combination of an ItemType and Classification used to manage an Office file. Any Aras ItemType (not just Document) can be used to manage Office documents if it is properly configured here in these settings. It is important to understand that the standard settings provided in this Tab are examples only. It is expected that they will be configured to match requirements for an organization.

The standard settings refer to four Classification Values of the Document ItemType, as shown here. The standard release automatically includes these Classification Values (Ad-hoc, General, Product, and Project) in the Document ItemType.

Within the tabular view, the Order property can be set to control the sort order for the Document Types. The sort order is the order in which users see the Document Types listed when they create new documents from the Aras Office Connector.

For the rest of the Document Type settings, it is more practical to edit them within a form rather than the tabular layout:

• To edit an existing Document Type in the relationship grid, right-click to display a context menu. Select Document Types and Open.
• To create and edit a new Document Type, click the Add Row button, select the new row, and select Document Types and Open.

You will then see the Office Document Type form.

• Label: This is the name of the Document Type that users see. It can be any text string that makes sense for a company. By default, the value of Label will be automatically set as the combination of ItemType and Classification (as shown above), but it can be changed by typing something else in the Label field.
• Item Type: The name of the base ItemType used to manage Office documents. This can be any ItemType in the system.
• Classification: (Optional) A specific Classification Type to use Classification to differentiate Document Types. If left blank, the base ItemType is used without a specific class value.
• Native File: Specifies the reference to the location of the native Office file (.docx, etc.) relative to the base ItemType. This can be either a relationship to File, a null relationship with an item property with a source File, or a property of type Item with source File. The value used to specify this is an Office Document Reference. Read the Office Document References section for details.
• Viewable File: This specifies the reference to the location of the viewable Office file (.pdf, etc.) relative to the base ItemType.
• Base Document Type: (Optional) Shows the name of another Office Document Type used as the basis for Property Mapping and Valid Linked Items settings. Refer to the Base Document Type section for details.
• Template Filter Method: This allows setting the desired logic to determine which templates are available for selection by the user during the document creation process. The Template Filter Methods provided by default are intended to give administrators examples of how to set this up. For example, the MSO_ReleasedTemplateFilterMethod only allows users to select Released templates during creation.
• Generate Thumbnail: This controls whether the thumbnail will generate on the Document Item form in Aras Innovator each time the item is saved.
• Template Required?: This controls whether the user will be forced to select a template stored in Aras as the basis for the new document being created when using the New Aras Document command. Certain Document Types should require templates, thus standardizing the document creation process in the organization.
• Linked ItemRequired?: This controls whether the user will be forced to select a Linked Item when creating a new document of this type. Certain Document Types, such as a Part or Project, should require using a Linked Item because the document should not exist without a relationship to this Item.
• Allow Promote: This controls whether the Promote function is available for the Document Type. This should only be enabled if the ItemType corresponding to the Document Type allows manual promotion and is not under the control of a change Item like ECO or DCO. If enabled, the Promote function will be made available both in the Aras ribbon (for manual use) and as part of the Save and Close function, for promoting after work is complete.
• Allow Select Existing Document: When this checkbox is selected, users can select an existing Document Item, create a new file, and link the two instead of creating a new document of a particular type. Users can then use the Document Number associated with the existing Document Item instead of generating a new Document Number.

• Available To: This specifies a single Identity that has access to the Document Type. Any user who belongs to this Identity can create documents of this Type. Otherwise, the user will not see the corresponding Document Type when creating a new document.
• Document Numbering: This allows setting one of three options for controlling the numbering of Aras Documents used to manage Office files: Method, Sequence, or Manual. Method means that you will define an Aras Method to define the logic for the Document Number. Sequence means you are going to use an Aras Sequence directly. Manual allows end users to enter the Document Number at the creation time. If Sequence is selected, the desired Sequence must be entered in the next field. If Method is selected, the desired Method must be entered in the following field.
• Document Numbering Sequence: If Document Numbering is set to Sequence, this field must include the name of the Aras Sequence to be used to define Document Numbers.
• Document Numbering Method: If Document Numbering is set to Method, this field must include the name of the Aras Method to be used to define Document Numbers. This approach provides more flexibility than Sequence since any desired logic can be used. The Document Numbering Methods provided by default are intended to give administrators examples of how to set this up. For example, the Method MSO_Product_Document_Numbering includes the following logic:
• Determine if the Document is being linked to a Part (a Valid Linked Item).
• If YES, the Document Number will be of the format P12345-DOC-1, where P12345 is the Number of the Linked Part, -DOC- is a fixed text string, and 1 is a sequential integer starting from 1. If a second Document is later linked to the same Part, its Document Number will be P12345-DOC-2.
• If NO, the Document Number will be set using the Default Document sequence.

The Method approach provides additional logic that allows the Document Number to be based on the Part Number if a Linked Part exists.

• Rename File?: This setting controls whether the Office file being saved into Aras (or being newly created) will be renamed or left as-is. Valid options are:
• No: If saving an existing file, the file will not be renamed, and if creating a new file, the user will be prompted to enter a file name.
• Method: An Aras Method will define the logic for renaming (or naming) the file. If this setting is used, the name of the Aras Method must be defined in the File Naming Method field.
• Match Document: The filename will match the Number assigned to the Document based on the Document Numbering approach described above.
• File Naming Method: If Rename File? is set to Method, this field must include the name of the Aras Method to be used to define the file name. This approach provides more flexibility, like Method for Document Numbering. The File Naming Methods provided by default are intended to give administrators examples of how to set this up. For example, the Method MSO_Product_File_Naming retrieves the value of the Document Number and appends the dash character and the entered Document Title (if any) to it. For example:
• If the Document Number is P12345-DOC-1, the File Name will be P12345-DOC-1-MyTitle.
• If the Document Number is D54321, the File Name will be D54321-MyTitle.

The Method approach provides additional logic that allows the file name to be more descriptive.

• Allowed Office Applications: This field specifies which Office application the Document Type applies to.

A Default Document Type has its ItemType Value set, but the Classification Value is not set. This is used to manage files that were previously stored manually in Aras. For example, an administrator uses the standard Aras Document ItemType and has ten different Classification values already used in existing Documents (not created by the Aras Office Productivity Connector). Suppose that in the future, the administrator wants to use only specific Document Types in Aras Office Productivity Connector for three of those Classifications. This means that if a user opens a Document set to any of the other seven Classification Values, it will be opened as a Default Document Type. Thus, it will follow the defined behaviors of the Default Document Type regarding Property Mappings, Valid Linked Items, etc. This saves time, as Document Types won’t have to be defined for every existing Classification. Any Document with a Classification Value that does not match a specific Document Type will be treated as Default.

Using a Base Document Type simplifies the definition of Property Mappings and Valid Linked Items, where most or all of these definitions are shared with many Document Types. To set a Base Document Type, simply pick an existing Document Type from the Base Document Type Property. In the following example, the Document Type Document / Miscellaneous uses a Base Document Type of Document Base. The Document / Miscellaneous Document Type automatically uses all Property Mapping definitions and Valid Linked Items for Document Base.

The following logic applies when using a Base Document Type:

• All settings in the Document Type header must be set directly and are not inherited from the Base Document Type.
• Any Property Mappings set on the current Document Type are in addition to those set on the Base Document Type. When there are duplicates, the settings on the current Document Type override those on the Base Document Type.
• Any Valid Linked Items set on the current Document Type are in addition to those set on the Base Document Type. When there are duplicates, the settings on the current Document Type override those on the Base Document Type.
• The Base Document Type must be the same ItemType as the referencing Document Type.
• Only one reference level is allowed (i.e., no recursive definition).

The concepts of Base Document Type and Default Document Type can be combined. This is achieved simply by defining a Base Document Type with no Classification Value.

Use the following procedure to attach a file to an existing Aras Innovator document:

1. Select New and New ArasDocument in the ribbon. The New Document task pane appears:

2. Select the Document Type from the dropdown list in the Document Type field.

3. Click the ellipsis (...) next to the Document Number field. The Search dialog box appears.

4. Click the Search Icon to see a list of existing document items that do not have any related files.

5. Select the existing Document and click Select. The Document Number is applied to the new document.

The second tab in the Office Connector Settings dialog is Property Redirection. This Tab allows you to define redirection for specific properties, such as authoring_tool, required by the Office Connector. It can also be used in cases where a property required by the Office Connector is already being leveraged for another purpose and cannot be used simultaneously with the Office Connector.

• Item Type: This is the Name of the ItemType within Aras Innovator that requires property redirection.
• Original Property: This is the Name of the property within the Aras ItemType definition that is to be redirected. It must be set to authoring_tool. No other Aras properties are currently supported.
• Redirect Property: This is the name of the property within the Aras ItemType definition to which the original property will be redirected.

One of the capabilities of the Aras Office Productivity Connector is that it allows easy linking of Documents to other Aras Items like Parts and Projects. The term “link” refers to the Aras concept of a relationship between two items. When links are used, the Base Item that contains the files is always the Related (i.e., Subordinate) Item, related to a Parent Item such as a Part. Valid Linked Items are defined on the second Tab of either the Office Document Type or Office Email Document Type Form. This setting defines which other Aras ItemTypes can be used as Parent Items of the Relationship for the given Document Type. For example, in the standard settings, only Parts can be linked items for the Document / Product Document Type because this type is designed to manage documents related to Part definition (specs, test plans, etc.).

Valid Linked Items are defined separately for each Document Type, and you can have as many valid Items as desired. Entries for Valid Linked Items are based on Office Document References, as described in the following section.

Office Document Reference is an ItemType used by the Aras Office Productivity Connector to define Document Types in a flexible way. It defines the links between the Base ItemType used by the Document Type and:

• The files managed by the Connector (both native and viewable).
• Any valid linked items (such as Part, Project, etc.).

In each of these cases, the links can either be:

• Item relationships (e.g., Document File, Part Document).
• Properties of type Item (e.g., the native_file property on CAD Document).

Office Document References are accessed from within the Administration section of the TOC.

The standard references shown here are provided to support the standard Document Types, but customers are expected to create their own to match the ItemTypes they are using to manage Office documents. Office Document References contain four properties as shown on the form here:

• Label: The name of the reference.

• Item Type: For a relationship, this is the name of the Relationship ItemType. This is the ItemType containing the property for a property of type Item.
• Property: This will always be the related_id property for a relationship. This is the name of the property for a property of type Item.
• Description: A description for the reference.

Here are some typical examples to illustrate the use of Office Document References, using standard Aras ItemTypes like Document and CAD Document to explain the common data model options:

Once Office Document References are created, they are used in two places in the definition of Office Document Types: the links to the Native and Viewable Files, and the Valid Linked Items.

Property Mapping is defined on the first tab of either the Office Document Type or Office Email Document Type Form. This Tab controls the property mappings between the Office file and the Aras Document. Properties can be mapped in either direction and can be set to be mapped either during the initial document creation (Create) or upon subsequent saves (Update). In addition to those two mapping events, any properties mapped From Aras to Office File are updated when the user clicks the Refresh button in the Aras ribbon. Property Mappings must be defined for each Document Type separately, although using Base Document Types can simplify the process. The Aras Office Connector provides a set of standard Property Mappings, as shown here. xProperties can be used in Property Mappings. Any Extended Classifications (xClasses) assigned to template documents will be automatically assigned to documents created from the templates, and Property Mappings can be configured for xProperties within the assigned xClasses. If a Property Mapping includes an xProperty configuration but the Document Item does not include these xClasses, the Property Mapping will be ignored. If a user creates a new Document in Office Connector and selects an existing Document and Document Template, any xClasses contained in the Documents are merged. Standard Mappings for Document Types:

• Office Property: This is the property’s Name within the Office file. It can be either a standard property (such as Title or Subject) or a custom property (such as Aras Author). When mapping from Office File to Aras, this property must exist in the file. When mapping from Aras to Office File, if the property does not exist, it will be automatically created as a custom property.

When mapping to and from Excel Cells, this value is the name of a Named Cell.

• Aras Property: The property’s Name is within the Aras ItemType definition. It must exist for either mapping direction or an error will occur.
• Use Template: If enabled, the corresponding property value from the Template Document will be set into the newly created Document. See the Mapping Properties from Linked Items section for details.
• Direction: The following table shows all valid mapping directions and which Office applications they work in:

For example, to set up a mapping that maps from all MS Office applications to Aras, use “From Office File to Aras”, whereas if you want the mapping to apply only for Word, use “From Word to Aras”.

• Create and Update: The checkboxes in these columns define which events the mappings occur. Create refers to the initial save to Aras, and Update refers to subsequent saves to Aras.

Some important points about Property Mapping:

• Mappings can be one way on Create and another on Update. The default mapping for Title is an example. This means that the initial Title is established from the Office file during the first save to Aras, but after that, Aras is the source of any changes to the Title.
• The same property must not be mapped on the same event in both directions.
• Valid Aras property Types for mapping include String, Text, Integer, Decimal, Float, List, Filter List, Multi Value List, Boolean, Date, and Item. Foreign and Federated property data types are also supported, but only in the direction from Aras to Office.
• If properties are defined as Required on the Aras ItemType, the property entry field will be presented to the user with a blue background inside Aras Office Productivity Connector. The user cannot create or save a new document until all required properties are entered.
• If properties are defined as having a default value on the Aras ItemType, this default value will be present to the user inside Aras Office Productivity Connector. They may then change the value if desired.

The mapping directions From Aras to Excel Cell and From Excel Cell to Aras allow connecting worksheet cell values to properties in Aras. This can be used, for example, to drive a calculation in Excel from values coming from Aras. When using these options, the value specified in the Office Property column is the name of a named cell in Excel. To name a cell in Excel, select the cell, right-click, and select Define Name…. The mapping directions From Aras to Excel and From Excel to Aras map to and from Custom Properties in the Excel file, rather than cells.

Some special mapping properties that perform specific functions in the connector are supported. They are summarized in the following table:

To use any of these special properties, a property must be defined with the required data type on the ItemType corresponding to the Document Type. Then, create a row in the Property Mapping where the Special Property Name is set in the Office Property column.

Documents are often linked to other Aras Items, like Parts. It is useful to be able to map properties from these linked Items. This capability is available but uses a specific technical approach known as Foreign properties in Aras, essentially properties inherited from one Item to another. This approach makes it possible to map and display properties from linked Items but not to set properties on those Items. The following example describes the step-by-step process to set this up. Company ACME has certain product specifications in Word that require displaying the official Part and Project Numbers from their Aras PLM system and the Document number itself. The header of the Word document looks like this: ACME PRODUCT SPECIFICATION

While the value of the Document Number is a standard case, getting the values for the Part Number and Project Number mapped into the Word document requires establishing appropriate Foreign properties on the Document Item.

1. Set up Properties on the ItemType.

Properties necessary to support our example look like this:

The linked_part and linked_project properties are regular Item properties that point to the linked Part and Project, respectively. The linked_part_number and linked_project_number properties are Foreign properties that refer back to the Item properties.

1. Set up Foreign Data Source for Linked Items.

The Aras Office Productivity Connector needs to know the names of which Item properties to set for each linked item. When Foreign properties are used, you need to add the name of the Item property into the Foreign Data Source column of the Valid Linked Items settings, as shown here:

Foreign Data Source is an optional setting. Notice that Activity and WBS Element are Valid Linked Items for this Document Type, but they don’t have any Foreign Data Source set. This means that no Property Mappings can be supported from any Activity or WBS Elements that may be linked to a Document of this type.

2. Set up Property Mappings.

To map the actual Foreign properties into Office, use Property Mappings as usual. Only directions going from Aras to Office are supported.