Skip Headers

Agile Product Lifecycle Management Web Services Guide Release 9.3.3 E39310-01 |
| Contents

Previous | Next |

# 3 Working with Business Objects

This chapter describes how you can work with Agile PLM Business Objects and also provides sample code snippets.

## 3.1 Getting an Object

To get an Agile PLM object, use the getObject operation. This operation lets you specify the objectType and objectNumber parameters.

An objectType is the API name or ID of a Subclass. For example, a 'Part' is an objectType of the Agile Class 'Item'; ECO is an objectType of the Agile Class 'Change'. An objectNumber is number of the Agile Object being retrieved.

The actual information about the object is obtained through the response in the form of AgileObjectType objects.

Use the following syntax to get an object by specifying objectType and objectNumber parameters, as shown in examples.

    GetObjectRequestType getObjectRequestType = new GetObjectRequestType();
    AgileGetObjectRequest agileGetObjectRequest[] = new AgileGetObjectRequest[1];
    agileGetObjectRequest[0] = new AgileGetObjectRequest();
    agileGetObjectRequest[0].setClassIdentifier("objectType");
    agileGetObjectRequest[0].setObjectNumber("objectNumber");

Example: Getting an Item

    GetObjectRequestType getObjectRequestType = new GetObjectRequestType();
    AgileGetObjectRequest agileGetObjectRequest[] = new AgileGetObjectRequest[1];
    agileGetObjectRequest[0] = new AgileGetObjectRequest();
    agileGetObjectRequest[0].setClassIdentifier("Part");
    agileGetObjectRequest[0].setObjectNumber("P00001");

Example: Getting a Change

    GetObjectRequestType getObjectRequestType = new GetObjectRequestType();
    AgileGetObjectRequest agileGetObjectRequest[] = new AgileGetObjectRequest[1];
    agileGetObjectRequest[0] = new AgileGetObjectRequest();
    agileGetObjectRequest[0].setClassIdentifier("ECO");
    agileGetObjectRequest[0].setObjectNumber("ECO-0001");

Note: The getObject operation request for the resource types User, Owner and UserGroup returns a response in integer values. These values are mapped as: 11605 = User, 18044 = Owner, 11885 = User Group.

### 3.1.1 Special Handling in the getObject Operation

To get certain Agile Objects, the getObject operation requires an additional parameter to be set. This parameter, setOptions(propertyType), accepts a name-value pair - propertyName and propertyValue.

Example: Getting a Manufacturer Part

    GetObjectRequestType getObjectRequestType = new GetObjectRequestType();
    AgileGetObjectRequest agileGetObjectRequest[] = new AgileGetObjectRequest[1];
    agileGetObjectRequest[0] = new AgileGetObjectRequest();
    agileGetObjectRequest[0].setClassIdentifier("ManufacturerPart");
    agileGetObjectRequest[0].setObjectNumber("manufPartNumber");
    PropertyType[] propertyType =  new PropertyType[1];
    propertyType[0] = new PropertyType();
    propertyType[0].setPropertyName( SchemaConstants.manufacturer_name.getValue() );
    propertyType[0].setPropertyValue(manufName);
    agileGetObjectRequest[0].setOptions(propertyType);

## 3.2 Creating an Object

To create a new Agile PLM object, use the createObject operation. This operation requires you to specify the objectType parameter, for example, a Part.

Example: Creating a Part

    CreateObjectRequestType createObjectRequestType = new CreateObjectRequestType();
    AgileCreateObjectRequest agileCreateObjectRequest[] = new AgileCreateObjectRequest[1];
    agileCreateObjectRequest[0].setClassIdentifier("Document");
    AgileRowType row_1 = new AgileRowType();
    MessageElement messages_1[] = new MessageElement[2];
    String namespaceUri = null;
    messages_1[0] = new MessageElement(namespaceUri, "number");
    messages_1[0].addTextNode(documentNumber);
    messages_1[1] = new MessageElement(namespaceUri, "description");
    messages_1[1].addTextNode("Doc Desc");

Note: Agile Web services do not support setting the Life Cycle Phase (LCP)/workflow status attribute of an object while you are creating that object because the necessary settings for LCP are not available until the object is created.

## 3.3 Creating a Reference Object

To create a new reference object, use the createReferenceobject operation.

