Managing Department Structures

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

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

Department Interface

Infinity Process Platform provides an interface Department to describe departments via the following methods:

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:

Please also refer to the section AdministrationService of the chapter Infinity Process Platform 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:

Exceptions are thrown in the following cases:

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 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 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:

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:

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:

Creating Departments in mixed Mode (external / internal Authentication)

To be able to create departments in mixed mode, you need to set the following combination of properties in your file:

Security.Authorization.SynchronizationStrategy = your authorization synchronization strategy class
Security.Authorization.SynchronizationProvider = your synchronization provider
Security.Authorization.Mode = internal

Now you are able to create departments and use the API provided for managing departments.

In case you do not set Security.Authorization.Mode = internal, departments are imported and you are not able to create, modify or delete them via API.

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 Infinity Process Platform 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

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.