4.2 Examples

This section contains the following topics:

The context operations web service provides operations that a domain manager, inspector or context manager would typically perform. This includes creating contexts, altering context labels, and adding or removing context managers.

The document right operations web service provides operations that allow a context manager to manage the rights users have within a context. Document right operations include assigning rights, checking in rights, and listing rights.

A document role can be assigned, within a context, to one or more accounts. This can be performed by users that have the Context Manager role within the context. An account can only have one role assigned within a context.

4.2.1 Creating a Context from a Template

A context is created from a context template. The template defines the structure of the context and what roles are available to assign to users and groups. Only active templates can be used when creating contexts. Changes to the template after the context is created are dynamically picked up in the context. For example, adding a role to the template makes the role available to the context.

4.2.1.1 Calling createContextFromTemplate

When creating a context, the relevant context template must be identified using a ContextTemplateRef type. This type includes the template UUID and owning domain. The domain created on installation has a fixed UUID value of dcfef562-971d-401b-81f9-86700573bf8b. If other domains are used, the domain UUID can be found by using operations such as listDomains.

DomainRef domainReference = new DomainRef();
domainReference.setUuid("dcfef562-971d-401b-81f9-86700573bf8b");

The standard templates installed in the installation domain also have fixed UUID values.

  • 474dbb07-718b-4c4e-8f43-d2b723469573 for the standard context template.

  • 1a05b98d-b415-4c38-9b7a-9d0ad19ee0e9 for the export context template.

If other templates are used, the template UUID can be obtained using the listActiveTemplates operations.

ContextTemplateRef templateRef = new ContextTemplateRef();
templateRef.setUuid("474dbb07-718b-4c4e-8f43-d2b723469573");
templateRef.setDomain(domainReference);

Once the template has been identified, a context can be created. The authenticated user will automatically be made the context manager.

ContextOperations contextOperations = new ContextOperationsService().getContextOperations();
 
Label english = new Label();
english.setLocale("en");
english.setName("Top Secret");
 
Label german = new Label();
german.setLocale("de");
german.setName("Strenges Geheimnis");
 
ContextInstance context = contextOperations.createContextFromTemplate(
    null, // automatically generate a UUID value for the context
    templateRef,
    new Label[] { english, german },
    Visibility.DOMAIN,
    null); // no additional context managers

4.2.2 Searching for Journal Entries

The context journal contains records of actions performed on sealed content of the context classification system. This information is available to administrators in the Reports tab of the Oracle IRM Server Management Console. The context journal can be searched for activity on content for the specified accounts and/or document items. This search is restricted to the contexts available to the caller. That is, the caller must be a context manager or inspector.

4.2.2.1 Calling searchJournal

Searching for journal entries may produce a large result set. For this reason a page range (starting from 1) must be provided.

PageRange pageRange = new PageRange();
pageRange.setFirst(1);
pageRange.setLast(100);

A time range to filter the search is also required. The following example is a time range for the last twenty-four hours.

Date end = new Date();
 
// Use a calendar to work out the time range
Calendar calendar = Calendar.getInstance();
 
calendar.setTime(end);
calendar.add(Calendar.DAY_OF_MONTH, -1);
 
Date begin = calendar.getTime();
 
TimeRange timeRange = new TimeRange().
timeRange.setBegin(begin);
timeRange.setEnd(end);

If no sort order is specified, the results are sorted by time.

ContextOperations contextOperations = new ContextOperationsService().getContextOperations();
 
ContextJournalEntry[] journalResults = contextOperations.searchJournal(
    null, // no accounts filter
    null, // no item codes filter
    timeRange,
    pageRange,
    null); // no sorting details

4.2.3 Assigning a Role

A document role can be assigned to a user or group. Document roles are identified with a UUID and a domain. The domain created on installation has a fixed UUID value of dcfef562-971d-401b-81f9-86700573bf8b. If other domains are used, the domain UUID can be found by using operations such as listDomains.