Example: Creating a Reference Object

    CreateObjectRequestType createObjectRequestType = new CreateObjectRequestType();
    AgileCreateObjectRequest agileCreateObjectRequest[] = new AgileCreateObjectRequest[1];
    agileCreateObjectRequest[0] = new AgileCreateObjectRequest();
    agileCreateObjectRequest[0].setClassIdentifier(refSubclassName);
    AgileRowType row_1 = new AgileRowType();
    MessageElement messages_1[] = new MessageElement[3];
    String namespaceUri = null;
    messages_1[0] = new MessageElement(namespaceUri, "Name");
    messages_1[0].addTextNode( objectNumber );
    messages_1[1] = new MessageElement(namespaceUri, "Description");
    messages_1[1].addTextNode("Object Desc");
    messages_1[2] = new MessageElement(namespaceUri, "referencedObjKey");
    messages_1[2].addTextNode(refPubKey);
    row_1.set_any(messages_1);
    agileCreateObjectRequest[0].setData(row_1);
    createObjectRequestType.setRequests(agileCreateObjectRequest);
    CreateObjectResponseType createObjectResponseType = businessObjectStub.createObject(createObjectRequestType);

## 3.4 Saving As a New Object

You can save an existing Agile object as a new object by using the saveAsObject operation. This operation calls AgileSaveAsObjectRequestType, which requires the values of objectName, objectNumber and newObjectName.

You can specify a newObjectNumber as a MessageElement to generate a number for a new object, as shown in the following syntax.

Example: Saving as a new object

    SaveAsObjectRequestType saveAsObjectRequestType = new SaveAsObjectRequestType();
    AgileSaveAsObjectRequestType agileSaveAsObjectRequestType[] = new AgileSaveAsObjectRequestType[1];
    agileSaveAsObjectRequestType[0].setParentClassIdentifier("objectName");
    agileSaveAsObjectRequestType[0].setParentObjectNumber("objectNumber");
    agileSaveAsObjectRequestType[0].setNewClassIdentifier("newObjectName");

AgileRowType row = new AgileRowType();

MessageElement messages[] = new MessageElement[1];

String namespaceUri = null;

messages[0] = new MessageElement(namespaceUri, "TagName");

messages[0].addAttribute(namespaceUri, "attributeId", "Attribute ID" );

messages[0].addTextNode(newObjectNumber);

row.set_any(messages);

agileSaveAsObjectRequestType[0].setData(row);

You can also use autoNumberSource to generate number for a new object, using the following syntax:

    SaveAsObjectRequestType saveAsObjectRequestType = new SaveAsObjectRequestType();
    AgileSaveAsObjectRequestType agileSaveAsObjectRequestType[] = new AgileSaveAsObjectRequestType[1];
    agileSaveAsObjectRequestType[0].setParentClassIdentifier("objectName");
    agileSaveAsObjectRequestType[0].setParentObjectNumber("objectNumber");
    agileSaveAsObjectRequestType[0].setNewClassIdentifier("newObjectName");
    agileSaveAsObjectRequestType[0].setAutoNumberSource("autoNumberSource");

See "Getting the AutoNumbers," for more details.

Example: Saving a Part as a new part

    SaveAsObjectRequestType saveAsObjectRequestType = new SaveAsObjectRequestType();
    AgileSaveAsObjectRequestType agileSaveAsObjectRequestType[] = new AgileSaveAsObjectRequestType[1];
    agileSaveAsObjectRequestType[0].setParentClassIdentifier("Part");
    agileSaveAsObjectRequestType[0].setParentObjectNumber(partNumber1);
    agileSaveAsObjectRequestType[0].setNewClassIdentifier("Part");

AgileRowType row = new AgileRowType();

MessageElement messages[] = new MessageElement[1];

String namespaceUri = null;

messages[0] = new MessageElement(namespaceUri, "Message_Num");

messages[0].addTextNode(newPartNumber);

row.set_any(messages);

agileSaveAsObjectRequestType[0].setData(row);

saveAs reference of the query cannot be in the same folder as the actual query. Multiplequery saveAs references cannot be created for the same query object in the same folder. While the first operation will work fine, the concurrent operations will fail.

### 3.4.1 Special Handling in the saveAsObject Operation

