Skip to Content
Author's profile photo Lora Tsanova

Developing BPM Custom Inbox with Task Custom Attributes and Actions

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.

/wp-content/uploads/2013/05/pic01_214409.jpg

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.

/wp-content/uploads/2013/05/pic02_214410.jpg

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.

/wp-content/uploads/2013/05/pic03_214411.jpg

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.

/wp-content/uploads/2013/05/pic05_214500.jpg

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
}

/wp-content/uploads/2013/05/pic05_214500.jpg

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.

/wp-content/uploads/2013/05/pic06_214433.jpg

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.

/wp-content/uploads/2013/05/pic07_214434.jpg

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
    }

/wp-content/uploads/2013/05/pic08_214435.jpg

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.

Assigned Tags

      20 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Christian Loos
      Christian Loos

      Excellent blog.

      One remark though: I believe you listed the wrong API method. The method to complete a task via custom action is this:

      complete(URI taskInstanceId, commonj.sdo.DataObject taskOutputData, CustomAction customAction)

                Complete the processing of the task, i.e. set the task to status Completed with custom action.

      Author's profile photo Lora Tsanova
      Lora Tsanova
      Blog Post Author

      Thank you for the feedback 🙂

      Author's profile photo Stefan Henke
      Stefan Henke

      Great blog on this new feature. Looking forward to see more from you 😉

      Author's profile photo Jocelyn Dart
      Jocelyn Dart

      Great blog Lora - and a nice example of using the BPM APIs in practice. Very much appreciated.

      Author's profile photo Thierry Logiest
      Thierry Logiest

      Great blog !

      Author's profile photo Former Member
      Former Member

      Thanks for your great blog.

      I have a question.

      I made my task list with BPM API,

      and on the task list, how I can open standard task UI ?

      I want to open task UI by selecting a task on my task list.

      Is there any API for opening task ui? or any url ?

      Author's profile photo Stefan Henke
      Stefan Henke

      Hi Jinho,

      you have the option to resolve a url for a specific task by calling the API method TaskInstanceManager#generateTaskExecutionUrl. This should allow you to either redirect to the url or open it in a new window.

      Author's profile photo Former Member
      Former Member

      Hi Stefan Henke

      Thanks for your reply. It works 🙂 .

      Author's profile photo lok y
      lok y

      Hi Jinho,

      We have a similar requirement, where in FIORI inbox application, on select of a task item, we want to show a hyperlink in the custom attribute value. We are able to show normal text as custom attribute value but unable to show a hyperlink. Any help.

      Regards,

      Lok

      Author's profile photo Jocelyn Dart
      Jocelyn Dart

      Thank for a very useful blog!

      Author's profile photo Former Member
      Former Member

      Hi Lora,

      Thanks for a good blog.

      I have tried to redo it as described below.

      My scenario is to create tasks that show the custom attributes in my SAP BPM Inbox, but this does not happen. I am wondering if the java application server /SAP NetWeaver also has to be on patch level SP08 ? (we are on SP06).

      I have made the following test/demo scenario:

      Where a service starts 3 task's (human activities).

      The custom attributes of the first tast are:

      But when deployed and during runtime - they do no show in the BPM Inbox:

      Here from the process mgmt:

      But in the BPM Inbox the custom attributes are not shown ?

      What is the trick? Is there more to be done ? I have not done anything with the BPM API ? Is that needed - and where do I do this ?

      Thanks

      Author's profile photo Lora Tsanova
      Lora Tsanova
      Blog Post Author

      Hi Torsten,

      Please update your application server, because I think that bmp inbox deliver this functionality in upper releases

      Best Regards,

      Lora

      Author's profile photo Former Member
      Former Member

      Hi Lora,

      Thanks, do you know if it is SP07 or SP08 ?

      Best Regards,

      Torsten

      Author's profile photo Lora Tsanova
      Lora Tsanova
      Blog Post Author

      I would say SP8, to be sure

      Best Regards,

      Lora

      Author's profile photo Christian Loos
      Christian Loos

      Custom Attributes and Custom Actions are available with SP07, but if you anyways have to upgrade why not go straight to SP08 - you get additional features in the inbox like forwarding tasks or showing from whom the task was sent

      Author's profile photo Former Member
      Former Member

      Hi Christian,

      Thanks, then will hopefully go for SP08.

      Author's profile photo Former Member
      Former Member

      Hi

      Finally we upgraded to sp07 - but still no attributes in my BPM inbox ? is there any thing i need as default before i can see the configured attributes in the BPM inbox ?

      Author's profile photo Lora Tsanova
      Lora Tsanova
      Blog Post Author

      No there are no additional steps to do. But there were changes in design time, and you have to rebuild your project with SP7. Did you do this?

      Author's profile photo Former Member
      Former Member

      Hi Lora, Thanks for you're reply. The reason is the rebuild. We use NWDI - and this component has not been "patched" to the new SP.

      Author's profile photo Siddhant Bhatankar
      Siddhant Bhatankar

      Thanks for the article Lora