9 Subscribing to Agile PLM Objects

This chapter includes the following:

• About User Subscriptions

• Getting Subscriptions for an Object

• Modifying Subscriptions for an Object

• Making Attributes Available for Subscription

• Working with Subscription Tables

9.1 About User Subscriptions

When you load an Agile PLM business object, such as an item or change, you can then subscribe to that object. Once you subscribe to the object, you will receive a Notification whenever a triggering event occurs for that object. You can specify which events trigger a Notification. Subscription events can be a lifecycle change, a change to attachment files, or a change to the value of any cell that is made available for subscription.

You can subscribe to both routable and nonroutable objects. The Agile API provides an interface called ISubscribable, which enables retrieving and modifying all subscriptions for an object. All objects that a user has subscribed to are listed on the user's Subscription table.

9.1.1 Subscription Events

Subscription events vary per object class. The full set of events you can subscribe to are listed in the following table.

Subscription Event	SubscriptionConstants
Status Change (for routable objects)	EVENT_STATUS_CHANGE
Lifecycle Phase Change (for nonroutable objects)	EVENT_LIFECYCLE_CHANGE
Field Change	EVENT_FIELD_CHANGE
Add File	EVENT_ADD_FILE
Delete File	EVENT_DELETE_FILE
Checkin File	EVENT_CHECKIN_FILE
Checkout File	EVENT_CHECKOUT_FILE
Cancel Checkout File	EVENT_CANCELCHECKOUT_FILE

Note: There are additional subscription events for Projects Execution objects that are not supported by the Agile API.

Although most routable and nonroutable objects support the subscription events listed in the table above, there are some exceptions:

• User objects do not support the Lifecycle Change subscription event.

• File Folder objects do not support the Add File and Cancel Checkout File subscription events.

The Field Change subscription event is related to any attribute whose Available To Subscribe property has been set to "Yes." Consequently, each class and subclass can have a different set of subscribable attributes.

9.1.2 Subscribe Privilege

To subscribe to an object, you must have the Subscribe privilege for that class. Many predefined Agile PLM roles, such as Creator, already have the Subscribe privilege for several object classes. To change your roles and privileges, see your Agile PLM system administrator.

9.1.3 Subscription Notifications

Subscription events trigger two types of Agile PLM Notifications:

• Email - Email Notifications are sent only if the Receive Email Notification preference of the recipient is set to Yes. For information on user and system preferences, refer to Agile PLM Administrator Guide.

• Inbox - Inbox Notifications occur automatically regardless of user preferences

A user with Administrator privileges can create and configure these Notifications in Java Client which provides two very similar dialogs for this purpose. The reason for the two dialogs is due to the fact that there are two sets of Email and Inbox Notifications:

• Those that the "To" field is grayed out

• Those that the administrator user can select recipients who are notified when the subscription event is triggered

9.1.3.1 Sending Notifications with SDK

Notifications are briefly described in the SDK Guide under Event Notifications. SDK exposes the following API to send Notifications to designated notifiers with the specified template for Agile PLM objects. For information about Notifications, refer to Agile PLM Administrator Guide.

sendNotification	(IDataObject	object	Object the Notification is issued for
	String	template	Name of Notification template
	Collection	notifiers	List of notifiers
	boolean	urgent	True for urgent Comments
	String	comments	about the Notification
	)		throws APIException

These parameters are defined as follows:

• object - object on which Notification is to be issued

• template - name of the Notification template

• notifiers - collection containing a list of users as individual IDataObjects such as IUser and IUserGroup

• urgent - value of true indicates send urgently, set to false otherwise

• comments - comments about the Notification

For more information about these parameters and the API, refer to Javadoc generated HTML files that document the SDK code. You can find them in the HTML folder in SDK_samples (ZIP file). To access this file, see the Note in "Client-Side Components."

The following example uses sendNotification to send a Notification from ECO C0001 to user1 and user2 with Notification Comment and template

Example 9-1 Sending a Notification with Agile SDK

IAgileSession session =      AgileSessionFactory.createSessionEx(loginParams);List notifyList = new ArrayList();IDataObject user =      (IDataObject)session.getObject
      (com.agile.api.IUser.OBJECT_TYPE,"John Doe");       notifyList.add(user);   user =   (IDataObject)session.getObject(com.agile.api.IUser.OBJECT_TYPE,"Jane Doe");        notifyList.add(user);IDataObject agileObject =    (IDataObject)session.getObject(com.agile.api.IChange.OBJECT_TYPE,"C0001");    boolean urgent = true;String comment =        "Add ECO approver, Notify CA";String template =        "Automated SDK process added ECO approver";session.sendNotification(agileObject,template,notifyList,urgent,comment);

9.2 Deleting Subscribed Objects

You can delete any Agile PLM business object using the IDataObject.delete() method. However, you can't delete an object until its subscriptions are removed. Users can remove their own subscriptions, but not the subscriptions of other users.

