Introduction

If you had the chance to touch SAP NetWeaver BPM 7.31 SP6 or a later SP, you may notice the newly introduced features to define custom attributes and actions for tasks.

The custom attributes and actions help task owners make appropriate decision for a task by presenting essential information in the tasks list directly. Having the important task’s data presented, task owner can take a direct action, without opening it, on a task instance in case custom action for this task had been specified. In SAP NetWeaver BPM 7.31 SP7, the task editor has been extended with a new tab called “Attributes & Actions”. Custom attributes and actions are exposed through SAP NetWeaver BPM’s public API and could be consumed in custom inbox. The public API allows obtaining the custom attributes and actions of the task and their values and completing the task directly.

With these articles I would like to describe how to benefit from custom attributes and actions for tasks in your custom inbox using the public API. I would also provide information about what are the necessary steps to enable custom attributes and actions for task definition.

Sample BPM process

To demonstarte the custom attributes and actions I would use a commonly used process for master data quality.

A company recently acquired new companies and needs to align master data process with all new branches. Customer master data creation process is one of them. The process has the following routine:

1. Customer requester is a person who is responsible for acquiring retailers for IDES Company. Once the requester finds a new retailer, he/she enters information about it. The data that the requester enters is the customer’s ID, first name, last name, country, city, street, zip code, and credit limit.
2. The data quality manager who is working in the same country location as the new customer reviews the data, and if needed, returns it for rework by customer requester.
3. Data quality manager can also directly approve or reject customer’s request.

Custom attributes for tasks

Custom attributes are defined during design time as a part of a task definition when performing modeling in Process Composer. The input data context of the task definition would be available for choosing as custom attributes. The attributes defined in Process Composer are visible as columns in the task list in BPM Inbox. Custom attributes of task would be visible in BPM Inbox when the user filters by task type. The expression would be calculated using the real process data and would be visible as a value. To define your custom attributes for a task follow the steps below.

Modeling Custom Attributes in NWDS

Open “Attributes and Actions” tab to define custom attributes for task definition. For each custom attribute the user has to specify its name, label, type, and expression (value). The label of the attribute is a translatable text and the name of the action serving as a key. The expression is the actual value of the attribute, populated in BPM inbox. The order in which the custom attributes are listed in the table would be same when the custom attributes are retrieved from BPM’s public API.

Optional: Translation of task custom attributes

Copy and rename task’s ‘.xlf’ file. Then open it with S2X document editor. Choose the ‘Source language’ in Header tab, open ‘Resource Text’ tab, and edit the translated text.

For more information, see Internationalization of Java Projects.

Consumption of Custom Attributes through Public API

To fetch the custom attributes, use TaskDefinitionManager, TaskInstanceManager, and TaskAbstractCustomAttributesCriteria. The task definition contains information about the name, label and type of all custom attributes defined for this task. The task instance contains the actual values for these custom attributes. To get TaskAbstract with custom attribute’s value, use an instance of TaskAbstractCustomAttributesCriteria as shown below.

IAuthentication auth = UMFactory.getAuthenticator();
IUser user = auth.forceLoggedInUser(request,response);

TaskInstanceManager taskInstanceManager = null;
TaskDefinitionManager taskDefinitionManager = null;

        try {
            taskInstanceManager = BPMFactory.getTaskInstanceManager();
            taskDefinitionManager = BPMFactory.getTaskDefinitionManager();

           

//Task statuses we are interested in
            Set<Status> statuses = new HashSet<Status>();
              statuses.add(Status.READY);
              statuses.add(Status.CREATED);
              statuses.add(Status.IN_PROGRESS);
              statuses.add(Status.RESERVED);


//The TaskAbstractCustomAttributesCriteria class is a marker telling the
//getMyTaskAbstracts() method whether to fetch the custom attributes for the
//tasks or not.
           
List<TaskAbstract> taskAbstracts =
 taskInstanceManager.getMyTaskAbstracts(statuses, null, new TaskAbstractCustomAttributesCriteria());
           
for(TaskAbstract ta : taskAbstracts) {

 URI taskModelId = ta.getModelId();
 URI taskDefinitionId = ta.getDefinitionId();

If you are interest in particular task definition and want to get its custom attributes, you have to use the following approach:

{

//Get custom attributes definitions for the current task definition
TaskDefinition taskDefinition =   taskDefinitionManager.getTaskDefinition(taskDefinitionId);
List<CustomAttributeDefinition> customAttributeDefinitions =
      taskDefinition.getCustomAttributeDefinitions();
     
     for(CustomAttributeDefinition cad : customAttributeDefinitions) {
     //Retrieves the label of the custom attribute defined which is       
      //translated based on logged in user's Locale.
            String caLabel = cad.getLabel();
            String caName = cad.getName();
            Class<?> caType = cad.getType();
      }
            //Get The custom attribute values
            Map<String, Object> caValues = ta.getCustomAttributeValues();
}

If you have more than one version of the process and you are interested in an active version of task definition and its custom attributes, you have to use the following approach:

{
//Get custom attributes definitions for the active task definition
TaskDefinition taskDefinition =  taskDefinitionManager.getActiveTaskDefinition(taskModelId);
List<CustomAttributeDefinition> customAttributeDefinitions =
      taskDefinition.getCustomAttributeDefinitions();
     
     
for(CustomAttributeDefinition cad : customAttributeDefinitions) {
     //Retrieves the label of the custom attribute defined which is
     //translated based on logged in user's Locale.
            String caLabel = cad.getLabel();
            String caName = cad.getName();
            Class<?> caType = cad.getType();
}
}

If you have more than one version of the process and you are interested in all versions of task definitions and their custom attributes, you have to use the following approach:

{
//Get custom attributes definitions for any task definition
Set<TaskDefinition> taskDefinition = taskDefinitionManager.getTaskDefinitions(taskModelId);
for(TaskDefinition td : taskDefinition) {
            List<CustomAttributeDefinition> customAttributeDefinitions =
           td.getCustomAttributeDefinitions();
           
for(CustomAttributeDefinition cad : customAttributeDefinitions) {
     //Retrieves the label of the custom attribute defined which is
      //translated based on logged in user's Locale.
            String caLabel = cad.getLabel();
            String caName = cad.getName();
            Class<?> caType = cad.getType();
      }
      }
}
}
       
}catch(BPMException e ) {
       //exception handling goes here
}

