Introduction
The Unified Inbox offers possibility to define substitution rules with so-called substitution profiles. A substitution profile is a set of task models that belong to the same business context. A task model is a stable identifier for a task definition across all of its versions. Profiles can be defined freely. For BPM as task provider maintaining a substitution rules with profiles was not possible till now. Starting with SAP BPM 7.31 SP15 substitution profiles are now supported.
The now released feature provides Java public API methods to manage such substitution profiles. In our article we want to show a simple way to use these APIs.
Overview about Profile Entity
In the Unified Inbox, an end user can create a Substitution Rule for his absence. In order to restrict the type of tasks on which the substitute can work on, he needs to assign one single profile representing those tasks. In BPM a substitution profile consists of several task models. The relationship between the entities is shown in the following figure:
In detail, the substitution profile consists of a technical key and a name. When accessing several provider systems from the Unified Inbox, the chosen keys should be consistent across the provider systems. When creating substitution rules, the profile's name is displayed in the Unified Inbox and thus can be localized in the users’ languages.
The user (having the role BPEM End User) using the Unified Inbox can only use defined profiles. The definition of the profiles is the responsibility of the administrator (having the role SAP_BPM_SuperAdmin). For more details regarding the permission concept, please refer to Using Substitution Profiles with the BPM API.
Determining the TaskModel IDs
To plan the creation of a substitution profile, a list of task models and their ids are required. The Java public API offers a functionality to retrieve the task models; either by name or even all. The search pattern can either contain a fragment of the name of the task model, or it could search for all models by specifying the asterisk ‘*’.
The following example provides the list of task models:
TaskModelManager taskModelManager = BPMFactory.getTaskModelManager();
List<TaskModel> retrievedTaskModels = taskModelManager.getTaskModelsByName(searchPattern);
Having the list of TaskModels, for each model its id and name can be accessed:
URI taskModelId = retrievedTaskModels.get(0).getId();
String taskModelName = retrievedTaskModels.get(0).getName();
For both, the search and the invocation of getName(), the logged on user’s locale determines the language of the text. There is also another method where the locale can be provided as explicit parameter.
Obtaining the SubstitutionProfileManager
All operations related to maintenance and retrieval of substitution profiles are provided by the SubstitutionProfileManager. You might have a look at the corresponding Javadoc.
An instance of this manager can be obtained as follows:
SubstitutionProfileManager substitutionProfileManager = BPMFactory.getSubstitutionProfileManager();
Creating a Substitution Profile
Creating a profile happens in a few steps. First, we create a Java instance of SubstitutionProfile by invoking the following method:
SubstitutionProfile profile = substitutionProfileManager.createProfile(profileKey, defaultName, taskModelIds);
The invocation towards the SubstitionProfileManager creates a new Java object of type SubstitutionProfile with the profile key identifying uniquely the profile. The defaultName provides the name shown to the end users in the Unified Inbox. The created profile has assigned the provided task model ids.
In order to provide translations to the provided default name, for each locale required by end users a translated name can be provided:
Map<Locale, String> localizedNames = new HashMap<Locale, String>();
localizedNames.put(new Locale("EN"), englishName);
localizedNames.put(new Locale("DE"), germanName);
// ... add more localized names as required
profile.setLocalizedNames(localizedNames);So far this object profile only exists in Java memory. To persist it finally, it needs to be stored:
substitutionProfileManager.storeProfile(profile);Retrieving a Substitution Profile
Once created, you might want to retrieve the profiles. This can be done by one of the following methods:
If you have no details about the available profiles, you can use the method:
List<SubstitutionProfile> profiles = substitutionProfileManager.getAllProfiles();
In the most cases you have either its key or its URI by hand. So you could do as follows:
SubstitutionProfile profile = substitutionProfileManager. getProfileById(substitutionProfileId);
or
SubstitutionProfile profile = substitutionProfileManager. getProfileByKey(profileKey);
All invocations return instances of SubstitutionProfile. You might inspect them by utilizing the getter methods.
Modifying a Substitution Profile
It might happen that already created substitution profiles need to get modified. In our example, we would like to remove a task model and to add a localized name to an existing profile.
We need to retrieve the relevant instance of SubstitutionProfile as described before. Based on this, the modifications can be performed:
List<URI> taskModelIdList = profile.getTaskModelIds();
taskModelIdList.remove(taskModelIdToRemove);
Map<Locale, String> localizedNames = profile.getLocalizedNames();
localizedNames.put(new Locale("IT"), italianName);
substitutionProfileManager.storeProfile(profile);In the example above we first remove the task model, second we add the locale ‘IT’ to the localized names and last we store the changed profile.
Deleting a Substitution Profile
The deletion works using the profile URI. If it is not at hand, again the profile needs to get retrieved as shown before. With that, the SubstitutionProfileManager can be invoked with the following method:
URI profileId = profile.getId();
substitutionProfileManager.deleteProfile(profileId);In case the profile is still in use by a substitution rule, the profile cannot be deleted and thus a BPMIllegalStateException is thrown.
Outlook
In the previous chapters we described how to use the Java public APIs for retrieving and managing Substitution Profiles. Looking at the usual development-test-productive landscape setup, there could be a need to transport substitution profiles between development, test and production systems. With the set of functionality explained before, you could implement import/export enabling the transport of substitution profiles between different systems.
To export the profiles the idea would be to retrieve all profiles including assigned task models and translated names. This information can then be stored into an exchange file (in any format you would prefer, e.g. xml, txt). The import of the file content can be implemented using the creation/update functionality of the SubstitutionProfileManager.
- SAP Managed Tags:
