11 Managing Reference Objects

This chapter includes the following:

About Reference objects
Creating a Reference Object
Updating a Reference Object
Deleting a Reference Object
Adding a Reference Object to the Relationships Tab of the Web Client
Removing a Reference Object
Searching for Reference Objects

11.1 About Reference objects

Reference Objects are an Oracle Agile PLM object class. They enable PLM users to look up objects in external applications and add them to the Relationships tab of the Web Client as references. Reference objects are only supported in the Web Client. However, once a reference object is added to a Relationships tab in the Web Client, that reference object is also visible in the Java Client.The Agile administrator must create the Discover, Read, Create, Modify, and Deleted privilege masks for Relationship Objects, and apply these privilege masks to roles. Reference Objects appear in the Add drop-down menu on the Relationships tab when the 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 of the Web Client. None of the other Agile PLM searches support searching for Reference Objects or their subclasses.The set of search result objects is determined by the external application.From the Relationships tab in Web Client, an end user can do the following interactively, and in the batch mode using the exposed Agile APIs:
- PLM's Relationships table.
- Create a new object in an external application and add a reference to that object in Agile PLM's Relationships table.Search, add, and remove Reference Objects from the Agile PLM Relationships table.
PLM Clients support an absolute URL and the SDK supports the absolute and relative URLs. For example, /jde/servlet/1234 (relative URL) and https://servlet:port/jde/servlet/1234 (absolute URL).The Relative and Absolute URL types support the following three SDK calls:
- getURL (relative URL)setURL (relative URL)getAbsoluteURL
You can:
- Search for an object in an external application and add a reference to that object in Agile PLM Relationships table.Search, add, and remove Reference Objects from the 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.
Advanced search does not support case sensitive or other Agile search FTS features. This limitation on the server side is due to the reference object query results are from the external system and our reference object WS schema does not have more search syntax definitions. So Agile core cannot guarantee the external search criteria.In Advanced Search:
- The only supported search criteria column is TitleBlock.Name/Number/Desc.The only supported search operator is ”Contains.” For example, query.setCriteria("[TitleBlock.Name/Number/Desc] contains the phrase '*'”); If the SDK client passes other criteria columns or operators, the Search server will throw an error stating the search condition syntax was invalid and use only one row with criteria column

11.2 Creating a Reference Object

The Reference Objects class is an ObjectType on a Remote or External Application that is configured or mapped to an Agile object class and accessed through the Relationships Tab of the Web Client.

To create Reference object use IAgileSession.createObject(Object, Object) method. Remember that the following required attributes must be provided at the creation time

Required Attribute	Potential Argument Types
ATT_GENERAL_INFO_OBJECT_TYPE	ReferenceObject SubClass (String), IAgileClass object
ATT_GENERAL_INFO_NUMBER	ReferenceObject Number/Name (String)
ATT_GENERAL_INFO_PUBLIC_KEY_STRING	ReferenceObject Public Key (String) This can be the composite key that uniquely identifies the Object on the Remote Application.

Note:

A Key(ID) that can uniquely identify the Reference Object on the Remote system is called Public Key. This is different from the security-related Public/Private Key definitions.

The following example shows how to create a Reference Object.

Example 11-1 Creating a Reference Object

IAdmin m_admin = m_session.getAdminInstance();
Map<Integer, String> paramsMap;

//The only allowed Sub Class is Name/APIName of the Reference Object from Agile //Java Client   paramsMap.put(ReferenceObjectConstants.ATT_GENERAL_INFO_OBJECT_TYPE,       referenceObjectSubClass); //Note: Should be a valid Sub Class   paramsMap.put(ReferenceObjectConstants.ATT_GENERAL_INFO_NUMBER, "REFOBJ01");
   paramsMap.put(ReferenceObjectConstants.ATT_GENERAL_INFO_PUBLIC_KEY_STRING,       "UniqueKeyOnRemoteApplication");   IReferenceObject refObject = (IReferenceObject)m_session.createObject(      IReferenceObject.OBJECT_TYPE,paramsMap);

Note:

Web Client users can directly create a Reference Object, but not using search and then adding it from the remote system. The SDK, in addition to search and add, it also support directly creating Reference Objects as in other Agile object types, when the required parameters are known. This is designed to align Reference Objects with other object types in the SDK framework.

11.3 Updating a Reference Object

To update a Reference Object, first get the pointer to the existing Reference Object using the IAgileSession.getObject(IReferenceObject.OBJECT_TYPE, paramsMap) API. Once the pointer to the object is available, updating the attributes is similar to other object types in the Agile system. You can use the getObject() API with either Subclass and Name, or Subclass and Public Key to uniquely identify the Object.

Note:

The getObject() API retrieves a Reference Object if and only if the object exists in the Agile system, otherwise, it will return a null value. As such, getObject() also determine if the object already is/is not in the Agile PLM. Because an object number can be repeated across different subclasses, for example, if part, manufacturer part, and problem report, all have the number 'P0001', it is necessary to pass the subclassID in order to return a unique Object ID. To this end, the getObject() API passes both the subclassID and the Object number.

Example 11-2 Updating a Reference Object

IAdmin m_admin = m_session.getAdminInstance();paramsMap.put(ReferenceObjectConstants.ATT_GENERAL_INFO_OBJECT_TYPE,    referenceObjectSubClass); //Note: Must be a valid Sub Class      paramsMap.put(ReferenceObjectConstants.ATT_GENERAL_INFO_NUMBER, "REFOBJ01");

paramsMap.put(ReferenceObjectConstants.ATT_GENERAL_INFO_PUBLIC_KEY_STRING,    "UniqueKeyOnRemoteApplication");

//Get/Load Reference Object from Agile if already exist.   IReferenceObject refObject = (IReferenceObject)m_session.getObject(      IReferenceObject.OBJECT_TYPE, paramsMap);

//Get the cell of each attribute:   ICell num = 
      refObject.getCell(ReferenceObjectConstants.ATT_GENERAL_INFO_NUMBER);

   ICell desc = 
      refObject.getCell(ReferenceObjectConstants.ATT_GENERAL_INFO_DESCRIPTION);   ICell url = 
      refObject.getCell(ReferenceObjectConstants.ATT_GENERAL_INFO_URL);   ICell sts = 
      refObject.getCell(ReferenceObjectConstants.ATT_GENERAL_INFO_STATUS);

//Update the cells with new values:   num.setValue("New Number");   url.setValue("Modified URL");   desc.setValue("New Description");   sts.setValue("Pending");

//The same above is also achieved using the following approach:   refObject.setValue(ReferenceObjectConstants.
      ATT_GENERAL_INFO_NUMBER, "New Number");   refObject.setValue(ReferenceObjectConstants.
      ATT_GENERAL_INFO_DESCRIPTION, "Modified URL");   refObject.setValue(ReferenceObjectConstants.
      ATT_GENERAL_INFO_URL, "New Description");   refObject.setValue(ReferenceObjectConstants.
      ATT_GENERAL_INFO_STATUS, "Pending");

