Skip Headers

Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-01 |
| Contents

Previous | Next |

# 5 Working with Data Cells

An ICell object is a data field for an Agile PLM object that you have loaded or created in your program. A cell can correspond to a field on a tab in Agile Web Client or a single cell on a table. The ICell object consists of several properties that describe the current state of a cell. Most of the data manipulation your Agile API programs perform will involve changes to the value or properties of cells.

## 5.1 Data Types

The type of objects associated with the getValue() and setValue() methods depends on the cell's data type. The table below lists the object types of cell values for getValue() and setValue() methods.

DataTypeConstants | Object type associated with getValue and setValue
--- | ---
TYPE_DATE | Date
TYPE_DOUBLE | Double
TYPE_INTEGER | Integer
TYPE_MONEY | Money
TYPE_MULTILIST | IAgileList
TYPE_OBJECT | Object
TYPE_SINGLELIST | IAgileList
TYPE_STRING | String
TYPE_TABLE | Table

Note: There are other Agile PLM datatypes, such as TYPE_WORKFLOW, but they are not used for cell values.

## 5.2 Checking the Discovery Privilege of the User

The Discovery privilege is the most basic Agile PLM privilege. It allows users to find if an object exists. If you do not have the Discovery privilege for an object, you won't be able to view that object.

For example, if a user does not have the Discovery privilege for Manufacturer Parts, your program will not allow the user to view several cells on the Manufacturers table of an item. You can use the ICell.hasDiscoveryPrivilege() method to check if the user has the Discovery privilege for a particular cell, as shown in the following example.

Note: When you get the value for a cell for which you don't have the Discovery privilege, the Agile API returns a null string (""). This behavior is different with other Agile PLM Clients. For example, Agile Web Client displays the value "No Privilege" when you try to view a field for which you don't have the necessary viewing privileges.

Example: Checking Discovery privilege

    Object v;
    Integer attrID = ItemConstants.ATT_MANUFACTURERS_MFR_NAME;
    try {
    // Get the Manufacturers table
     ITable aml =

item.getTable(ItemConstants.TABLE_MANUFACTURERS);

    // Get the first row of the Manufacturers table
    IIterator iterator =

aml.getTableIterator();

    if (iterator.hasNext()) {
    IRow amlRow =

(IRow)iterator.next();

    }
    Integer attrID = ItemConstants.ATT_TITLE_BLOCK_NUMBER;
    // Get the value for the Mfr. Name field.
    // If the user does not have Discovery privilege, the value is a null String.
     v = amlRow.getValue(attrID);
      txtMfrName.setText(v.toString());
    // If the user does not have the Discovery privilege
    // for the cell, make its text color red.
     ICell cell =
    amlRow.getCell(attrID);
     if (cell.hasDiscoveryPrivilege()==false) {
    txtMfrName.setForeground(Color.red);
     }
    } catch (APIException ex) {
      System.out.println(ex);
    }

## 5.3 Checking if the Cell is a Read-Only Cell

Roles and privileges assigned to a user by Agile PLM administrators, determine the level of access the user has to Agile PLM objects and their underlying data. For example, users with only ReadOnly privileges can view Agile PLM objects but not modify them.

Whenever your program displays a value from a cell, you should check whether the cell is read-only for the current user. If it is, your program must not allow the user to edit the value. If a user tries to set a value for a read-only cell, the Agile API throws an exception.

Example: Checking whether a field is a read-only field

    // ID for "Title Block.Description"
    // Set the value for the Description text field.
    try {

Integer attrID = ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION;

txtDescription.setText(item.getValue(attrID).toString());

    // Get the ICell object for "Title Block.Description"
    // If the cell is read-only, disable the cell

ICell cell = item.getCell(attrID);

if (cell.isReadOnly()) {

txtDescription.setEnabled(false);

txtDescription.setBackground(Color.lightGray);

}

else {

txtDescription.setEnabled(true);

txtDescription.setBackground(Color.white);

}

} catch (APIException ex) {

System.out.println(ex);

    }

## 5.4 Getting Values

The following table lists Agile API methods for getting values for cells.

Method | Description
--- | ---
ICell.getValue() | Gets a cell value
IRow.getValue() | Gets a cell value contained within a row
IRow.getValues() | Gets all cell values contained within a row
IDataObject.getValue() | Gets a cell value on Page One, Page Two, or Page Three

Before working with a cell's value, you must select the cell. Agile PLM cells are instances of attributes. To specify the attribute for a cell, specify either the attribute's ID constant, it's fully qualified name (such as "Title Block.Description"), or an IAttribute object. For more information about referencing attributes, see Referencing Attributes in SDK Developer Guide - Developing PLM Extensions.

