41 Administering Reference Objects

This chapter explains how to configure the Reference Objects feature in Agile PLM.

41.1 What are Reference Objects?

In Agile PLM, the table on the Relationships tab enables users to add references to other objects in Agile PLM. Introduced in Agile PLM 932, the Reference Objects feature enables users to search for objects in external applications and add them as references on the Relationships tab.

From the Relationships tab, an end user can:

• Search for an object in an external application and add a reference to that object in Agile PLM Relationships table.

• Create a new object in an external application, and add a reference to that object in the Agile PLM Relationships table.

• Search, add, and remove Reference Objects from the Agile PLM Relationships table.

41.2 Reference Object Setup

As of release 9.3.2, Reference Objects are a new Oracle Agile PLM object class. Reference Objects allow the user to look up objects in external applications and add them to the Relationships tab as references.

• Relationship rules are not supported for Relationship Objects.

• Reference objects are supported in Web Client only. However, once a reference object has been added to a Relationships tab in Web Client, that reference object is visible in Java Client.

• Reference objects are created only from the Add drop-down menu on the Relationships tab (or Content tab in PPM). (Reference objects cannot be created from the Create New menu in the top pane of Web Client.)

• The Agile administrator must create Discover, Read, Create, Modify, and Deleted privilege masks for Relationship Objects, and apply those privilege masks to roles. Reference Objects appears in the Add drop-down menu on the Relationships tab when end user has a Create privilege mask for Reference Objects.

• You can perform a simple search for reference objects only from the Relationships (or Content) tab. In all other Agile PLM searches, Reference Objects or its subclasses do not appear as a choice for searching.

The set of search result objects is determined by the external application.

By default, the Reference Objects feature is not automatically enabled when Oracle Agile PLM is initially installed or upgraded.

Overview of the Reference Object feature configuration tasks:

1. On the System Settings > Reference Objects Management > Applications node, define the external applications.

2. Enable the Reference Objects class and define the needed subclasses.

3. Define each Reference Objects subclass, including specifying the external application webservices.

4. Define the Attribute Mappings for each subclass.

5. Define the Quickview Mappings for each subclass.

6. Create the necessary privilege masks: Discover, Read, Create, Modify, Delete.

To enable the References Objects class and subclass:

1. Under Data Settings, double-click Classes. The Classes window appears.

2. Double-click the Reference Objects class name. The class properties window appears.

3. Next to the Enabled drop-down list, select Yes.

4. Click Save.

41.2.1 Define External Application

The Reference Objects Applications node (Java Client, Admin > Systems Settings > Reference Objects Management > Applications) enables you to create, modify, delete, enable, and disable external applications that Agile PLM will search to find external objects to associate with an Agile Reference Object.

Define the external applications:

1. In Java Client, navigate to the System Settings > Reference Objects Management > Applications node.

2. Click the Create button.

3. In the Create Application dialog, fill in the Application property fields.

4. When you are finished, click OK.

Table 41-1 Specify external application details properties

Property	Description
Name	Name of the external application that will appear in the add Relationship search dialog list and
API Name	This field in filled in automatically. You can enter a different API name, if desired.
Description	Detailed description of the external application.
Host Base URL	The base URL of the external application.
Port	Port number.
Virtual Path	Virtual path of the external application.
UserID	UserID used on external application.
Password	Password for above userID
Enabled	Set to Enabled by default. Values: Enabled or Disabled.

• Together, the Base URL, Port and Virtual Path construct a URL to the location of the external application's webservices.

• UserID and Password can be left blank to use the logged in user context during runtime.

You can define multiple external applications, as needed.

41.2.2 Specify Reference Object Webservices

Each remote application must have webservices written for the Reference Object integration. The Host Base URL, Port and Virtual Path properties on the Application definition are used to construct a URL to the location of the external applications webservices.

You can download a sample webservice from http://www.oracle.com/technetwork/indexes/samplecode/agileplm-sample-520945.html on the Oracle Technology Network (OTN) website.

41.2.3 Define Reference Object Subclasses

For each external application object type for which you want to create Reference Objects, you must define a separate subclass. Each external application object type must have its own subclass. For example, if the external application has both Diode objects and Resistor objects, then you must define a subclass for:

• <External Application> Diode

• <External Application> Resistor

