| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.4 E52162-05 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.4 E52162-05 |
|
Previous |
Next |
This chapter includes the following:
About APIName Field
Assigning Names to APIName Fields
APIName Validation Rules
Accessing Metadata Using the 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.
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 APIName 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. |
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".
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 is 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)
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.
| 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") |
| Interface | Method |
| IAdminList | getAPIName() |
| IAgileClass | getAPIName() |
| IAgileList | getAPIName()
addChild(Object child, String apiName) |
| IAttribute | getAPIName() |
| ICell | getAPIName() |
| INode | getAPIName() |
| IProperty | getAPIName() |
| ITableDesc | getAPIName() |
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 |
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.
/**
* 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 the value. setP2List(itemParent);
// Add the child part to the BOM table of the parent part addBOM(itemParent, itemChild); } catch (Exception e) { e.printStackTrace(); } 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 partsClass = itemParent.getAgileClass();//'PageTwo' is the API name of the Page Two tabITableDesc p2TableDesc = partsClass.getTableDescriptor("PageTwo");//'list20' is the API name of the List20 fieldIAttribute list20 = p2TableDesc.getAttribute("list20");//Enable list20 attributeIProperty visible = list20.getProperty(PropertyConstants.PROP_VISIBLE);IAgileList values = visible.getAvailableValues();values.setSelection(new Object[]{ "Yes" });visible.setValue(values);//Assign My List to list20 attributeIAdminList myList = listLibrary.getAdminList("MY_LIST");IProperty assignMyList = list20.getProperty(PropertyConstants.PROP_LIST);IAgileList availableLists = assignMyList.getAvailableValues();availableLists.setSelection(new Object[]{myList});assignMyList.setValue(availableLists);//Select one of the list20 values for the parent itemIAgileList listValues = myList.getValues();//VAL_B is the API name of the list value 'Value B'listValues.setSelection(new Object[] {"VAL_B"} );itemParent.setValue("PageTwo.list20", listValues);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 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 IItem item = (IItem)session.createObject("Part",map);// 'Part' is the API name of the Part class System.out.println("Created Part " + number);return item;}
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 IItem item = (IItem)session.createObject("Part",map);
// 'Part' is the API name of the Part class System.out.println("Created Part " + number); return item;}
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 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 {
// 'BOM' is APIName for ItemConstants.TABLE_BOM ITable table = itemParent.getTable("BOM");
// Add child item to BOM of parent item table.createRow(itemChild); 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; }}