11.4 Deleting a Reference Object

You can only delete the Reference Object, provided it exists, from the local Agile system and not from the Remote Agile system. This is similar to deleting other object types in the Agile PLM.

11.5 Adding a Reference Object to the Relationships Tab of the Web Client

Adding Reference Objects to the Relationships table of the Web Client is similar to adding other object types in the Agile system, using the createRow() API.

Example 11-3 Adding a Reference Object to the Relationships Table in Web Client

IAdmin m_admin = m_session.getAdminInstance();paramsMap.put(ReferenceObjectConstants.
   ATT_GENERAL_INFO_OBJECT_TYPE, referenceObjectSubClass);paramsMap.put(ReferenceObjectConstants.
   ATT_GENERAL_INFO_NUMBER, "REFOBJ01");paramsMap.put(ReferenceObjectConstants.
   ATT_GENERAL_INFO_PUBLIC_KEY_STRING, "UniqueKeyOnRemoteApplication");

//Get the Reference Object from Agile
   IReferenceObject refObject =
      (IReferenceObjectm_session.getObject(
         IReferenceObject.OBJECT_TYPE,paramsMap);

//Get Relationship Table of an Object that the Reference Object will be added to:   IDataObject parentObj = (IDataObject) m_      session.getObject(QualityChangeRequestConstants.CLASS_CAPA, "CAPA0001");   ITable relTbl = parentObj.
      getTable(QualityChangeRequestConstants.TABLE_RELATIONSHIPS);

//Add the Reference Object with the createRow() 
   API HashMap map = new HashMap();   map.put(CommonConstants.ATT_RELATIONSHIPS_NAME, refObject);   IRow targetRow = relTbl.createRow(map);

11.6 Removing Reference ObjectS from Relationships Tab of the Web Client

To Delete or remove a Reference Object from the Relationships table in the Web Client, use the removeRow(IRow row) API. This is similar to deleting other object types in Agile PLM tables.

11.7 Searching for Reference Objects TOHERE

Use the getCell (ReferenceObject .....) API to search for Reference Objects. This is shown in the following example.

Example 11-4 Searching for Reference Objects

ITable searchResult = doSearch("RemoteItems", "P0000");ArrayList objects = doCreate("RemoteItems", searchResult);//Search the external system and retrieve the referenced objects in Tablular format:private static ITable doSearch(String subClassName, String srchStr) throws APIException {ITable results = null;try {//qry = "[Title Block.Name/Number/Desc] contains '"+srchStr+"'";String qry = "["+ReferenceObjectConstants.SEARCH_KEY+"]"+ " contains '"+srchStr+"'";IQuery query = (IQuery)session.createObject(IQuery.OBJECT_TYPE, RefObjSubClassName);query.setCaseSensitive(false);query.setCriteria(qry);results = query.execute();
}catch (APIException ex) {System.out.println(ex);}return results;}//Create the Reference Objects retrieved by IRows in the above search:private static ArrayList doCreate(String subClassName, ITable qryResult) throws APIException{ArrayList result = new ArrayList();IDataObject refObj = null;try{Iterator itr = qryResult.getTableIterator();while(itr.hasNext()){IRowReferenceObjectWebServiceSearch row = (IRowReferenceObjectWebServiceSearch) itr.next();//String name = row.getName(); // get RowReferenceObjectWebServiceSearch.java from sc branch.String name = row.getValue(ReferenceObjectConstants.ATT_GENERAL_INFO_NUMBER).toString();String pubKey = row.getPublicKey();String description = row.getValue(ReferenceObjectConstants.ATT_GENERAL_INFO_DESCRIPTION).toString();String url = row.getUrl();Map params = createParams(subClassName, name, pubKey, description, url);refObj = (IReferenceObject) session.getObject(ReferenceObjectConstants.CLASS_REFERENCE_OBJECT_CLASS, params);if (refObj==null)refObj = (IReferenceObject) session.createObject(subClassName, params);result.add(refObj);}} catch(APIException ex) {throw ex;}return result;}