When the end user adds Agile Reference Objects to the Relationships tab, each Reference Object subclass appears in the search palette object drop-down list.

To enable the References Objects class:

1. Under Data Settings, double-click Classes. The Classes window appears.

2. Double-click the Reference Objects base class name. The class properties window appears.

3. Next to the Enabled drop-down list, select Yes.

4. Click Save.

To create a Reference Object subclass:

1. Navigate to Data Settings > Classes. Double-click Reference objects class name. The class properties window opens.

2. Click the Subclasses tab.

3. Click the New Subclass button. The New Subclass dialog appears.

4. Fill in the editable fields:

   • Name

   • API Name (See "API Name.")

   • Description

   • Icon (Enter the location of a custom icon, if desired.)

5. Click OK.

   The subclass window opens.

6. Complete the remaining fields:

   • Tokens – Tokens is the object name in the external application's webservice that calls up a specific type of object in that application. Example: objectType=Changes

   • Search Webservice – the name of the external application's webservice that initiates a search in the external application.

   • Quick View Webservice – the name of the external application webservice that retrieves the Quick View attributes as defined in the Mappings node.

   • Available On – the objects in the current Agile PLM system that will be able to add this Reference Object subclass as a row on their Relationships tab. For example, Items and Changes.

7. Click the Test Webservice button to test the webservices you have configured.

8. When you are done, click Save.

41.2.4 Define Reference Object Attribute Mappings

The Reference Objects Management folder Mappings node enables you to map attributes from an external application to attributes on a configured Reference Objects subclass.

There are two types of mappings available:

• Attribute Mappings

  • Attribute mappings are automatically created when the subclass is created.

  • There are three mappable Reference Object Attributes: Name, Description, Current Status.

  • The Agile administrator can modify or remove the corresponding Webservice Attributes.

• Quickview Mappings

  • The Quickview mappings define the external application attributes that appear in the Quickview palette when the end user views the Reference Object with the Quickview feature.

  • Quckview mappings are not created automatically when the subclass is created.

  • You can add up to 15 Quickview mappings.

  • Quickview mappings consist of:

    Label – the label that appears in the Quickview palette.

    Webservice Attribute – the external application webservice that returns the corresponding external application attribute.

    Data Type – choices are Text, MuliText, Date, and Numeric.

  • You can modify the order of the Quickview Mappings.

To define attribute mappings:

1. Navigate to Admin > Settings > System Settings > Reference Objects Management. Double-click the Mapping node to display the Mappings window. The defined Reference Object subclasses are displayed in a table.

2. Double-click the table row of the subclass you want to modify. The Mappings:<subclass name> window appears.

3. Under Attribute Mappings, you can modify the Webservice Attribute.

   
   

   Note: When specifying Quickview mappings for an Agile-to-Agile reference object subclass, the Webservice Attribute names cannot include any white space (space characters).

   
   

4. Under Quickview Mappings, click the Add button to add a row.

5. Double-click in a cell to enter values for Label and Webservice. Use the drop-down list to select a Data Type.

6. Click the Add button again to add another row, up to 15 rows.

7. Click the Reorder Quickview Attribute Mapping button to display the Order dialog.

8. Select a row and use the up arrow and down arrow buttons to rearrange the order of the attributes.

9. When you are finished, click OK in the Order dialog.

10. When you are finished in the Mapping dialog, click OK.

Note: When specifying Quickview mappings, Page Two and Page Three attributes must have unique API names. For example, if date01 on Page Two and date01 on Page Three have the same API name, only the Page Two date01 attribute will be displayed in the Quickview display. To avoid this conflict, in the Java Client Administrator Classes node, rename one or both of the conflicting attributes so that the API names are unique.

41.2.5 Create Reference Object Privilege Masks

The Administrator privilege includes an AppliedTo value, Reference Objects Management. This Administrator privilege property grants access to both the Applications and Mappings nodes in the Reference Objects Management folder.

You can create reusable criteria for Reference Objects, and then use that criteria to create privilege masks for the privileges Create, Modify, Discovery, Read, and Delete. Discovery and Read of the Relationship table rows is achieved by granting privilege masks for Reference Objects class and subclass.

A Create Reference Objects privilege mask controls whether a user can create reference objects. It also controls the availability of the "Reference Objects" selection on the Add button drop-down menu on the Relationships tab.