Note: You can use ICell getAPIName() to access Data Cell attribute values. For information to use this field, see Accessing PLM Metadata with APIName Field on page 135.

The following example shows how to reference a cell by attribute ID constant.

Example: Specifying a cell by ID

    Object v;
    try {
      v = item.getValue(attrID);
    } catch (APIException ex) {
      System.out.println(ex);
    }

The following example shows how to reference a cell by the fully qualified attribute name.

Example: Specifying a field by fully qualified name

    Object v;
    String attrName = "Title Block.Number";
    try {
      v = item.getValue(attrName);
    } catch (APIException ex) {
      System.out.println(ex);
    }

The method that you use to get a cell value depends on the current object in use by your program. Use the ICell.getValue() method if you have already retrieved an ICell object and want to retrieve a value.

Example: Getting a value using ICell.getValue()

    private static Object getCellVal(ICell cell) throws APIException {
    Object v;
      v = cell.getValue();
      return v;
    }

Quite often, your program will first retrieve an object, such as an item, and then use the IDataObject.getValue(java.lang.Object cellId) method to retrieve values for it.

Example: Getting a value using IDataObject.getValue(Object cellID)

    private static Object getDescVal(IItem item) throws APIException {
    Integer attrID = ItemConstants.ATT_TITLE_BLOCK_NUMBER;

Integer attrID = ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION;

Object v;

v = item.getValue(attrID);

return v;

    }

The object returned by the getValue() method is of the same data type as the Agile PLM attribute. For more information about data types, see Data Types.

Note: All cells in a table returned by a query contain String values regardless of the datatypes associated with those cells. For more information about query result tables, see Working with Query Results.

If you are iterating over rows in an Agile PLM table, you can use the IRow.getValues() method to retrieve a Map object containing all cell values for a particular row in the table. The returned Map object maps attribute ID keys to cell values.

### 5.4.1 Understanding SDK Date Formats and User Preferences

In SDK, date is available as a Java Date object and does not format the date according to User Preferences. However, end users can convert it to their preferred format in GUI's User Preferences.

Important End users must use the GMT date format for PPM dates. For more information, refer to the Agile PLM Product Portfolio Management User Guide.

## 5.5 Getting Values

The following table lists Agile API methods for getting values for cells.

Method | Description
--- | ---
ICell.getValue() | Gets a cell value
IRow.getValue() | Gets a cell value contained within a row
IRow.getValues() | Gets all cell values contained within a row
IDataObject.getValue() | Gets a cell value on Page One, Page Two, or Page Three

Before working with a cell's value, you must select the cell. Agile PLM cells are instances of attributes. To specify the attribute for a cell, specify either the attribute's ID constant, it's fully qualified name (such as "Title Block.Description"), or an IAttribute object. For more information about referencing attributes, see Referencing Attributes.

Note: You can use ICell getAPIName() to access Data Cell attribute values. For information to use this field, see Accessing PLM Metadata with APIName Field on page 135.

The following example shows how to reference a cell by attribute ID constant.

Example: Specifying a cell by ID

    Object v;
    try {
      v = item.getValue(attrID);
    } catch (APIException ex) {
      System.out.println(ex);
    }

The following example shows how to reference a cell by fully a qualified attribute name.

Example: Specifying a field by fully qualified name

    Object v;
    String attrName = "Title Block.Number";
    try {
      v = item.getValue(attrName);
    } catch (APIException ex) {
      System.out.println(ex);
    }

The method that you use to get a cell value depends on the current object in use by your program. Use the ICell.getValue() method if you have already retrieved an ICell object and want to retrieve a value.

Example: Getting a value using ICell.getValue()

    private static Object getCellVal(ICell cell) throws APIException {
    Object v;
      v = cell.getValue();
      return v;
    }

Quite often, your program will first retrieve an object, such as an item, and then use the IDataObject.getValue(java.lang.Object cellId) method to retrieve values for it.

Example: Getting a value using IDataObject.getValue(Object cellID)

    private static Object getDescVal(IItem item) throws APIException {
    // Get the Page Two List01 cell
      Integer attrID = ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION;
      Object v;
      v = item.getValue(attrID);
      return v;
    }

The object returned by the getValue() method is of the same data type as the Agile PLM attribute. For more information about data types, see Data Types.

Note: All cells in a table returned by a query contain String values regardless of the datatypes associated with those cells. For more information about query result tables, see Working with Query Results.

If you are iterating over rows in an Agile PLM table, you can use the IRow.getValues() method to retrieve a Map object containing all cell values for a particular row in the table. The returned Map object maps attribute ID keys to cell values.

## 5.6 Setting Values

The following table lists Agile API methods for setting values for cells.

