Skip Headers

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

Previous | Next |

# 8 Accessing PLM Metadata with APIName Field

The primary purpose of the APIName field is to facilitate SDK developers' access to internal Agile metadata when developing SDK applications. Prior to introduction of this field, display names or numeric IDs defined in the SDK Constants file were used to access Agile internal/metadata of objects in Classes, Tables, Attributes, Lists, and so on. The negative aspect of this approach is that numbers are difficult to remember and display names can change. However, an object's APIName is unique, it is easier to remember, and unlike DisplayName it is not subject to change which can break your code.

For example, your SDK application can use "AuditResult" which is the APIName of the List instead of its ID which is 6820, or its display name which is "Audit Result" to look up its internal value.

Figure 8-1 Accessing attribute value via API Name field

The following paragraphs describe the rules that assign a name to APIName fields and SDK interfaces that you can use in your SDK applications to access internal data with the APIName field.

Note: When upgrading to Release 9.3, it is possible to have duplicate APINames assigned to previously user defined fields. For example, if you have the user defined field "Foo" on P2 and P3, the upgrade tool will assign the APIName Foo to both fields. To avoid these duplications, change the APIName for one of these fields in the Java Client.

## 8.1 Assigning Names to APIName Fields

Names are automatically assigned to APIName fields by the PLM application when authorized users create new data objects in Java Client. Objects that support APIName have the additional "API Name" field in their Create dialog boxes which PLM immediately populates once a name is typed in the object's "Name" field.

The PLM assigned APIName converts the contents of the "Name" field using the CamelCase naming convention. The CamelCase convention is adhered to by Java JDK for all core APIs and closely resembles the name of the API. For example, the class "Manufacturer Parts" is converted to "ManufacturerParts" and the list "My new list" is converted to "MyNewList".

Figure 8-2 API name field

## 8.2 APIName Validation Rules

The APIName naming convention must adhere to the following rules:

- It can contain only characters

- It must be a valid Java/XML identifier

· Allowed characters are a-z, A-Z, 0-9, and _ (underscore)

- It must be between 1 and 255 characters long

- It is case-sensitive

- It must be unique within a context, for example:

· The attribute "Number" can exist in the cover page table for classes "Parts" as well as "Changes" (Different context, Parts & Changes)

· Two attributes with APIName "Number" cannot exist in the cover page table of "Parts" (Same context, Parts cover page)

· Two attributes with APIName "Number" cannot exist in Cover Page, Page Two and Page Three (Cover Page, Page Two and Page Three are a single context)

## 8.3 Accessing Metadata Using the APIName Field

You can use the API name of the Agile Metadata to:

- Access the metadata of Agile PLM (Node, Class, Attribute)

- Access/manipulate the value of the metadata (attributes and table attributes) of a data object

You can view the API name of Nodes, Classes, and Attributes in Java Client. SDK interfaces that support the APIName field are listed in the following tables.

### 8.3.1 APIs that Support the APIName Field