In case of saving an object as a Program, you need to specify the TemplateType -Active, Template or Proposed. Optionally, you can also pass additional attributes, such as Scheduled Start Data, Tables to be copied, Apply to children, etc.

Note: The default TemplateType of a Program is Active.

Example: Saving an object as a program of type template

    SaveAsObjectRequestType saveAsObjectRequestType = new SaveAsObjectRequestType();
    AgileSaveAsObjectRequestType agileSaveAsObjectRequestType[] = new AgileSaveAsObjectRequestType[1];
    agileSaveAsObjectRequestType[0] = new AgileSaveAsObjectRequestType();
    agileSaveAsObjectRequestType[0].setParentClassIdentifier("Program");
    agileSaveAsObjectRequestType[0].setParentObjectNumber( parentProgramNumber );
    agileSaveAsObjectRequestType[0].setNewClassIdentifier("Program");
    AgileRowType row = new AgileRowType();

MessageElement messages[] = new MessageElement[1];

String namespaceUri = null;

messages[0] = new MessageElement(namespaceUri, "name");

messages[0].addTextNode(newProgramNumber);

row.set_any(messages);

agileSaveAsObjectRequestType[0].setData(row);

PropertyType properties[] = new PropertyType[1];

properties[0] = new PropertyType();

properties[0].setPropertyName( SchemaConstants.program_template.getValue() );

properties[0].setPropertyValue("Template");

agileSaveAsObjectRequestType[0].setOptions(properties);

String tables[] = {"PageTwo", "Team"};

    agileSaveAsObjectRequestType[0].setTablesToCopy(tables);
    agileSaveAsObjectRequestType[0].setApplyToChildren(true);

When you create a program, you can specify that it is a template by setting the value of the Template attribute to ”Template”. You can do this only when you create a program or when you save it as a new program. Existing programs cannot be changed from the ”Active” or ”Proposed” state to ”Template”.

## 3.5 Deleting and Undeleting an Object

The deletion of an object in Agile is of two types - soft delete and hard delete.

With soft delete, which is carried out using the operation deleteObject, the object is marked as 'Deleted'. It is however not removed from the database, so that it can be restored using the operation undeleteObject. A soft-deleted object does not appear in search results, however with the operation isDeletedObject you can find these deleted objects.

With hard delete, the object is removed from the database permanently. These objects do not appear in search queries or pre-defined query results.

Note: To delete and undelete an object, you must have Delete and Undelete privileges, respectively, for the particular object type. However, soft-deleted changes that have items on the Affected Items tab cannot be restored, regardless of the user's privileges.

Not all Agile PLM objects can be deleted. If you attempt to delete these objects, the deleteObject operation throws an exception. Also, if you try to delete an Item that is used on the BOM tab of another item, the Agile PLM server throws an exception.

Some of the objects that cannot be deleted are:

- An item with a pending change

- An item with a revision history

- An item with a canceled change

- A released change

- A manufacturer with one or more manufacturer parts

- A manufacturer part currently used on the Manufacturers tab of another object

Example: Deleting a part

    DeleteObjectRequestType deleteObjectRequestType = new DeleteObjectRequestType();
    AgileDeleteObjectRequest agileDeleteObjectRequest[] = new AgileDeleteObjectRequest[1];
    agileDeleteObjectRequest[0] = new AgileDeleteObjectRequest();
    agileDeleteObjectRequest[0].setClassIdentifier("Part");
    agileDeleteObjectRequest[0].setObjectNumber(partNumber);

Example: Undeleting a part

    UndeleteObjectRequestType undeleteObjectRequestType = new UndeleteObjectRequestType();
    AgileUndeleteObjectRequest agileUndeleteObjectRequest[] = new AgileUndeleteObjectRequest[1];
    agileUndeleteObjectRequest[0] = new AgileUndeleteObjectRequest();
    agileUndeleteObjectRequest[0].setClassIdentifier("Part");
    agileUndeleteObjectRequest[0].setObjectNumber(partNumber);

### 3.5.1 Checking the Delete Status

You can verify whether an Object has been deleted or not by using the isDeletedObject operation.