Custom actions for tasks

Custom actions are defined during design time as a part of a task definition. At runtime, they can be fetched via the public API or accessed through the BPM Inbox. The public API is enhanced with a complete method taking custom action’s technical name as a parameter. The name of the action can be taken during the next step of the process by mapping the new task attribute “customAction” to the process context. To define your task custom actions follow the steps below.

Modeling custom actions in NWDS

To enable the defining of custom actions for task definition, open the “Attributes & Actions” tab. This tab is used to define actions in a table. For each custom action you have to specify the name, label, and description. The label and description are translatable text, and the name of the action serves as a key. The actions will be presented in BPM inbox as buttons. The order in which the custom actions are listed in the table would be same when the custom actions are retrieved from BPM’s public API.

Optional: Translation of task custom actions

You can follow the same approach described for custom attributes.

Modeling process workflow using action value

You have to map ‘customAction’ value to some context. So this ‘customAction’ attribute can be used for decision-making. In our case this value is used to make decision about how the process ends.

Consumption of custom actions through public API

This code snippet shows how to get the custom action definitions for all tasks assigned to the current user.

IAuthentication auth = UMFactory.getAuthenticator();
IUser user =  auth.forceLoggedInUser(request,response);

    TaskInstanceManager taskInstanceManager = null;
    TaskDefinitionManager taskDefinitionManager = null;
   
try {
        taskInstanceManager = BPMFactory.getTaskInstanceManager();
        taskDefinitionManager = BPMFactory.getTaskDefinitionManager();

        //Task statuses we are interested in
        Set<Status> statuses = new HashSet<Status>();
            statuses.add(Status.READY);
        statuses.add(Status.CREATED);
            statuses.add(Status.IN_PROGRESS);
            statuses.add(Status.RESERVED);


        //The TaskAbstractCustomAttributesCriteria class is a marker telling the
          // getMyTask Abstracts() method whether to fetch the custom actions for the tasks or not.
        List<TaskAbstract> taskAbstracts =
           taskInstanceManager.getMyTaskAbstracts(statuses, null,
                     new TaskAbstractCustomAttributesCriteria());
  
      PrintWriter pw = response.getWriter();
        for(TaskAbstract ta : taskAbstracts) {
            URI taskDefinitionId = ta.getDefinitionId();
                TaskDefinition taskDefinition = taskDefinitionManager.getTaskDefinition(taskDefinitionId);
                List<CustomActionDefinition> customActions = taskDefinition.getCustomActionDefinitions();
            }

    }catch (BPMException e) {
               // TODO: handle exception
    }

Complete a task instance with a custom action via the public API

The public API of SAP NetWeaver BPM now has a complete method accepting a custom action as a parameter:

    public  void  complete(URI taskInstanceId, DataObject taskOutputData, CustomAction customAction) 

Using this method you can complete a task with one of the already defined custom actions for this task definition. When the complete method call from public API with custom action value is processed, task completion message is created with custom action value, if chosen. And during the same method’s (complete) processing, notification of the completion state is delivered to the BPEMTaskParent, where the task attribute’s ‘customAction’ element is updated with the custom action value that is chosen to complete the task.

For more information about custom attribute, see Defining Custom Attributes for Tasks.