9.3 Getting Subscriptions for an Object

To retrieve the current subscriptions for an object, use ISubscribable.getSubscriptions(), which returns an array of all ISubscription objects, both enabled and disabled. The following example shows how to get subscriptions for an object.

Example 9-2 Getting subscriptions for an object

public void getSubscriptionStatus(IAgileObject obj) throws APIException {
   ISubscription[] subs =      ((ISubscribable)obj).getSubscriptions();   for (int i = 0; i < subs.length; ++i) {   if (subs[i].getId().equals(SubscriptionConstants.EVENT_ADD_FILE)) {      if (subs[i].isEnabled()) {   System.out.println("Add File subscription is enabled");      }   }   else if 
      (subs[i].getId().equals(SubscriptionConstants.EVENT_CANCELCHECKOUT_FILE)) {      if (subs[i].isEnabled()) {   System.out.println("Cancel Checkout File subscription is enabled");      }   }   else if (subs[i].getId().equals(SubscriptionConstants.EVENT_CHECKIN_FILE)) {      if (subs[i].isEnabled()) {   System.out.println("Checkin File subscription is enabled");      }   }   else if (subs[i].getId().equals(SubscriptionConstants.EVENT_CHECKOUT_FILE)) {      if (subs[i].isEnabled()) {System.out.println("Checkout File subscription is enabled");      }}   else if (subs[i].getId().equals(SubscriptionConstants.EVENT_DELETE_FILE)) {      if (subs[i].isEnabled()) {   System.out.println("Delete File subscription is enabled");      }   }   else if (subs[i].getId().equals(SubscriptionConstants.EVENT_FIELD_CHANGE)) {      if (subs[i].isEnabled()) {   IAttribute attr = subs[i].getAttribute();         if (attr != null) {String attrName = attr.getFullName();System.out.println("Field Change subscriptionis enabled for " + attrName);         }      }   }   else if 
      (subs[i].getId().equals(SubscriptionConstants.EVENT_LIFECYCLE_CHANGE)) {   if (subs[i].isEnabled())   System.out.println("Lifecycle Change subscription is enabled");   }   else if (subs[i].getId().equals(SubscriptionConstants.EVENT_STATUS_CHANGE)) {      if (subs[i].isEnabled())      System.out.println("Status Change subscription is enabled");   }   else   System.out.println("Unrecognized subscription event: " + subs[i].getId());   }}

9.4 Modifying Subscriptions for an Object

You can use the Agile API to modify subscriptions for the current user only. If you change your subscriptions for a particular business object, other users' subscriptions for that object remain unaffected.

The list of subscription events for any object is set at the server and cannot be modified by the Agile API. However, you can select the fields (attributes) you want subscribed. If you have Administrator privileges, you can also modify classes to define which fields are available for subscription. For more information, see "Making Attributes Available for Subscription."

To work with a subscription, use the following ISubscription methods:

• enable(boolean) - Enables or disables the subscription

• getAttribute() - Returns the IAttribute object associated with a subscription. Only Field Change subscriptions have associated attributes

• isEnabled() - Returns true if the subscription is enabled, false otherwise

• getId() - Returns the subscription ID, which is equivalent to one of the SubscriptionConstants

ISubscription is a value object interface. Consequently, when you make changes to a subscription (for example, by enabling it), it's not changed in the Agile PLM system until you call ISubscribable.modifySubscriptions().

The following example shows how to enable the Lifecycle Change and Field Change subscription events and subscribe to two Page Two fields. All other subscription events are disabled.

Example 9-3 Enabling and disabling subscriptions for an object