Example: Checking if a part is deleted

    IsDeletedObjectRequestType isDeletedObjectRequestType = new IsDeletedObjectRequestType();
    AgileIsDeletedObjectRequest agileIsDeletedObjectRequest[] = new AgileIsDeletedObjectRequest[1];
    agileIsDeletedObjectRequest[0] = new AgileIsDeletedObjectRequest();
    agileIsDeletedObjectRequest[0].setClassIdentifier("Part");
    agileIsDeletedObjectRequest[0].setObjectNumber(partNumber);

## 3.6 Deleting a Reference Object

To delete a reference object use the deleteReferenceobject operation. This operation lets you specify the objectType and objectNumber parameters.

Example: Deleting a Reference Object

    DeleteObjectRequestType deleteObjectRequestType = new DeleteObjectRequestType();
    AgileDeleteObjectRequest agileDeleteObjectRequest[] = new AgileDeleteObjectRequest[1];
    agileDeleteObjectRequest[0] = new AgileDeleteObjectRequest();
    agileDeleteObjectRequest[0].setClassIdentifier(refSubclassName);
    agileDeleteObjectRequest[0].setReferencedObjKey(refObjPubKey);  //optional
    agileDeleteObjectRequest[0].setObjectNumber(refObjName);  //ignored if refObjPubKey is provided
    deleteObjectRequestType.setRequests(agileDeleteObjectRequest);
    DeleteObjectResponseType deleteObjectResponseType = businessObjectStub.deleteObject(deleteObjectRequestType);

## 3.7 Updating an Object

You can update any object with the operation updateObject by setting the values of the desired attributes.

Example: Updating a Part

    UpdateObjectRequestType updateObjectRequestType = new UpdateObjectRequestType();
    AgileUpdateObjectRequest agileUpdateObjectRequest[] = new AgileUpdateObjectRequest[1];
    agileUpdateObjectRequest[0] = new AgileUpdateObjectRequest();
    agileUpdateObjectRequest[0].setClassIdentifier("Part");
    agileUpdateObjectRequest[0].setObjectNumber(partNumber);

AgileRowType rows = new AgileRowType();

MessageElement messages[] = new MessageElement[1];

String namespaceUri = null;

messages[0] = new MessageElement(namespaceUri, "Message_Desc");

messages[0].addTextNode("Updated value of Doc Description");

rows.set_any(messages);

agileUpdateObjectRequest[0].setData(rows);

## 3.8 Updating a Reference Object

To update a reference object you need to use the updateReferenceObject operation. This operation lets you specify the objectType and objectNumber parameters.

Example: Updating a Reference Object

    UpdateObjectRequestType updateObjectRequestType = new UpdateObjectRequestType();
    AgileUpdateObjectRequest agileUpdateObjectRequest[] = new AgileUpdateObjectRequest[1];
    agileUpdateObjectRequest[0] = new AgileUpdateObjectRequest();
    agileUpdateObjectRequest[0].setClassIdentifier(refSubclassName);
    agileUpdateObjectRequest[0].setReferencedObjKey(refObjPubKey); //optional
    agileUpdateObjectRequest[0].setObjectNumber(refObjName); //ignored if refObjPubKey is provided
    AgileRowType rows = new AgileRowType();
    MessageElement messages[] = new MessageElement[4];
    String namespaceUri = null;
    messages[0] = new MessageElement(namespaceUri, "Message_Name");
    messages[0].addAttribute(namespaceUri, "attributeId", ReferenceObjectConstants.ATT_GENERAL_INFO_NUMBER.toString());
    messages[0].addTextNode(newName);
    messages[1] = new MessageElement(namespaceUri, "Message_Desc");
    messages[1].addAttribute(namespaceUri, "attributeId", ReferenceObjectConstants.ATT_GENERAL_INFO_DESCRIPTION.toString());
    messages[1].addTextNode(newDescription);
    messages[2] = new MessageElement(namespaceUri, "Message_Status");
    messages[2].addAttribute(namespaceUri, "attributeId", ReferenceObjectConstants.ATT_GENERAL_INFO_STATUS.toString());
    messages[2].addTextNode(newStatus);
    messages[3] = new MessageElement(namespaceUri, "Message_URL");
    messages[3].addAttribute(namespaceUri, "attributeId", ReferenceObjectConstants.ATT_GENERAL_INFO_URL.toString());
    messages[3].addTextNode(newURL);
    rows.set_any(messages);
    agileUpdateObjectRequest[0].setData(rows);
    updateObjectRequestType.setRequests(agileUpdateObjectRequest);
    UpdateObjectResponseType updateObjectResponseType = businessObjectStub.updateObject(updateObjectRequestType);

