| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-02 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-02 |
|
Previous |
Next |
This chapter includes the following:
About PLM Administration Tasks
Privileges Required to Administer Agile PLM
Administrative Interfaces
Getting an IAdmin InstanceWorking with Nodes
Managing Agile PLM Classes
Working with Attributes
Working with Properties of Administrative Nodes
Managing UsersManaging User Group
The Agile API provides read/write access to all nodes of Agile PLM's administrative functionality. This means you can create Agile API programs that let users read and modify Agile PLM subclasses, and add, modify, or delete Agile PLM users. The Agile API does not allow you to create new nodes in the administrative tree structure. Therefore, you can't create workflows, criteria, and roles. However, you can create users and user groups because those objects have been implemented as data objects; IUser and IUserGroup both extend IDataObject.
Agile Java Client provides administrative functionality that enables users with Administrative privileges to manage the Agile Application Server. It enables these users to quickly and easily configure the Agile PLM system to support the way they use the system. They can customize the Agile PLM system in several ways:
Modify Agile PLM database propertiesDefine object classes and subclassesSet preferencesCreate and configure user accountsDefine user groups
Define roles and privilegesDefine SmartRules, which set how you manage your change control process
Before you can administer the Agile Application Server, you must have proper privileges. For access to administrative functionality, you should have the Administrator privilege. The Administrator role grants the Administrator privilege to all administrative functionality available on the server. The User Administrator role grants the Administrator privilege for functionality related to users and user groups.
Without the Administrator privilege, you cannot modify administrative nodes, users, and user groups. If you have not yet been granted Administrator rights to the Agile PLM system, contact the Agile PLM administrator.
To create users and user groups, you need the Create privilege for those objects. Several roles supplied with the Agile PLM system, such as the Administrator, User Administrator, and Change Analyst roles, include the Create privilege for users and user groups.
The following table lists interfaces related to Agile PLM's administrative functionality.
| Interface | Description |
|---|---|
| IAdmin | Interface that lets you get Agile PLM classes, nodes, users, or user groups |
| IAgileClass | Class definition used to identify the category to which an object belongs |
| IAgileList | A general-purpose list interface for all SingleList or MultiList attributes and properties |
| IAttribute | Provides detailed information about a particular data member in an object |
| IAutoNumber | An AutoNumber source, which is a predefined, consecutive number series used to automatically number Agile PLM objects |
| ICriteria | A reusable set of search criteria used primarily for queries and Workflows |
| INode | A node in the administrative hierarchy. Each node is equivalent to an Admin node in the Agile Java Client |
| IProperty | A property of an Agile PLM administrative node |
| IRoutableDesc | Metadata that describes any object that implements the IRoutable interface, you can use IRoutableDesc to get the workflows for a class without instantiating an object of that class |
| ITableDesc | Metadata that describes an Agile PLM table, you can use ITableDesc to get table attributes without loading a table |
| ITreeNode | A generic node in a hierarchical tree structure. Several administrative interfaces, such as INode and IFolder, are subinterfaces of ITreeNode and therefore inherit its functionality
Note: There is also a deprecated ITree interface which provides similar functionality to ITreeNode. Be sure to use ITreeNode instead. |
| IUser | An Agile PLM user |
| IUserGroup | A user group. Use user groups to define project teams, site-related groups, departments, or global groups |
| IWorkflow | A Workflow node |
The IAdmin interface provides access to most administrative functionality for the Agile Application Server. To use the ITreeNode interface, you first get an instance of ITreeNode from the current session. The following example shows how to log in to the Agile Application Server and get an ITreeNode instance.
Example 21-1 Getting an instance of IAdmin
public IAgileSession m_session;public IAdmin m_admin;public AgileSessionFactory m_factory;
try { HashMap params = new HashMap(); params.put(AgileSessionFactory.USERNAME, "jdassin"); params.put(AgileSessionFactory.PASSWORD, "agile"); m_factory = AgileSessionFactory.getInstance("http://agileserver/virtualPath"); m_session = m_factory.createSession(params); m_admin = m_session.getAdminInstance();} catch (APIException ex) { System.out.println(ex);
}
Once you have an instance of IAdmin, you can:
Traverse the server nodes
Traverse the folder hierarchy
Get Agile PLM classes and subclasses
The INode object represents a single node or object within Agile PLM's administrative tree. Similar to the Windows Explorer interface, each INode can be expanded to show child nodes. This simple hierarchy lets you navigate the administrative tree structure on the Agile Application Server. Examples of nodes are the root node (also called the Database node), Classes, Preferences, Roles, Privileges, and Smart Rules.
This table shows the mapping of Agile Java Client nodes to Agile API administrative functionality.
| Agile Java Client node | Agile API equivalent |
|---|---|
| Data Settings | |
| Classes | NodeConstants.NODE_AGILE_CLASSES |
| Character Sets | NodeConstants.NODE_CHARACTER_SETS |
| Lists | Not supported |
| Process Extensions | Not supported |
| AutoNumbers | NodeConstants.NODE_AUTONUMBERS |
| Criteria | NodeConstants.NODE_CRITERIA_LIBRARY |
| Workflow Settings | |
| Workflows | NodeConstants.NODE_AGILE_WORKFLOWS |
| User Settings | |
| Account Policy | Not supported |
| Users | Create a query of users |
| User Groups | Create a query of user groups |
| Supplier Groups | Not supported |
| Roles | NodeConstants.NODE_ROLES |
| Privileges | NodeConstants.NODE_PRIVILEGES |
| User Monitor | Not supported |
| Deleted Users | Not supported |
| Deleted User Groups | Not supported |
| System Settings | |
| SmartRules | NodeConstants.NODE_SMARTRULES |
| Viewer & Files | NodeConstants.NODE_VIEWER_AND_FILES |
| Notifications | NodeConstants.NODE_NOTIFICATION_TEMPLATES |
| Full Text Search | Not supported |
| UOM | Not supported |
| Company Profile | Not supported |
| Currency Exchange Rates | IAdmin.getConversionRates() |
| Commodities | Not supported |
| Product Cost Management | |
| Ship To Locations | Not supported |
| Project Portfolio Management | |
| Projects Health | Not supported |
| Cost Status | Not supported |
| Quality Status | Not supported |
| Resource Status | Not supported |
| Dashboard Management | Not supported |
| Default Role | Not supported |
| Agile Content Service | |
| Subscribers | NodeConstants.NODE_SUBSCRIBERS |
| Destinations | NodeConstants.NODE_DESTINATIONS |
| Events | NodeConstants.NODE_EVENTS |
| Filters | NodeConstants.NODE_FILTERS |
| Package Services | Not supported |
| Response Services | Not supported |
| Product Governance & Compliance | |
| Sign Off Message | Not supported |
| Server Settings | |
| Locations | NodeConstants.NODE_SERVER_LOCATION |
| Database | NodeConstants.ROOT |
| Preferences | NodeConstants.NODE_PREFERENCES |
| Licenses | NodeConstants.NODE_SERVER_LICENSES NodeConstants.NODE_USER_LICENSES |
| Task Monitor | Not supported |
| Task Configuration | Not supported |
| Example | |
| Example Roles | Not supported |
| Example Privileges | Not supported |
| Example Criteria | Not supported |
Agile Web Client allows you to view and edit system and user settings by choosing Admin and Settings from the menu, respectively. The following table identifies how Agile Web Client administrative functionality maps to the Agile API.
| Agile Web Client Node | Agile API equivalent |
|---|---|
| Tools > My Settings | |
| User Profile | User.General Info page |
| Change Password | IUser.changeLoginPassword() and IUser.changeApprovalPassword() |
| Transfer Authority | Not supported |
| Organize Bookmarks | My Inbox folder |
| Organize Searches | Searches folder |
| Organize Reports | Not supported |
| Personal Groups | My Inbox folder |
| Deleted Personal Groups | Not supported |
| Personal Criteria | Not supported |
| Personal Supplier Groups | Not supported |
| Tools > Administration > Web Client Settings | |
| Themes | Not supported |
| Tools > Administrator > User Settings | |
| Users | Create a query of users |
| User Groups | Create a query of user groups |
| Supplier Groups | Not supported |
| Deleted Users | Not supported |
| Deleted User Groups | Not supported |
| Dashboard Configuration | Not supported |
Admin nodes in Agile PLM Clients do not have names that match up identically to their respective NodeConstants. For example, the Notifications node in Agile Java Client is equivalent to NodeConstants.NODE_NOTIFICATION_TEMPLATES. Similarly, the hierarchy of nodes that are represented in the Agile PLM database does not exactly match Agile Java Client node hierarchy.
If your Agile API program provides a tree view of the Agile PLM administrative nodes, you can use the view to interactively retrieve INode objects. From each INode object you can get the child nodes. If you continue to traverse the administrative node hierarchy, you can reach all node levels.
The following example shows how to retrieve the root node and its children, thus displaying the top-level nodes on the Agile Application Server.
Example 21-2 Retrieving top-level nodes
private void getTopLevelNodes() throws APIException { INode root = m_admin.getNode(NodeConstants.ROOT); if (null != root) { System.out.println(root.getName() + ", " + root.getId()); Collection childNodes = root.getChildNodes(); for (Iterator it = childNodes.iterator();it.hasNext();) { INode node = (INode)it.next(); System.out.println(node.getName() + ", " + node.getId()); }
}
}
|
Note: When you call getChildNodes() on the root node, the results include several undocumented Agile PLM nodes. Any undocumented nodes are not supported by the Agile API. |
For faster access, you can also retrieve a node by specifying its node ID constant. The NodeConstants class lists all administrative nodes that are directly accessible. The following example shows how to retrieve the SmartRules node and its properties.
//Get the SmartRules node in Agile Administrator INode node = m_admin.getNode(NodeConstants.NODE_SMARTRULES);System.out.println("SmartRules Properties");
//Get SmartRules properties IProperty[] props = (IProperty[])node.getProperties(); for (int i = 0; i < props.length; i++) { System.out.println("Name : " + props[i].getName()); Object value = props[i].getValue(); System.out.println("Value : " + value); }}
Another way to get a node is to locate a parent node and then get one of its children using the ITreeNode.getChildNode() method. The getChildNode() method supports specifying a node by name or ID. You can also specify the path to a subnode, separating each node level with a slash character (/). The following example shows how to use the getChildNode() method to retrieve a node.
private INode getChildNode(INode node, String childName)
throws APIException {
Node child = (INode)(node.getChildNode(childName)); return child;
}
The Classes node and its subnodes are similar to the IAgileClass objects that are returned by the IAdmin.getAgileClasses() method. The difference is that getAgileClasses() returns several virtual classes, such as Item and Change, that are not represented as nodes. To modify the properties of the attribute of a particular node, Agile recommends using the IAdmin.getAgileClasses() or IAdmin.getAgileClass() methods. Although it's possible to modify a subclass by traversing the Classes node and its subnodes, it is much easier to work with getAgileClasses() objects. For more information, see "Managing Agile PLM Classes."
The Agile Classes node provides a framework for classifying Agile PLM objects, such as parts, changes, and packages. Using Agile Java Client, you can define new subclasses for your organization. Although you can't use the Agile API to create new subclasses, you can read or modify any of the existing subclasses. For example, you can customize a subclass by defining the attributes that are visible in each table or on each page.
The Agile PLM classes framework is based on the types of objects that are created in Agile PLM. The objects that are available on your Agile PLM system depend on the Agile PLM agreement with Oracle.
Each Agile PLM class has at least one subclass. The following table lists Agile PLM base classes, classes, and Agile-supplied subclasses. Your Agile PLM system may include other user-defined subclasses.
| Base Class | Classes | Predefined Subclasses |
|---|---|---|
| Changes | Change Orders | ECO |
| Change Requests | ECR | |
| Deviations | Deviation | |
| Manufacturer Orders | MCO | |
| Price Change Orders | PCO | |
| Site Change Orders | SCO | |
| Stop Ships | Stop Ship | |
| Customers | Customers | Customer |
| Declarations | Homogeneous Material Declarations | Homogeneous Material Declaration |
| IPC 1752-1 Declarations | IPC 1752-1 Declaration | |
| IPC 1752-2 Declarations | IPC 1752-2 Declaration | |
| JGPSSI Declarations | Japan Green Procurement Survey Standardization Initiative Declaration | |
| Part Declarations | Part Declaration | |
| Substance Declarations | Substance Declaration | |
| Supplier Declarations of Conformance | Supplier Declaration of Conformance | |
| Discussions | Discussions | Discussion |
| File Folders | File Folders | File Folder |
| Historical Report File Folders | Schedule Generated | |
| User Saved | ||
| Items | Documents | Document |
| Parts | Part | |
| Manufacturer Parts | Manufacturer Parts | Manufacturer Part |
| Manufacturers | Manufacturers | Manufacturer |
| Packages | Packages | Package |
| Prices | Published Prices | Contract |
| Published Price | ||
| Quote Histories | Quote History | |
| Product Service Requests | Non-Conformance Reports | NCR |
| Problem Reports | Problem Report | |
| Projects | Activities | Phase |
| Program | ||
| Task | ||
| Gates | Gate | |
| Quality Change Requests | Audits | Audit |
| Corrective and Preventive Actions | CAPA | |
| Reports1 | Custom Reports | Custom Report |
| External Reports | External Report | |
| Standard Reports | Administrator Report | |
| Standard Report | ||
| Requests for Quote | Requests for Quote | RFQ |
| RFQ Responses | RFQ Responses | RFQ Response |
| Sites | Sites | Site |
| Sourcing Projects | Sourcing Projects | Sourcing Project |
| Specifications | Specifications | Specification |
| Substances | Materials | Material |
| Subparts | Subpart | |
| Substance Groups | Substance Group | |
| Substances | Substance | |
| Suppliers | Suppliers | Broker |
| Component Manufacturer | ||
| Contract Manufacturer | ||
| Distributor | ||
| Manufacturer Representative | ||
| Transfer Orders | Automated Transfer Orders | ATO |
| Content Transfer Orders | CTO | |
| User Groups | User Groups | User Group |
| Users | Users | User |
|
Note: Report objects are not supported by the Agile API. |
Agile PLM super classes, such as Item and Change, are abstract classes that serve as the parent classes for other abstract classes, such as Parts Class, Documentation Class, and Engineering Change Order Class. Abstract superclasses and classes cannot be instantiated.
Concrete classes are user-defined subclasses that can be instantiated by the Agile API. Examples of concrete classes are Part, Document, ECO, and ECR.
When you load an object using the IAgileSession.getObject() method, you can specify either a concrete or an abstract Agile PLM class. For example, all of the following methods load the same specified part.
Example 21-5 Example: Loading an object using abstract or concrete classes
try { IItem item;// Load a part using the Item base class item =(IItem)m_session.getObject
(ItemConstants.CLASS_ITEM_BASE_CLASS, "1000-02");// Load a part using the Parts class item =(IItem)m_session.getObject
(ItemConstants.CLASS_PARTS_CLASS, "1000-02");// Load a part using the Part subclass item =(IItem)m_session.getObject
(ItemConstants.CLASS_PART, "1000-02");} catch (APIException ex) { System.out.println(ex);}
To get an array of classes, use the IAgileClass.getAgileClasses() method. You can specify a range of classes to return. For example, specify IAdmin.CONCRETE for the range parameter to return only concrete classes or IAdmin.ALL to return all classes.
Example 21-6 Getting classes
private void getConcreteClasses() throws APIException { IAgileClass[] classes = m_admin.getAgileClasses(IAdmin.CONCRETE);
for (int i = 0; i < classes.length; i++) { System.out.println("Class Name : " + classes[i].getName()); System.out.println("ID : " + classes[i].getId()); }}void getAllClasses() throws APIException { IAgileClass[] classes = m_admin.getAgileClasses(IAdmin.ALL); for (int i = 0; i < classes.length; i++) { System.out.println("Class Name : " + classes[i].getName()); System.out.println("ID : " + classes[i].getId()); }
}
When you create a new object using the IAgileSession.createObject() method, you must specify a concrete Agile PLM class, that is, one of the user-defined subclasses. Remember, abstract classes cannot be instantiated. The following example shows how to create an object of the Part subclass.
Example: Creating a part
You can reference Agile PLM classes in the following ways:
by object (an IAgileClass)
by class ID constant, such as ItemConstants.CLASS_PART or ChangeConstants.CLASS_ECO. All Agile API constants are contained in classes that have a suffix name Constants. For example, ItemConstants contains all constants related to IItem objects.
by class name, such as "Part" or "ECO".
In general, avoid referencing classes by name for the following reasons:
Class names can be modified.
Class names are not necessarily unique. It's possible to have duplicate class names. Consequently, if you reference a class by name you may inadvertently reference the wrong class.
Class names are localized; that is, the names are different for different languages.
Each class has a specified target type, which is the type of Agile PLM object that the class can create. For example, the target type for the Part subclass is IItem.OBJECT_TYPE. You can use the target type to classify the user-defined subclasses that have been defined in your Agile PLM system. For example, if you want to create a user interface that displays item classes, you can list the classes at run time by selecting those with the target type IItem.OBJECT_TYPE.
Example 21-8 Getting the target type for a class
private void getConcreteItemClasses() throws APIException { IAgileClass[] classes = m_admin.getAgileClasses(IAdmin.CONCRETE); for (int i = 0; i < classes.length; i++) { if (classes[i].getTargetType() == IItem.OBJECT_TYPE) {
System.out.println("Class Name : " + classes[i].getName()); System.out.println("ID : " + classes[i].getId()); } }}
There are two predefined concrete classes for the Item class, Document and Part. If your company hasn't added any Item subclasses to the Agile PLM system, the code in the previous example should print the following results:
Class Name : DocumentID : 9141Class Name : PartID : 10141
Each object that you can retrieve in an Agile API program has a set of attributes. An attribute represents metadata for a particular business object. It defines the properties and values of the object. For example, Title Block.Number, Title Block.Description, and Title Block.Part Category are three of the Title Block attributes for a Part.
When you create an instance of an object in your program, each IAttribute in your object classes is equivalent to a field, or an ICell object. IAttribute objects directly correspond with ICell objects for an object that you created or opened in your program. For more information about ICell objects, see Chapter 6, "Working with Folders."
You can reference Agile PLM attributes in the following ways:
by object (an IAttribute)
by attribute ID constants
All Agile API constants, including attribute ID constants, are contained in classes that have the suffix Constants. For example, ItemConstants contains all constants related to IItem objects.
by fully qualified name, such as Title Block.Number or Cover Page.Change Category.
by short name, such as Number. However, attribute short names are not unique in Agile PLM. If you are referencing multiple attributes, you may run into a conflict if two different attributes have the same short name.
|
Note: Because attribute names can be modified and referencing attributes by ID number or constant is difficult to identify or remember, Agile recommends using the APIName field for this purpose. For information and procedures, see Chapter 8, "Accessing PLM Metadata with APIName Field." Many of the examples in this manual reference attributes by name because they were constructed before the introduction of this field. |
The following example shows how to reference an attribute ID constant.
Example 21-9 Referencing an attribute ID constant
Integer attrID = ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION; try { v = item.getValue(attrID); } catch (APIException ex) { System.out.println(ex); }
A fully qualified attribute name is a string with this format TableName.AttributeName where TableName is the name of the table in which the attribute appears. AttributeName is the current value for the Name property of an attribute. All attributes have default names, but the names can be changed. In particular, Page Two and Page Three attributes that have been made visible in your Agile PLM system are likely to have been assigned more meaningful names than Text01, List01, and Date01.
For example, Cover Page.Reason for Change and Title Block.Number are two examples of fully qualified attribute names.
The following example shows how to reference to a fully qualified attribute name.
Example 21-10 Referencing an attribute name
Object v; String attrName = "Title Block.Description"; try { v = item.getValue(attrName); } catch (APIException ex) { System.out.println(ex); }
|
Note: Attribute names are case-sensitive. |
IAttribute objects are associated with a particular subclass. For example, the attributes for a Part are different from those of an ECO. Therefore, if you know the subclass of an object you can retrieve the list of attributes for it. The following table lists methods that can be used to retrieve attributes.
| Method | Description |
|---|---|
| IAgileClass.getAttribute() | Retrieves the specified IAttribute object for a class |
| IAgileClass.getAttributes() | Retrieves an array of IAttribute objects for all tables of a class |
| IAgileClass.getTableAttributes() | Retrieves an array of IAttribute objects for a specified table of the class |
| ITable.getAttributes() | Retrieves an array of IAttribute objects for a table |
| ICell.getAttribute() | Retrieves the IAttribute object for a cell |
The following example shows how to retrieve BOM table attributes.
Example 21-11 Retrieving BOM table attributes for the Part subclass
try {
// Get the Part subclass IAgileClass partClass = (IAgileClass)m_admin.getAgileClass
(ItemConstants.CLASS_PART);
// Get the collection of BOM table attributes for the Part subclass IAttribute[] attrs = partClass.getTableAttributes(ItemConstants.TABLE_BOM);} catch (APIException ex) { System.out.println(ex);}
Another way to retrieve the attributes for a particular table is to first get the table, then get its attributes using the ITable.getAttributes() method.
Example 21-12 Retrieving the collection of BOM table attributes from the table
try {
// Get Part P200 IItem item = (IItem)m_session.getObject(IItem.OBJECT_TYPE, "P200");
// Get the BOM table ITable bomTable = item.getTable(ItemConstants.TABLE_BOM);
// Get BOM table attributes IAttribute[] attrs = bomTable.getAttributes();
} catch (APIException ex) { System.out.println(ex);}
If you know the attribute you want to retrieve, you can get it by using the IAgileClass.getAttribute() method. The following example shows how to get the Cover Page.Reason Code attribute for an ECO.
Example 21-13 Retrieving the "Cover Page.Reason Code" attribute
try {
// Get the ECO subclass IAgileClass classECO = m_admin.getAgileClass("ECO");
// Get the "Cover Page.Reason Code" attribute IAttribute attr = classECO.getAttribute
(ChangeConstants.ATT_COVER_PAGE_REASON_CODE);
// Get available values for Reason Code IAgileList availValues = attr.getAvailableValues();} catch (APIException ex) {
System.out.println(ex);}
Agile PLM classes have attributes, and attributes have properties. To modify the properties of an attribute for a particular subclass, follow these steps:
Use the IAdmin.getAgileClass() method to get an Agile PLM class.
Use the IAgileClass.getAttribute() method to get an attribute for the class.
Use the IAttribute.getProperty() method to get a property for the attribute.
Use the IProperty.getValue() method to get the current value for the property.
Use the IProperty.setValue() method to set a new value for the property.
For each Agile PLM subclass, you can define additional attributes on the Page Two and Page Three tables. These user-defined attributes, also known as customer flex fields, behave the same as predefined Agile PLM attributes. You can retrieve them and edit their properties.
User-defined attributes are custom extensions to the Agile PLM system. Consequently, their IDs are not included in the CommonConstants class. However, you can view the base ID for any attribute, including user-defined attributes, in Agile Java Client. You can also write a procedure to programmatically retrieve the ID for a user-defined attribute at run time, or use the API name.
If you use the Agile API to retrieve an INode object, you can also view INode's property values. An IProperty object represents a single property for an administrative node. To return an array of all properties for a node, use the INode.getProperties() method.
The following example shows how to get the property value for the Reminder/Escalation Weekend Setting preference. The last part of this example converts the available list values for this SingleList property to a comma-delimited string.
Example 21-14 Getting Property values
private void getReminderEscalationWeekendProp() throws APIException {
//Get the General Preferences node INode node = m_admin.getNode(NodeConstants.NODE_PREFERENCES);
//Get the Reminder/Escalation Weekend Setting propertyIProperty prop = node.getProperty
(PropertyConstants.PROP_REMINDER_ESCALATION_WEEKEND_SETTING);
//Get the Reminder/Escalation Weekend Setting property value Object value = prop.getValue(); System.out.println("Reminder/Escalation Weekend Setting : " + value); IAgileList avail = prop.getAvailableValues();
if (avail != null) { String strAvail = listToString(avail); System.out.println("Available Values : " + strAvail); }} private String listToString(IAgileList list) throws APIException { String strList = ""; Collection children = list.getChildNodes(); for (Iterator it = children.iterator();it.hasNext();) { IAgileList childList = (IAgileList)it.next(); strList = strList + childList.getValue(); if (it.hasNext()) { strList = strList + ", "; } } return strList; }
The SingleList and MultiList properties are different from other types of properties. You cannot use the IProperty.getValue() and IProperty.setValue() methods to directly modify a property that contains a list of values. Instead, you use the IAgileList.setSelection () method to select a list node, and then use the IProperty.setValue() method to set the value. For more information about how to modify SingleList and MultiList properties, see "Getting and Setting List Values."
Users are data objects that you can create, like items and changes. Consequently, you can work with users directly without traversing the administrative node hierarchy. If you have the proper Agile PLM privileges, you can create, modify, and delete users. For example, you could create a program that periodically synchronizes Agile PLM users with data available from a corporate directory.
To retrieve all Agile PLM users, run a query for User objects. The following example retrieves all users and prints the user ID, first name, and last name for each user.
Example 21-15 Getting all users
private void getAllUsers() throws APIException { IQuery q = (IQuery)m_session.createObject
(IQuery.OBJECT_TYPE, "select * from [Users]"); ArrayList users = new ArrayList(); Iterator itr = q.execute().getReferentIterator(); while (itr.hasNext()) {
users.add(itr.next()); } for (int i = 0; i < users.size(); i++) { IUser user =(IUser)users.get(i); System.out.println( user.getValue(UserConstants.ATT_GENERAL_INFO_USER_ID) + ", " + user.getValue(UserConstants.ATT_GENERAL_INFO_FIRST_NAME) + ", " + user.getValue(UserConstants.ATT_GENERAL_INFO_LAST_NAME)); }}
A user is like other data objects that you can create with the Agile API. To create a user, you define the user's parameters and pass them to the IAgileSession.createObject() method. The required parameters you must specify are user ID and login password. You can also specify other user attributes, which are listed in the UserConstants class.
|
Note: If an LDAP directory server is used to authenticate users for your Agile PLM system, you can create only supplier users through the SDK that have restricted access to the Agile PLM system. You must create and maintain other users on the directory server. |
The passwords you specify for a new user are default values. If you specify an approval password, it must be different from the login password, unless the UserConstants.ATT_GENERAL_INFO_USE_LOGIN_PASSWORD_FOR_APPROVAL cell is set to Yes. The user can always change the password later.
Example 21-16 Creating a user
private void userTest() { try {
//Add code here to log in to the Agile Application Server//After logging in, create a new user by invoking the createUser method below IUser user = createUser("akurosawa"); } catch (APIException ex) { System.out.println(ex); }}
//Create the new user
private IUser createUser(String newUser) throws APIException { Map params = new HashMap(); params.put(UserConstants.ATT_GENERAL_INFO_USER_ID, newUser); params.put(UserConstants.ATT_LOGIN_PASSWORD, "agile"); IUser user =(IUser)session.createObject(UserConstants.CLASS_USER, params); return user; }
By default, when you create a new user it's assigned the Concurrent user category and the My User Profile role, a combination that allows the user to only view their own profile. To create and modify objects, the user must be assigned roles with the appropriate create and modify privileges. For an example showing how to change a user's Role settings, see "Configuring User Settings."
A user group, like a user, is a dataobject and not an administrative node on the Agile Application Server. To create a user group, you define the user group's parameters, such as its name, and pass the parameters to the IAgileSession.createObject() method. The only required parameter you must specify is the name, whose attribute ID is UserGroupConstants.ATT_GENERAL_INFO_NAME. You can also specify other user attributes, which are listed in the UserGroupConstants class. To enable a user group, make sure the Enabled cell is set to Yes.
After creating a user group, you need to add users to the Users table to make the group meaningful. To create a new row in the Users table, use the ITable.createRow(java.lang.Object) method.
Example: Creating a user group
Example 21-17 Creating a user group
private void userGroupTest() throws APIException { //Add code here to log in to the Agile Application Server //After logging in, create a new user group IUserGroup group = createGroup("Swallowtail Project");
//Add users to the Western project group IUser[] selUsers = new IUser[] { m_session.getObject(IUser.OBJECT_TYPE, "jford"), m_session.getObject(IUser.OBJECT_TYPE, "hhawkes"), m_session.getObject(IUser.OBJECT_TYPE, "speckinpah") }; addUsers(group, selUsers);}
private IUserGroup createGroup(String groupName) throws APIException {//Create the user group IUserGroup group =(IUserGroup)m_session.createObject
(UserGroupConstants.CLASS_USER_GROUP, groupName);
//Enable the user group ICell cell = group.getCell(UserGroupConstants.ATT_GENERAL_INFO_STATUS); IAgileList list = cell.getAvailableValues(); list.setSelection(new Object[] { "Active" }); cell.setValue(list); return group;}
private void addUsers(IUserGroup group, IUser[] seUsers) throws APIException { ITable usersTable = group.getTable(UserGroupConstants.TABLE_USERS); for (int i = 0; i < users.length; i++) { IRow row = usersTable.createRow(users[i]); }}
User groups can be global or personal. Global user groups are accessible to all Agile PLM users. Personal user groups are accessible only to the person who created the group. The following example shows how to make a user group global.
Example 21-18 Creating a Global User Group
private void setGlobal(IUserGroup group) throws APIException {//Get the Global/Personal cell ICell cell = group.getCell(UserGroupConstants.
ATT_GENERAL_INFO_GLOBAL_PERSONAL);
//Get the available values for the cell IAgileList values = cell.getAvailableValues();
//Set the selected value to "Global" values.setSelection(new Object[] { "Global" });
//Change the cell value group.setValue(UserGroupConstants.
ATT_GENERAL_INFO_GLOBAL_PERSONAL, values);}
When creating a user, you can require the new user to change the assigned password, which is usually temporary, for a new and more secure one at login. To create such a user, it is necessary to define the user's parameters as explained in "Creating a User." and pass a flag to force password change at login. This is illustrated in the following code sample.
Example: Creating a user and requiring password modification at login
String username = "USER" + System.currentTimeMillis();
HashMap params = new HashMap();
params.put(UserConstants.ATT_GENERAL_INFO_USER_ID, username);
params.put(UserConstants.ATT_GENERAL_INFO_FIRST_NAME, username);
params.put(UserConstants.ATT_GENERAL_INFO_LAST_NAME, username);
params.put(UserConstants.ATT_LOGIN_PASSWORD, "agile");
params.put(UserConstants.ATT_APPROVAL_PASSWORD, "agile2");
params.put(UserConstants.ATT_MUST_CHANGE_PWD_AT_LOGON, "true");
IUser user = (IUser) session.createObject(UserConstants.CLASS_USER, params);
System.out.println("Created user: " + user.getName());
Supplier users are assigned to the Restricted user category by default, which restricts their access to the Agile PLM system. The Restricted user category allows supplier users to respond to RFQs and use other features of Agile Product Cost Management (PCM).
To create a supplier user, define the user's parameters and pass them to the IAgileSession.createObject() method. You must specify the user ID, login password, and supplier name. You can also specify other user attributes, which are listed in the UserConstants class.
Example 21-20 Creating a supplier user
private IUser createSupplierUser(String userName, String supplier)
throws APIException { HashMap userParams = new HashMap(); userParams.put(UserConstants.ATT_GENERAL_INFO_USER_ID, userName); userParams.put(UserConstants.ATT_LOGIN_PASSWORD, "agile"); userParams.put(UserConstants.ATT_SUPPLIER, supplier); return (IUser)m_session.createObject(UserConstants.CLASS_USER, userParams);}
You can use the IDataObject.saveAs() method to save an existing user to a new user. The saveAs()method serves as a handy shortcut because it allows you to assign a new user the same roles, privileges, and sites as an existing user. When you use the saveAs() method to save a user, you must specify parameters for the new user's user name and login password.
Example 21-21 Saving an object as a new object
private void saveAsUser(IUser user, String newUserName) {
try {
//Set parameters for the new user Map params = new HashMap(); params.put(UserConstants.ATT_GENERAL_INFO_USER_ID, newUserName); params.put(UserConstants.ATT_LOGIN_PASSWORD, "agile");
// Save the new user user.saveAs(UserConstants.CLASS_USER, params); } catch (APIException ex) { System.out.println(ex); }}
An IUser object, unlike administrative nodes, is a dataobject. Therefore, an IUser object has data cells, not properties, and you use the ICell interface to configure a user's settings. The following example shows how to get visible cells on the General Info and Page Two tables for a user. To access cells on other user tables, use the IDataObject.getTable() method to load the table.
Example 21-22 Getting user cells for General Info and Page Two
private void getUserCells(IUser user) throws APIException { ICell[] cells = user.getCells(); for (int i = 0; i < cells.length; i++) { System.out.println(cells[i].getName() + " : " + cells[i].getValue());
}
}
Two important settings for a user are User Category and Roles. The User Category setting defines the broad range of actions a user can perform on the Agile PLM system. Select from one of the following User Category values:
Power - User can log in to the server at any time with unrestricted use of the Agile PLM system. Power users are not subject to the limited number of concurrent users.
Concurrent - User can log in to the server only if a concurrent user agreement is available.
|
Note: Licenses are controlled by your agreement with Oracle. |
Restricted - User has restricted access to the Agile PLM system. Supplier users are by default assigned the Restricted category, which allows them to respond to RFQs and use other features of Agile Product Cost Management (PCM). Restricted users are not subject to the limited number of concurrent users.
The Roles setting further defines the capabilities of a user, assigning roles and privileges. A user won't be able to create objects without the proper roles and privileges. For more information about Agile PLM user roles, and privileges, refer to the Agile PLM Administrator Guide.
The following example shows how to set a user's User Category and Roles settings.
Example 21-23 Setting the User Category and Roles settings for a user
private void setCategory(IUser user) throws APIException {
//Get the User Category cell ICell cell = user.getCell(UserConstants.ATT_GENERAL_INFO_USER_CATEGORY);
//Get the available values for the cell IAgileList license = cell.getAvailableValues();
//Set the selected value to "Concurrent" license.setSelection(new Object[] { "Concurrent" });
//Change the cell value cell.setValue(license);}private void setRoles(IUser user) throws APIException {
//Get the Role cell ICell cell = user.getCell(UserConstants.ATT_GENERAL_INFO_ROLES);
//Get the available values for the cell IAgileList roles = cell.getAvailableValues();
//Set the selected roles to Change Analyst and Administrator roles.setSelection (new Object[]
{"Change Analyst","Administrator","My User Profile"});
//Change the cell value cell.setValue(roles);}
Administrators with User Administrator privileges can reset the password of other users to a new value. Users without this privilege are not able to reset user passwords. This feature enables resetting large numbers of passwords in the batch mode, which is preferable to manually changing them one at a time using the UI.
The changeLoginPassword() method which supports this feature allows passing a null value instead of the current password value. The following example shows how to use this method to reset a user's password using null instead of the current password.
To delete a user, use the IDataObject.delete() method. Like other dataobjects, an object deleted for the first time is "soft-deleted," which means it is disabled but not removed from the database. The Agile Application Server does not allow you to permanently delete a user.
Example 21-25 Deleting a user
private void removeUser(IUser user) throws APIException { user.delete(); user = null;}
|
Note: In Agile Java Client, deleted users can be listed by choosing Admin > User Settings > Deleted Users. |
A user group is an object that contains a list of Agile PLM users. You can use user groups to define project teams, departments, and global groups and their assigned users. User groups are not site-related, unlike items and changes, but you can create groups of users based on their location. Whenever you add a user to a user group, that change is reflected in the user's Groups setting, whose attribute ID is UserConstants.ATT_GENERAL_INFO_GROUPS.
|
Note: In Agile Clients such as Agile Web Client, you can send an object, such as a change, to a user group. The Agile API does not support sending objects to user groups. However, you can retrieve users from the Users table of a User Group object and then send them an object. |
To retrieve all Agile PLM user groups, run a query for User Group objects. You can iterate through the user groups to find a particular group. The following example retrieves all user groups and prints the name, description, maximum number of users, and enabled status for each user group.
Example 21-26 Example: Getting all user groups
private void getAllUserGroups() throws APIException { IQuery q = (IQuery)m_session.createObject
(IQuery.OBJECT_TYPE, "select * from [User Groups]"); ArrayList groups = new ArrayList(); Iterator itr = q.execute().getReferentIterator(); while (itr.hasNext()) { groups.add(itr.next()); } for (int i = 0; i < groups.size(); i++) { IUserGroup ug =(IUserGroup)groups.get(i); System.out.println( ug.getValue(UserGroupConstants.ATT_GENERAL_INFO_NAME) + ", " + ug.getValue(UserGroupConstants.ATT_GENERAL_INFO_DESCRIPTION) + ", " + ug.getValue(UserGroupConstants.ATT_GENERAL_INFO_MAX_NUM_OF_NAMED_USERS)+ "," + ug.getValue(UserGroupConstants.ATT_GENERAL_INFO_STATUS)); }}
A user group, like a user, is a dataobject and not an administrative node on the Agile Application Server. To create a user group, you define the user group's parameters, such as its name, and pass the parameters to the IAgileSession.createObject() method. The only required parameter you must specify is the name, whose attribute ID is UserGroupConstants.ATT_GENERAL_INFO_NAME. You can also specify other user attributes, which are listed in the UserGroupConstants class. To enable a user group, make sure the Enabled cell is set to Yes.
After creating a user group, you need to add users to the Users table to make the group meaningful. To create a new row in the Users table, use the ITable.createRow(java.lang.Object) method.
Example 21-27 Creating a user group
private void userGroupTest() throws APIException {
//Add code here to log in to the Agile Application Server
//After logging in, create a new user group
IUserGroup group = createGroup("Swallowtail Project");
//Add users to the Western project group IUser[] selUsers = new IUser[] { m_session.getObject(IUser.OBJECT_TYPE, "jford"), m_session.getObject(IUser.OBJECT_TYPE, "hhawkes"), m_session.getObject(IUser.OBJECT_TYPE, "speckinpah") }; addUsers(group, selUsers);}
private IUserGroup createGroup(String groupName) throws APIException {//Create the user group IUserGroup group =(IUserGroup)m_session.
createObject(UserGroupConstants.CLASS_USER_GROUP, groupName);
//Enable the user group ICell cell = group.getCell(UserGroupConstants.ATT_GENERAL_INFO_STATUS); IAgileList list = cell.getAvailableValues(); list.setSelection(new Object[] { "Active" }); cell.setValue(list); return group;}
private void addUsers(IUserGroup group, IUser[] seUsers) throws APIException { ITable usersTable = group.getTable(UserGroupConstants.TABLE_USERS); for (int i = 0; i < users.length; i++) { IRow row = usersTable.createRow(users[i]); }}
User groups can be global or personal. Global user groups are accessible to all Agile PLM users. Personal user groups are accessible only to the person who created the group. The following example shows how to make a user group global.
Example 21-28 Making a user group global
private void setGlobal(IUserGroup group) throws APIException {
//Get the Global/Personal cell ICell cell = group.getCell
(UserGroupConstants.ATT_GENERAL_INFO_GLOBAL_PERSONAL);
//Get the available values for the cell IAgileList values = cell.getAvailableValues();
//Set the selected value to "Global" values.setSelection(new Object[] { "Global" });
//Change the cell value
group.setValue(UserGroupConstants.ATT_GENERAL_INFO_GLOBAL_PERSONAL, values);}
IUserGroup cannot be passed to createRow() to add a user group to the user's user group table. You must use a Map as shown in the following example.
Example 21-29 Using a Map to add a User Group to a User Group Table
ITable ugTable = user.getTable(UserConstants.TABLE_USERGROUP);
Map map = new HashMap(); map.put(UserConstants.ATT_USER_GROUP_GROUP_NAME, ug.getName()); ugTable.createRow(map);
The users contained within a user group are listed on the Users table. Therefore, to get the list of users in the user group, use the IDataObject.getTable() method and then iterate over the table rows to access data for each user. The following example shows how to list the users in a user group.
Example 21-30 Listing the users in a user group
private void listUsers(IUserGroup group) throws APIException { ITable usersTable = group.getTable(UserGroupConstants.TABLE_USERS); Iterator it = usersTable.iterator(); while (it.hasNext()) { IRow row = (IRow)it.next(); System.out.println(row.getValue
(UserGroupConstants.ATT_USERS_USER_NAME)); }}
|
 Copyright © 2010, 2014, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|