public void setSubscriptions(IAgileObject obj) throws APIException {   ISubscription[] subs = ((ISubscribable)obj).getSubscriptions();      for (int i = 0; i < subs.length; ++i) {

   // Enable the Status Change subscription event   if (subs[i].getId().equals(SubscriptionConstants.EVENT_STATUS_CHANGE)) {      subs[i].enable(true);   }   /* Enable the Field Change subscription event for Page Two.Text01 and P
   * page Two.List01
   */
   else if (subs[i].getId().equals(SubscriptionConstants.EVENT_FIELD_CHANGE)){      if (subs[i].getAttribute() != null)      System.out.println(subs[i].getAttribute().getFullName() + ": " +       subs[i].getAttribute().getId());      if ((subs[i].getAttribute() != null) &&
   ((subs[i].getAttribute().getId().
      equals(CommonConstants.ATT_PAGE_TWO_LIST01)) ||   (subs[i].getAttribute().
      getId().equals(CommonConstants.ATT_PAGE_TWO_TEXT01))) )      subs[i].enable(true);         else            subs[i].enable(false);   }   // Disable all other subscription events      else   subs[i].enable(false);   }      ((ISubscribable)obj).modifySubscriptions(subs);}

9.5 Making Attributes Available for Subscription

The attributes that are subscribable vary per Agile PLM class. In general, most Page One (Title Page, Cover Page, and General Info) attributes are subscribable and can therefore be made available for subscription. All Page Two attributes, except for ATT_PAGE_TWO_CREATE_USER, and all Page Three attributes are also subscribable.

When an attribute's Available To Subscribe property is set to Yes, users can subscribe to the attribute. When you call ISubscribable.getSubscriptions() for an object, the returned ISubscription[] array includes an ISubscription object for each subscription event. Although there is only one Field Change event-whose constant is SubscriptionConstants.EVENT_FIELD_CHANGE, each subscribed attribute is treated as a separate event that can trigger a subscription Notification. Depending on how your Agile PLM system has been configured, there could be dozens of attributes available for subscription for a particular object.

If an attribute isn't visible, it also isn't subscribable even if its Available To Subscribe property has been set to Yes. Therefore, before setting the Available To Subscribe property to Yes, make sure the Visible property is also set to Yes. The following example shows how to make all Page Two attributes for ECOs available for subscription.

Example 9-4 Making Page Two attributes available for subscription

try {
// Get the ECO subclass   IAgileClass classECO = m_admin.getAgileClass("ECO");

// Get Page Two attributes   IAttribute[] attr = classECO.getTableAttributes(ChangeConstants.TABLE_PAGETWO);

Example 9-5 Making visible Page Two attributes subscribable

for (int i = 0; i < attr.length; ++i) {   IProperty prop = null;   IAgileList listValues = null;   String strVal = "";

// Check if the attribute is visible   prop = attr[i].getProperty(PropertyConstants.PROP_VISIBLE);
   listValues = (IAgileList)prop.getValue();   strVal = listValues.toString();

// If the attribute is visible, make it subscribable   if (strVal.equals("Yes")) {      prop =         attr[i].getProperty(PropertyConstants.PROP_AVAILABLE_FOR_SUBSCRIBE);         if (prop != null) {           listValues = prop.getAvailableValues();           listValues.setSelection(new Object[] { "Yes" });           prop.setValue(listValues);         }      }   }} catch (APIException ex) {      System.out.println(ex);} 

9.5.1 Parent and Child Attributes

Several read-only attributes have a child relationship with a parent attribute. Child attributes derive values from their parent attribute. Consequently, parent attributes are available for subscription, but child attributes are not. Examples of child attributes include BOM table attributes like BOM.Item List02 and BOM.Item Text01.

9.6 Working with Subscription Tables

A user's Subscription table lists all subscriptions the user has made. The Subscription table offers limited editing capabilities. For example, you can't add new rows to the table; the only way to add subscriptions using the Agile API is to call ISubscribable.modifySubscriptions() for a dataobject. However, you can remove subscriptions from the table.

The following example shows how to retrieve the Subscription table for the current user. It also shows how to remove a subscription for a part with the number 1000-02.

Example 9-6 Removing a subscription

try {// Get the current user   IUser user = m_session.getCurrentUser();

// Get the Subscription table   ITable tblSubscriptions = user.getTable(UserConstants.TABLE_SUBSCRIPTION);   Iterator i = tblSubscriptions.getReferentIterator();

// Get each object referenced in the table   while (i.hasNext()) {
      IRow row = (IRow)i.next();      String n = (String)row.getValue(UserConstants.ATT_SUBSCRIPTION_NUMBER);      if (n.equals("1000-02")) {         tblSubscriptions.removeRow(row);         break;      }   }
} catch (APIException ex) {      System.out.println(ex);}

In addition to removing individual rows from the Subscription table, you can also use the Collection.clear() method to clear the table.

Example 9-7 Clearing the Subscription table

public void clearSubscriptionTable(IUser user) throws APIException {// Get the Subscription tableITable tblSubscriptions = user.getTable(UserConstants.TABLE_SUBSCRIPTION);// Clear the tabletblSubscriptions.clear();}

The Subscription table doesn't list the events you've subscribed to for each object. To find that information, you need to open each referenced object. The following example shows how to use ITable.getReferentIterator() to iterate through the referenced objects in the table.

Example 9-8 Getting objects referenced in the Subscription table

try {// Get the current user   IUser user = m_session.getCurrentUser();

// Get the Subscription table   ITable tblSubscriptions = user.getTable(UserConstants.TABLE_SUBSCRIPTION);   Iterator i = tblSubscriptions.getReferentIterator();

// Get each object referenced in the table   while (i.hasNext()) {      IAgileObject obj = (IAgileObject)i.next();         if (obj instanceof ISubscribable) {           ISubscription[] subscriptions =           ((ISubscribable)obj).getSubscriptions();      for (int j = 0; j < subscriptions.length; j++) {         ISubscription subscription = subscriptions[j];         System.out.println(subscription.getName());

      // Add code here to handle each subscription         }      System.out.println(obj.getName());      }   }} catch (APIException ex) {      System.out.println(ex);}