This chapter contains the following subjects describing functionality to manage department structures:
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.
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.
The AdministrationService provides the following methods for managing departments:
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.
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:
runtimeOid or by Id.Exceptions are thrown in the following cases:
The method getDepartment retrieves the department with the given OID.
An ObjectNotFoundException is thrown in case no department with the
given OID exists.
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.
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.
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.
The method QueryServiceImpl.findDepartment() creates a new department in the audit trail.
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.
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.
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:
parent and organization, are null, the result contains all
top level departments, regardless of the organization to which they are assigned.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.parent is null, but organization is not null,
the result contains all departments assigned to the organization,
regardless of their parent department.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:
To be able to create departments in mixed mode, you need to set the following
combination of properties in your carnot.properties 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.
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.
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.
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 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.
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.
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.
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.