## 3.9 Getting the Status of an Object

In a workflow or a lifecycle, a routable object passes through various states. Subsequent action on this object requires ascertaining its current state, the states it has already crossed and the states it must go through. This information is obtained using the operation getStatus.

The response object will consist of AgileStatusType objects for nextDefaultStatus, nextValidStatuses, currentStatus. For complete details, refer Schema Documentation at Oracle eDelivery Site.

Example: Getting the status of an ECO

    GetStatusRequestType getStatusRequestType = new GetStatusRequestType();
    AgileGetStatusRequestType agileGetStatusRequestType[] = new AgileGetStatusRequestType[1];
    agileGetStatusRequestType[0] = new AgileGetStatusRequestType();
    agileGetStatusRequestType[0].setClassIdentifier("ECO");
    agileGetStatusRequestType[0].setObjectNumber( changeNumber );

## 3.10 Getting the AutoNumbers

An AutoNumber source is a predefined sequence of numbers that automatically assign a number to an object. An Agile PLM class can have one or more AutoNumber sources. These are defined in the Admin node of the Agile Java Client.

To get a 'next in sequence' AutoNumber, specify the autoNumberSource and objectType attributes in the operation getAutoNumbers.

Note: The Manufacturers and Manufacturer Parts classes, and their user-defined subclasses, do not support automatic numbering.

Example: Getting Autonumbers for Part Class

    GetAutoNumbersRequestType getAutoNumbersRequestType = new GetAutoNumbersRequestType();
    AgileGetAutoNumbersRequestType agileGetAutoNumbersRequestType[] = new AgileGetAutoNumbersRequestType[2];
    agileGetAutoNumbersRequestType[0].setClassIdentifier("Part");
    agileGetAutoNumbersRequestType[0].setAutoNumberIdentifier( new String[]{"PartNumber"} );
    agileGetAutoNumbersRequestType[0].setSize(3);

agileGetAutoNumbersRequestType[1].setClassIdentifier("ECO");

agileGetAutoNumbersRequestType[1].setIncludeAllAutoNumberSource(true);

agileGetAutoNumbersRequestType[1].setSize(2);

    getAutoNumbersRequestType.setRequests(agileGetAutoNumbersRequestType);
    AgileGetSubClassesRequestType agileGetSubClassesRequestType[] = new AgileGetSubClassesRequestType[1];

## 3.11 Getting all the Classes

You can retrieve the classes for each object type with the operation getAllClasses. Your program can then provide a method to pick the desired class from the list.

You can specify the ClassFilterType as follows:

ClassFilterType.ALL | To retrieve all the classes and their subclasses.
--- | ---
ClassFilterType.TOP | To retrieve all the classes only
ClassFilterType.CONCRETE | To retrieve all the subclasses only

The syntax for this operation is:

Syntax GetAllClassesRequestType getAllClassesRequestType = new GetAllClassesRequestType(); getAllClassesRequestType.setLevel(ClassFilterType.ALL);

## 3.12 Getting the Subclasses of a Class

Although you can retrieve all Subclasses by using the operation getAllClasses with ClassFilterType filter, you may require Subclasses of a particular Class. This is achieved by using the operation getSubClasses, in which, you specify the Agile API name of the desired Class.

ClassType objects are obtained from the response.

Example: Getting all subclasses of the class 'Changes'

    GetSubClassesRequestType getSubClassesRequestType = new GetSubClassesRequestType();
    agileGetSubClassesRequestType[0].setClassIdentifier("Changes");

## 3.13 Getting Agile Classes

Example: Getting Agile Classes

    GetAgileClassRequestType getAgileClassRequestType =
    new GetAgileClassRequestType();
    AgileGetClassRequestType[] agileGetClassRequestTypeArray =
        new AgileGetClassRequestType[1];
    agileGetClassRequestTypeArray[0] = new AgileGetClassRequestType();
    agileGetClassRequestTypeArray[0].setClassIdentifier("Part"); //API name of the class
    getAgileClassRequestType.setRequests(agileGetClassRequestTypeArray);