API | Example
--- | ---
IAdmin
getAgileClass(Object id) | getAgileClass("Parts")
getNode(Object id) | getNode ("Part.TitleBlock")
IAgileClass
getAttribute (Object key) | getAttribute("TitleBlock.number") or, getAttribute("number")
getTableAttributes(Object tableId) | getTableAttributes("TitleBlock")
getTableDescriptor (Object id) | getTableDescriptor("TitleBlock")
isSubclassOf(Object cls) | isSubclassOf("Parts")
IAgileList
getChild(Object child) | getChild("UNITED_STATES") UNITED_STATES is the APIName for entry 'United States' in 'Country' list
getChildNode(Object child) | getChildNode("UNITED_STATES")
setSelection (Object[] childNodes) | setSelection(new Object[] {"UNITED_STATES" , "INDIA"})
IAgileSession
createObject(Object objectType, Object params) | Map map = new HashMap(); String partNumber = "P00001" map.put("TitleBlock.number", partNumber); IDataObject dObj = (IDataObject) (m_session.createObject("Part", map));
createObject(int objectType, Object params) | Map map = new HashMap(); String partNumber = "P00001" map.put("number", partNumber); IDataObject dObj = (IDataObject) (m_session.createObject("Part", map));
getObject(Object objectType, Object params) | Map map = new HashMap(); map.put("TitleBlock.number", "1000-01"); IDataObject dObj = (IDataObject) (m_session.getObject("Part", map));
getObject(int objectType, Object params) | Map map = new HashMap(); map.put("TitleBlock.number", "1000-01"); IDataObject dObj = (IDataObject)(m_session.getObject(IItem.OBJECT_TYPE, map));
IDataObject
getCell(Object key) | getCell("PageTwo.list11") or getCell("list11")
getTable(Object tableId) | getTable("AffectedItems")
getValue(Object attribute) | getValue ("PageTwo.list11") or getValue ("list11")
setValue(Object key,Object value) | setValue("PageTwo.text01","test")
saveAs(Object type,Object params) | Map params = new HashMap(); params.put("number", number); IItem part2 = (IItem) part.saveAs("Document", params);
setValues(Map map) | Map map = new HashMap(); map.put("TitleBlock.number", "1000-01"); part.setValues(map);
ILibrary
getAdminList(Object listId) | getAdminList("ActionStatus")
createAdminList(Map map) | map.put(IAdminList.ATT_NAME,"My List"); map.put(IAdminList.ATT_APINAME, "MyList"); map.put(IAdminList.ATT_DESCRIPTION, "My desc"); map.put(IAdminList.ATT_ENABLED, new Boolean(false)); map.put(IAdminList.ATT_CASCADED, new Boolean(false)); IAdmin admin = m_session.getAdminInstance(); IListLibrary listLibrary = admin.getListLibrary(); IAdminList newList = listLibrary.createAdminList(map);
INode
getChild(Object child) | IAdmin admin = m_session.getAdminInstance(); INode node = admin.getNode(NodeConstants.NODE_AGILE_CLASSES); INode partsClass = node.getChild("Parts");
getChildNode(Object child) | IAdmin admin = m_session.getAdminInstance(); INode node = admin.getNode("AgileClasses"); INode partsClass = node.getChildNode("Parts");
IProgram
saveAs (Object type, Object[] tablesToCopy, Object params) | HashMap map = new HashMap(); map.put("name", new_number); map.put("scheduleStartDate", new Date()); Object[] objects = new Object[]{"PageTwo", "PageThree", "Team"}; IProgram program2 = (IProgram)program.saveAs("Program", objects, map);
saveAs(Object type, Object[]tablesToCopy, Object params, boolean applyToChildren) | HashMap map = new HashMap(); map.put("name", new_number); map.put("scheduleStartDate", new Date()); Object[] objects = new Object[]{"PageTwo", "PageThree", "Team"}; IProgram program2 = (IProgram)program.saveAs("Program", objects, map, true);
IProject
assignSupplier(Object supplierParams) | HashMap map = new HashMap(); map.put("Responses.itemNumber", item.getName()); map.put("Responses.supplier", supplier.getName()); rfq.assignSupplier(map);
IQuery
setResultAttributes (Object[] attrs) | String[] attrs = new String[3]; attrs[0] = "TitleBlock.number"; attrs[1] = "TitleBlock.description"; attrs[2] = "TitleBlock.lifecyclePhase"; query.setResultAttributes(attrs);
IRequestForQuote
assignSupplier (Object supplierParams) | HashMap map = new HashMap(); map.put("Responses.itemNumber", item.getName()); map.put("Responses.supplier", supplier.getName()); rfq.assignSupplier(map);
ITable
createRow(Object param) | HashMap params = new HashMap(); params.put("itemNumber", "P0001"); params.put("newRev", "A"); ITable affectedItems = change.getTable("AffectedItems"); IRow affectedItemRow = affectedItems.createRow(params);
createRows(Object[] rows) |
getAvailableValues(Object attr) | getAvailableValues("PageTwo.list01")
updateRows (Map rows) | HashMap[] mapx = new HashMap[5]; Map rows = new HashMap(); mapx[0] = new HashMap(); mapx[0].put("newRev", "A"); mapx[0].put("text01", "sdk test1"); rows.put(rowArray[0], mapx[0]); mapx[1] = new HashMap(); mapx[1].put("newRev", "A"); mapx[1].put("text01", "sdk test2"); rows.put(rowArray[1], mapx[1]); tab.updateRows(rows);
ITableDesc
getAttribute (Object key) | getAttribute("number")

### 8.3.2 SDK APIs that Get the APIName Field

Interface | Method
IAdminList | getAPIName()
IAgileClass | getAPIName()
IAgileList | getAPIName() addChild(Object child, String apiName)
IAttribute | getAPIName()
ICell | getAPIName()
INode | getAPIName()
IProperty | getAPIName()
ITableDesc | getAPIName()

### 8.3.3 API Names of Root Administrator Nodes

The following table lists the API names of the top level Administrator nodes which are not exposed in Agile Java Client. Top Level Admin Nodes are Admin Nodes that exist on their own. That is, no other Admin Node must exist in order for these Admin nodes to exist. For example, Class and Roles are top level nodes, but Life Cycle Phases and Attributes are not because they belong to another Admin Node. Similarly, Workflow Statuses are not top level nodes because they belong to Workflow.

