Managing Department Structures

This chapter contains the following subjects describing functionality to manage department structures:

• Department Interface
• Managing Departments
• Searching for Departments
• Manipulating Grants for Scoped Participants
• Reflecting the Department Association
• Distinguishing Between Scoped and Unscoped Participants

For information on service operations provided by Stardust for predefined permissions concerning departments, please refer to the section Setting Application Permissions of the chapter Securing the Stardust Engine in the Operation Guide.

Department Interface

Stardust provides an interface Department to describe departments via the following methods:

• getDescription(): returns the description of this department.
• getParentDepartment(): gets the parent department bound to this department.
• getOrganization(): gets the organization bound to this department.
• getScopedParticipant(ModelParticipant participant): creates a client side model participant bound to this department.

The getScopedParticipant method throws an InvalidArgumentException if the participant argument is not compatible with the organization to which it belongs. Compatible means that it is either the same organization or a direct member of the organization.

Managing Departments

The AdministrationService provides the following methods for managing departments:

• Create Departments
• Retrieve Departments
• Modify Departments
• Remove Departments
• Delete all existing Departments
• Creating a new or updating an existing Department in Audit Trail on Synchronization

Please also refer to the section AdministrationService of the chapter Stardust Services for information on this service and the according Javadoc of the AdministrationService for detailed information on its methods and their parameter usage.

Create Departments

The method createDepartment creates a new department with the given id, in the scope of the parent department and assigned to the specified organization. The method has the following restrictions:

• The id and the name must not be null or empty and must be unique in the parent scope.
• The department IDs are compared as Strings, without additional processing.
• The parent may be null. If it's null, it means it is a top level department, otherwise it must resolve (by OID) to an existing department.
• The organization must not be null and must resolve to an existing model participant organization. Resolving can be performer either by runtimeOid or by Id.

Exceptions are thrown in the following cases:

• DepartmentExistsException:
  
  • A department with the same Id already exists in the parent scope.
• ObjectNotFoundException:
  
  • Either the parent or the organization could not be resolved.
• InvalidArgumentException:
  
  • Either the Id or the name is null or an empty string.
  • The organization is null.
  • The organization does not resolve to an actual organization in the model (i.e. resolves to a role or conditional performer).
  • The organization is not directly part of the organization to which the parent department is assigned (invalid hierarchy).

Retrieve Departments

The method getDepartment retrieves the department with the given OID. An ObjectNotFoundException is thrown in case no department with the given OID exists.

Modify Departments

The method modifyDepartment changes the name and the description of a department. An ObjectNotFoundException is thrown in case no department having the specified OID exists. If the name is null or contains an empty string, an InvalidArgumentException is thrown.

Remove Departments

The method removeDepartmentremoves the department having the specified OID, all his children and all user grants associated with the department. An InvalidArgumentException is thrown if there are non-terminated or terminated work items that are associated with either the given department or with any of its direct children. An ObjectNotFoundException is thrown in case no department with the specified OID exists. So the instance any activity gets associated with the department, it cannot be deleted. Because the audit trail maintains either ActivityInstance entries or ActivityInstanceHistory entries that references the department which has any activity associated with it. An ActivityInstanceHistory objects can be removed only by archiving the audit trail.

Delete all existing Departments

To delete all existing departments, you can use the cleanupRuntimeAndModels method or the method cleanupRuntime(boolean keepUsers). In the cleanupRuntime(boolean keepUsers) set the parameter keepUsers, which is a flag to specify if the users should be deleted or not, to false.

Creating a new or updating an existing Department in Audit Trail on Synchronization

The method QueryServiceImpl.findDepartment() creates a new department in the audit trail on synchronization if it is not already present there, but exists in the external repository. In case the department already exists in the audit trail, it will be updated on synchronization if there are any changes.

QueryServiceImpl.findDepartment()

On synchronization with external repository the specified department is created in the audit trail if it is not already present there but exists in an external repository. In case the department exists in the audit trail it will be updated on synchronization if there are any changes.