Method | Description
--- | ---
ICell.setValue() | Sets a cell value
IRow.setValue() | Sets a cell value contained within a row
IRow.setValues() | Sets multiple cell values contained within a row
IDataObject.setValue() | Sets a cell value on Page One, Page Two, or Page Three
IDataObject.setValues() | Sets multiple cell values on Page One, Page Two, or Page Three

The method you use to set a value depends on the current object in use by your program.

Use the ICell.setValue() method if you've already retrieved an ICell object and want to set its value.

Example: Setting a value using ICell.setValue()

    private static void setDesc(ICell cell, String text) throws APIException {
    }

cell.setValue(text);

If your program has already retrieved an object, such as a part, you can use the IDataObject.setValue() method to set values for it.

Example: Setting a value using IDataObject.setValue()

    private void setDesc(IItem item, String text) throws APIException {

Integer attrID = ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION;

item.setValue(attrID, text);

    }

If you are iterating over rows in an Agile PLM table, you can use the IRow.setValues() method to set the cell values for an entire row. You can also use the IDataObject.setValues() method to set multiple cell values on Page One, Page Two, or Page Three of an object. The Map parameter you specify with setValues() maps attributes to cell values.

Example: Setting multiple values in a row using IRow.setValues()

    private void setBOMRow(IRow row) throws APIException {

Map map = new HashMap();

map.put(ItemConstants.ATT_BOM_ITEM_NUMBER, "23-0753");

map.put(ItemConstants.ATT_BOM_QTY, "1");

map.put(ItemConstants.ATT_BOM_FIND_NUM, "0");

    }

row.setValues(map);

When you set an Agile PLM value, you must know the cell's data type. If you try to set a cell's value using an object of the wrong data type, the method fails. You may need to cast the object to another class before using it to set a value.

Note: If you do not explicitly demarcate transactional boundaries in your code, every setValue() operation your program performs is treated as a separate transaction.

### 5.6.1 Catching Exceptions for Locked Objects

If someone else is modifying an object, it is temporarily locked by that user. If you try to set the value for a cell when another user has the object locked, your program will throw an exception. Therefore, whenever your program sets values of cells, make sure you catch the following Agile exceptions related to locked objects:

- ExceptionConstants.APDM_ACQUIRE_DBLOCK_FAILED

- ExceptionConstants.APDM_RELEASE_DBLOCK_FAILED

- ExceptionConstants.APDM_OBJVERSION_MISMATCH

You should also catch exception 813, which is related to locked objects.

The typical exception message that Agile PLM returns for a locked object is "Someone is working on this object. Please try again later."

For more information about how to handle exceptions, see Handling Exceptions on page 283 .

## 5.7 Getting and Setting List Values

There are two different datatypes for list cells. One for SingleList and one for MultiList cells. When you get the value for a SingleList or MultiList cell, the object returned is an IAgileList object. For that reason, list cells are slightly more complicated to work with than other cells. The IAgileList interface provides methods for getting and setting the current list selection. This section provides examples showing how to get and set values for different types of Agile PLM lists, including cascading lists.

When you use ICell.getAvailableValues() to get the available values for a list cell, the returned IAgileList object may include obsolete list values. Your program should not permit users to set the value for a list cell to an obsolete value. For information on how to check whether a list value is obsolete, see Making List Values Obsolete on page 190.

When a list contains String values, the values are case-sensitive. This means that whenever you set the value for a list cell you must ensure that the value is the right case.

### 5.7.1 Getting and Setting Values for SingleList Cells

A SingleList cell allows you select one value from the list. When you get the value for a SingleList cell, the object returned is an IAgileList. From that IAgileList object, you can determine what the currently selected value is. The following example shows how to get and set values for the "Title Block.Part Category" cell for an item.

Example: Getting and setting the value for a SingleList cell

    private static String getPartCatValue(IItem item) throws APIException {
    // Get the Part Category cell

ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PART_CATEGORY);

    // Get the current IAgileList object for Part Category
    // Get the current value from the list

IAgileList cl = (IAgileList)cell.getValue();

String value = null;

IAgileList[] selected = cl.getSelection();

if (selected != null && selected.length > 0) {

value = (selected[0].getValue()).toString();

}

return value;

}

private static void setPartCatValue(IItem item) throws APIException {

    // Get the Part Category cell
    // Get available list values for Part Category

ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PART_CATEGORY);

IAgileList values = cell.getAvailableValues();

    // Set the value to Electrical

values.setSelection(new Object[] { "Electrical" });

cell.setValue(values);

    }

### 5.7.2 Getting and Setting Values for MultiList Cells

A MultiList cell behaves very similar to a SingleList cell except that it allows you to select multiple values. A MultiList cell cannot be a cascading list. The following example shows how to get and set values for a MultiList cell, "Title Block.Product Line(s)" for an item.