Root Node | API Name
ACS Responses | ACSResponses
Account Policy | AccountPolicy
Activity Statuses | ActivityStatuses
ActivityHealths | ActivityHealths
Agile Classes | AgileClasses
Agile Workflows | AgileWorkflows
Agile eHubs | AgileEHubs
Attachment Purge Setting | AttachmentPurgeSetting
AutoNumbers | AutoNumbers
Catchers | Catchers
Character Set | CharacterSet
Cluster | Cluster
Company Profile | CompanyProfile
Criteria Library | CriteriaLibrary
Dashboard Management | DashboardManagement
Default Role Settings | DefaultRoleSettings
Destinations | Destinations
Event Handler Types | EventHandlerTypes
Event Handlers | EventHandlers
Event Subscribers | EventSubscribers
Event Types | EventTypes
Events | Events
Example Role/Privilege | ExampleRolePrivilege
Filters | Filters
Full Text Search Settings | FullTextSearchSettings
Import Preference Setting | ImportPreferenceSetting
LDAPConfig | LDAPConfig
LifeCycle Phases | LifeCyclePhases
My Assignments | MyAssignments
Notification Templates | NotificationTemplates
PGC SmartRules | PGCSmartRules
Package File Types | PackageFileTypes
Portals | Portals
Preferences | Preferences
Privileges | Privileges
Process eXtension Library | ProcessEXtensionLibrary
Query Cleanup | QueryCleanup
RFQ Terms and Conditions | RFQTermsAndConditions
Reports | Reports
Roles | Roles
Server Location | ServerLocation
Sign Off Message | SignOffMessage
SmartRules | SmartRules
Subscribers | Subscribers
Task Configuration | TaskConfiguration
UOM Families | UOMFamilies
Viewer and Files | ViewerAndFiles
wCM Servers | WCMServers

### 8.3.4 API Name Examples

The following example shows how to log in to an Agile PLM server, create two parts, enable Page Two text 01 and List 20, set values for them, and then add the second part to the BOM Table of the first part.

