Enabling Instance-Based Permissions on an Agent

By using instance-based permissions, users can now enforce permissions on a particular instance of an entity type.

When you assign instance-based permission to a given agent, you can control whether or not the permission is applicable to the user, group, or role on one or more instances of an entity type. In addition to that, you can also control whether the permission must be assigned to one or multiple instances of an entity type. .

Prerequisites

The feature is available only on those agents that use the annotation style of development. TOP_LEVEL_TEA_OBJECT does not have instances. Therefore, it will not support instance-based permissions.
The following points are the prerequisites to enable instance-based permissions:
  • The separator character used in ObjectKey has to be unique and consistent across the agent.
  • An ObjectType can have only one parent ObjectType.
  • Cyclic parent-child relationship among the ObjectType instances is not supported.
  • In a given ObjectKey for an ObjectType, the ObjectKey of the parent must have a prefix of the current ObjectKey.
  • A response from TeaOperation can be filtered only if it is an instance of AgentObjectIdentifier (AOI). Plain Java objects (POJO) cannot be filtered by the TIBCO Enterprise Administrator server.
  • An ObjectKey cannot contain a separator character unless it is separating the key of the current object from that of its parent.
  • ObjectKey should not contain the * (star) character. Also make sure that the agent separator is not a *( star) character.

To enable instance-based permissions, the TIBCO Enterprise Adminstrator server must recognize the hierarch of entity types. Perform the following steps to ensure that the TIBCO Enterprise Adminstrator server recognizes the hierarchy of entity types.

Procedure

  1. Define a separator character on the TeaAgentServer object using the setSeparator() method. A separator character is of type char and is used by the agent in the instance keys to separate the current instance from the parent instance key. For example: 
    final TeaAgentServer server = new TeaAgentServer("tomcat", "7.0.42",
tomcatAgentConfig.getAgentInfo(), tomcatAgentConfig.getPort(),
 "/tomcatagent", true);
.
.
server.setSeparator("/");
  2. On every ObjectType that has a parent ObjectType, add a new attribute in @TeaObjectType annotation "parentObjectType" as shown in the following example: 
    @TeaObjectType(name = TomcatAgentUtil.WEBAPP, 
concept = TeaConcept.APPLICATION, description = "Tomcat Webapp",
 parentObjectType = TomcatAgentUtil.SERVER)
public class TomcatWebApp{
    .
    .
}
  3. To filter the response from TeaOperation by instance-based permissions, ensure that TeaOperation sends back AgentObjectIdentifier or an AgentObjectIdentifier[]. For example: 
    @TeaOperation(name = "getWebAppsAsAOI", 
description = "Returns array of web apps in this tomcat server
 instance", methodType = MethodType.READ)
    public AgentObjectIdentifier[] 
    getWebAppsAsAOI(@KeyParam final String key) {
    .  
    .  
    .
}
  4. Optional: As an agent developer, you can hide instances on the permission assignment page of the TIBCO Enterprise Administrator UI by adding the showInstancesInUI attribute to the TeaObjectType annotation and setting its value to false. For example: 
    @TeaObjectType(name = TomcatAgentUtil.WEBAPP, 
 concept = TeaConcept.APPLICATION, description = "Tomcat Webapp",
 parentObjectType = TomcatAgentUtil.SERVER, 
 showInstancesInUI = false)
public class TomcatWebApp implements WithNotifications {
.
.
}