Searching for Departments

Searching for Department with specific ID

Method findDepartment of QueryService searches for a department having a specified Id in the scope defined by the parent department. On synchronization with external repository the specified department will be created in the audit trail in case it is not already present there but exists in the external repository. If the department exists in the audit trail it will be updated on synchronization in case of any changes.

Department findDepartment(DepartmentInfo parent, String id, OrganizationInfo info)
   throws ObjectNotFoundException;

Parameter parent of type DepartmentInfo determines the search scope. It can be null, in which case the search scope is the top level. Parameter info of type OrganizationInfo represents the organization to which the retrieved departments are assigned.

An ObjectNotFoundException is thrown in the following cases:

• the parent could not be resolved
• the specified Id is null
• there is no department with the specified Id in the parent scope

A permission to read departments is required for this method.

Finding all departments satisfying a specific search criteria

The method findAllDepartments(DepartmentInfo parent, OrganizationInfo organization) of the QueryService interface, retrieves a list containing all the departments satisfying the search criteria. The search is performed as follows:

• If both, parent and organization, are null, the result contains all top level departments, regardless of the organization to which they are assigned.
• If parent is not null but the organization is null, result contains all direct children of the parent department, regardless of the organization to which they are assigned.
• If parent is null, but organization is not null, the result contains all departments assigned to the organization, regardless of their parent department.
• If both, parent and organization, are not null, the result contains all departments assigned to the organization, that have as direct parent the specified department.

Whereby parameter parent of type DepartmentInfo determines the parent department. Parameter organization of type OrganizationInfo represents the organization to which the retrieved departments are assigned.

On synchronization departments will be updated if they exist in the audit trail and have any changes. If a department does not exist in the audit trail but is present in an external repository, the department will not be created in the audit trail on synchronization with external repository.

The resulting list can be empty if no departments are matching the search criteria. An ObjectNotFoundException is thrown if one of the following cases applies:

• Neither the parent nor the organization can be resolved
• The specified Id is null or empty
• There is no department with the specified Id in the parent scope

Manipulating Grants for Scoped Participants

With the interface User, you can manage grants for scoped participants, as described in detail in section Adding and Removing Grants of chapter Declarative Security Usage in Stardust Services API.

Adding grants for scoped participants in their default department(s)

For every distinct scope in an organizational hierarchy, there is a dedicated null department. A scoped participant in its default department is granted to a user by granting his null department given by granting the organization for the parent department.

Declarative Security effecting Scoped Participants

• On Data, Model and Partition Level
• On Activity Level
• On Process Level

On Data, Model and Partition Level

If a grant is given to a scoped participant (explicitly or implicitly) on data, model or participant level, then all users assigned to this participant do have execution permission. The department is not taken into account.

On Activity Level

On Activity Level each activity instance stores the department information. Thus, it depends on the concrete activity instance, if a user has execution permission. In that case, the grant including the department has to match the grant permission and the department of the activity instance.

On Process Level

Department information is not stored in the process instance. Instead, the relevant process data defining the department is evaluated on demand.

For example, a process definition permission is granted to a role Role 1. This role is a scoped role with scope data Data 1 defining the department. If the value of Data 1 is executed for a specific process instance, the department required to get the execution permission is evaluated.

Reflecting the Department Association

The method getDepartment of the interface Grant, provides the option to retrieve the department with which this grant is associated. In case the grant has no department association, the method returns null. Please also refer to the Javadoc of the interface Grant for detailed information on this interface and its methods.

Distinguishing Between Scoped and Unscoped Participants

To distinguish between scoped and unscoped organizations and roles, use the method isDepartmentScoped() of the interface ModelParticipantInfo. It returns whether the role or organization is modeled to support the creation of its own departments.

The method definesDepartmentScope() returns true, if this particular organization defines a department scope.

Please refer to the Javadoc of the interface org.eclipse.stardust.engine.api.model.ModelParticipantInfo for detailed information on these methods.