Example: Getting and setting the value for a MultiList cell

    private static String getProdLinesValue(IItem item) throws APIException {
    // Get the Product Lines cell

String prodLines;

ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PRODUCT_LINES);

    // Get the current IAgileList object for Product Lines
    // Convert the current value from the list to a string

IAgileList list = (IAgileList)cell.getValue();

prodLines = list.toString();

return prodLines;

    }
    private static void setProdLinesValue(IItem item) throws APIException {
    // Get the Product Lines cell

ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PRODUCT_LINES);

    // Get available list values for Product Lines
    // Set the Product Lines values

IAgileList values = cell.getAvailableValues();

values.setSelection(new Object[] {"Saturn","Titan","Neptune"});

cell.setValue(values);

    }

### 5.7.3 Getting and Setting Values for Cascading Lists

A SingleList cell can be configured to be a cascading list. A cascading list presents a list in multiple hierarchical levels, letting you drill down to a specific value in the list hierarchy. For more information about working with cascading lists, see Working with Lists on page 171.

When you get the value for a cascading list cell, a vertical bar (also called a piping character) separates each level in the cascading list. To select the value for a cascading list, use the IAgileList.setSelection() method. You can specify either an array of IAgileList leaf nodes or a String array containing one string delimited by vertical bars. After you select the value, save it using one of the setValue() methods.

The following example shows how to get and set the value for a cascading list.

Example: Getting and setting the value for a cascading list

    private String getCascadeValue(IItem item) throws APIException {

String value = null;

    // Get the Page Two.List01 value

IAgileList clist =

(IAgileList)item.getValue(ItemConstants.ATT_PAGE_TWO_LIST01);

    // Convert the current value from the list to a string

value = clist.toString();

return value;

    }

private void setCascadeValue(IItem item) throws APIException {

String value = null;

    // Get the Page Two List01 cell
    // Get available list values for Page Two List01

ICell cell = item.getCell(ItemConstants.ATT_PAGE_TWO_LIST01);

IAgileList values = cell.getAvailableValues();

    // Set the value to "North America|United States|San Jose"

values.setSelection(new Object[] {"North America|United States|San Jose"});

cell.setValue(values);

    }

Although the previous example shows one way to set the value for a cascading list, there's another longer form you can use that illustrates the tree structure of the list. Instead of specifying a single String to represent a cascading list value, you can set the selection for each level in the list. The following example selects a value for a cascading list with three levels: continent, country, and city.

Example: Setting the value for a cascading list (long form)

    private void setCascadeValue(IItem item) throws APIException{

ICell cell = item.getCell(CommonConstants.ATT_PAGE_TWO_LIST01);

    // Get available list values for Page Two List01
    // Set the continent to "North America"

IAgileList values = cell.getAvailableValues();

IAgileList continent = (IAgileList)values.getChildNode("North America");

    // Set the country to "United States"
    // Set the city to "San Jose"

IAgileList country = (IAgileList)continent.getChildNode("United States");

IAgileList city = (IAgileList)country.getChildNode("San Jose");

values.setSelection(new Object[]{city});

    // Set the cell value
    }

cell.setValue(values);

## 5.8 Using Reference Designator Cells

You can control how to use reference designator cells with Agile 9 SDK. You can make reference designator cells render collapsed or expanded depending on your system setting. The IReferenceDesignatorCell interface contains three public APIs that allow the end user to retrieve reference designator information in three formats:

- Collapsed-for example A1-A3; use getCollapsedValue()

- Expanded-A1, A2, A3; use getExpandedValue()

- Array of individual reference designators-[A1, A2, A3]; use getReferenceDesignators[]

The following table lists Agile API methods for retrieving reference designator values for cells.

Method | Description
--- | ---
IReferenceDesignatorCell.getCollapsedValue() | Gets a collapsed representation of the reference designators. For example, "A1,A2,A3" would be represented as "A1-A3". Note that the range separator, ("-") is defined as part of the system preferences.
IReferenceDesignatorCell.getExpandedValue() | Gets an expanded value of a reference designator. For example, for "A1-A3" the string, "A1, A2, A3" would be returned.
IReferenceDesignatorCell.getReferenceDesignators() | Gets the individual reference designators as an array of strings. For example, for "A1-A3" an array of these three strings, ["A1", "A2", "A3"] would be returned.

Note: In previous releases of Agile SDK, the value of a reference designator was a comma-delimited list of reference designators. Because the functionality of cell.getValue() for a reference designator will depend on the system setting controlling reference designator presentation, the SDK user should not use cell.getValue() or row.getValue(). We recommend that you get the cell and cast it into an IReferenceDesignatorCell; then call the method that corresponds to your desired data structure for processing or displaying reference designator information