DomainRef domainReference = new DomainRef();
domainReference.setUuid("dcfef562-971d-401b-81f9-86700573bf8b");

The standard roles installed in the installation domain also have fixed UUID values.

  • a456140d-24dc-4cc2-8f23-1a72fb6c2d81 for the contributor role.

  • 6dbed6c1-6a45-4da1-9aff-c8f1b4d856c4 for the contributor with export role.

  • b68278a1-70d1-4f24-aae2-2803729a6674 for the item reader role.

  • 48c2e03c-9cd3-4bb1-91db-3eaa4564adc2 for the reader role.

  • 37646b77-aee3-418c-8664-4101fa7b44df for the reader with export role.

  • e70daaa1-0c27-4f8e-aa8b-d8dfc34c4579 for the reader no print role.

  • 7d25eda0-2641-445f-9c94-45798165b262 for the reviewer role.

If other roles are used, the role UUID can be obtained using the listDocumentRoles operations.

DocumentRoleRef roleReference = new DocumentRoleRef();
roleReference.setUuid("a456140d-24dc-4cc2-8f23-1a72fb6c2d81");
roleReference.setDomain(domainReference);

The context is also identified with a UUID. If the context was created using the web services, the UUID value may already be known. If not, use the listContexts operations to identity the context required.

ContextInstanceRef contextReference = new ContextInstanceRef();
contextReference.setUuid("9c8d7f1f-9819-4c8e-833f-380f3141e2b6");

The user or group can be identified by GUID or name. See "Working with Users and Groups" for more details.

AccountRef user1 = new AccountRef();
user1.setUuid("9c8d7f1f-9819-4c8e-833f-380f3141e2b6");
 
AccountRef user2 = new AccountRef();
user2.setUuid("urn:user:john.smith");

Once the context, role, and accounts have been identified, the role can be assigned.

DocumentRightOperations rightOperations = new DocumentRightOperationsService().getDocumentRightOperations();
 
rightOperations.assignRole(
    contextInstanceRef,
    roleRef,
    new AccountRef[] {user1, user2},
    null); // no item constraints

If the role is item locked, items can also be specified. The item code values may be well known or can be obtained by peeking sealed content. See "Peeking".

ItemCode itemCode = new ItemCode();
itemCode.setValue("example.stml");
 
rightOperations.assignRole(
    contextInstanceRef,
    roleRef,
    new AccountRef[] {user1, user2},
    new ItemCode[] {itemCode});

4.2.4 Listing the Rights Assigned to a User or Group

A context manager or inspector can list the rights for the contexts that they are allowed to see. Rights listed for a user or group include rights obtained indirectly through group membership.

AccountRef user = new AccountRef();
user.setUuid("urn:user:john.smith");
 
DocumentRightOperations rightOperations = new DocumentRightOperationService().getDocumentRightOperations();
 
// Get all of the rights assigned to the account
DocumentRight[] rights = rightOperations.listRightsByAccount(user);

Or for a group:

AccountRef group= new AccountRef();
group.setUuid("urn:group:everyone");
 
DocumentRightOperations rightOperations = new DocumentRightOperationService().getDocumentRightOperations();
 
// Get all of the rights assigned to the account
DocumentRight[] rights = rightOperations.listRightsByAccount(group);

4.2.5 Unassigning a Role

A context manager can remove roles that have already been assigned within the context to an account. This is performed using the unassignRights method. The assignment of a document role to an account is stored as a document right identified by a UUID.

DocumentRightRef rightRef = new DocumentRightRef();
rightRef.setUuid("ff34e6f9-364b-550d-dfa7-bdf56b0c8188");
 
DocumentRightOperations rightOperations = new DocumentRightOperationsService().getDocumentRightOperations();
 
rightOperations.unassignRights(new DocumentRightRef[] { rightRef });

The UUID for the relevant right can be obtained by using methods such as listRightsByAccount or listRightsByContext.