Example: Using the APIName field to access metadata

    import com.agile.api.*;
    e.printStackTrace();
    import java.util.*;

    /**
     * This sample code shows how to use the API name.
     * It uses some of the SDK APIs with the API name.
     * For a list of API names for attributes and classes,
     * refer to Agile Java Client.
     * Some API names in Agile Java Client may differ from the ones
     * in this example. This is because a duplicate conflict
     * was detected in the API name in the same context.
     * If you detect this conflict, be sure to change the API name
     * in this sample before compiling and executing the code.
    */

    public class APIName
    {

public static final String USERNAME = "admin";

public static final String PASSWORD = "agile";

public static final String URL = "http://localhost:<>/Agile";

public static IAgileSession session = null;

public static IAdmin admin = null;

public static AgileSessionFactory factory = null;

public static IListLibrary listLibrary = null;

/**

* @param args

*/

public static void main(String[] args) {

try {

// Create an IAgileSession instance

session = connect(session);

admin = session.getAdminInstance();

listLibrary = admin.getListLibrary();

// Create two parts

IItem itemParent = createItem(getAutonumber());

IItem itemChild = createItem(getAutonumber());

// enable Page Two tab for Part

enableP2();

// enable Page Two Text 01 and set value

setP2Text(itemParent);

// create a new AdminList

createAdminList();

// enable Page Two List 20 and set value

setP2List(itemParent);

// Add the child part to the BOM table of the parent part

ITable bomTable = addBOM(itemParent, itemChild);

}

    catch (Exception e) {

}

finally {

session.close();

}

}

/**

* @throws APIException

*/

private static void createAdminList() throws APIException {

Map listParams = new HashMap();

listParams.put(IAdminList.ATT_APINAME, "MY_LIST"); // Specify the API name of the List

listParams.put(IAdminList.ATT_NAME, "My List");

listParams.put(IAdminList.ATT_ENABLED, new Boolean(true));

IAdminList myList = listLibrary.createAdminList(listParams);

IAgileList values = myList.getValues();

values.addChild("Value A", "VAL_A"); // Specify the API name along with the value

values.addChild("Value B", "VAL_B");

values.addChild("Value C", "VAL_C");

myList.setValues(values);

System.out.println("Created Admin List " + myList.getName());

}

/**

* @throws APIException

*/

private static void enableP2() throws APIException {

INode p2 = admin.getNode("Part.PageTwo"); // Fully qualified API name

IProperty visible = p2.getProperty(PropertyConstants.PROP_VISIBLE);

IAgileList values = visible.getAvailableValues();

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

visible.setValue(values);

System.out.println("Page two enabled for Part class");

}

/**

* @param itemParent

* @throws APIException

*/

private static void setP2Text(IItem itemParent) throws APIException {

IAgileClass clazz = itemParent.getAgileClass();

ITableDesc p2TableDesc = clazz.getTableDescriptor("PageTwo"); // 'PageTwo' is the API name of the Page Two tab

IAttribute text01 = p2TableDesc.getAttribute("text01"); // 'text01' is the API name of the Text01 field

IProperty visible = text01.getProperty(PropertyConstants.PROP_VISIBLE);

IAgileList values = visible.getAvailableValues();

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

visible.setValue(values);

itemParent.setValue("PageTwo.text01", "SDK test"); // 'PageTwo.text01' is the fully qualified APIName for ItemConstants.ATT_PAGE_TWO_TEXT01

System.out.println("Set P2 Text01 " + itemParent.getValue("PageTwo.text01") + " for Part " + itemParent.getName());

}

/**

* @param itemParent

* @throws APIException

*/

private static void setP2List(IItem itemParent) throws APIException {

IAgileClass clazz = itemParent.getAgileClass();

ITableDesc p2TableDesc = clazz.getTableDescriptor("PageTwo"); // 'PageTwo' is the API name of the Page Two tab

IAttribute text01 = p2TableDesc.getAttribute("list20"); // 'list20' is the API name of the List20 field

IProperty visible = text01.getProperty(PropertyConstants.PROP_VISIBLE);

IAgileList values = visible.getAvailableValues();

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

visible.setValue(values);

IAdminList myList = listLibrary.getAdminList("MY_LIST"); // MY_LIST is the API name of the List 'My List'

IAgileList listValues = myList.getValues();

listValues.setSelection(new Object[] { "VAL_B" } ); // VAL_B is the API name of the list value 'Value B'

itemParent.setValue("PageTwo.list20", listValues); // 'PageTwo.list20' is the fully qualified APIName for ItemConstants.ATT_PAGE_TWO_TEXT01

System.out.println("Set P2 List20 " + listValues.getSelection()[0].getValue() + " for Part " + itemParent.getName());

}

/**

* <p> Create an IAgileSession instance </p>

* @param session

* @return IAgileSession

* @throws APIException

*/

private static IAgileSession connect(IAgileSession session)

throws APIException {

factory = AgileSessionFactory.getInstance(URL);

HashMap params = new HashMap();

params.put(AgileSessionFactory.USERNAME, USERNAME); params.put(AgileSessionFactory.PASSWORD, PASSWORD);

session = factory.createSession(params);

return session;

}

/**

* <p> Create a part </p>

* @param parent

* @return IItem

* @throws APIException

*/

private static IItem createItem(String number) throws APIException {

HashMap map = new HashMap();

map.put("TitleBlock.number", number); // 'number' or 'TitleBlock.number' is the APIName for ItemConstants.ATT_TITLE_BLOCK_NUMBER

map.put("description", "test"); // 'description' or 'TitleBlock.description' is the APIName for ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION

String p = "P" + System.currentTimeMillis();

IItem item = (IItem)session.createObject("Part",map); // 'Part' is the API name of the Part class

System.out.println("Created Part " + number);

return item;

}

/**

* <p> Add the child parts to the BOM table of the parent part </p>

* @param itemParent

* @param itemChild1

* @param itemChild2

* @return ITable

* @throws APIException

*/

private static ITable addBOM(IItem itemParent, IItem itemChild) throws APIException {

ITable table = itemParent.getTable("BOM");

// 'BOM' is APIName for ItemConstants.TABLE_BOM

IRow row1 = table.createRow();

String number = (String)itemChild.getValue("TitleBlock.number");

row1.setValue("itemNumber", number);

// 'itemNumber' is APIName for 'Item Number' on BOM Table

System.out.println("Added Part " + itemChild.getName() + " to BOM of the Part " + itemParent.getName());

return table;

}

/**

* @return

* @throws APIException

*/

private static String getAutonumber() throws APIException{

IAgileClass cls = admin.getAgileClass("Part");

// 'Part' is the API name of the Part class

IAutoNumber auto[] = cls.getAutoNumberSources();

String number = null;

if(auto != null && auto.length > 0)

number = auto[0].getNextNumber();

else

number = "PART" + System.currentTimeMillis();

return number;

}

    }