Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

While the necessary steps within the SAP ERP system and SAP Netweaver are mentioned, the focus of the article is on the necessary customization within Lotus Notes.

Back to top

Sample scenario: Simple material master creation approval

Rather than implementing a complex business workflow, let's focus on the key steps here and choose a simple scenario. Let's assume that the customer needs to control the creation of material masters (transaction MM01) in the SAP ERP back-end network or server and thus wants to create a business workflow that triggers a decision step upon each material master creation. The sole purpose of the decision step is to approve or decline the new material. In addition to the standard attributes of a material business object, some additional attributes (such as weight and weight unit) are defined and passed down to the approver in Lotus Notes as shown in figure 1.

Based on the information provided about the newly created material, the approver makes a decision directly within the Lotus Notes inbox, and the corresponding approval or rejection is carried out in SAP. For this scenario to be implemented, several steps within SAP ERP and Netweaver and in Lotus Notes and IBM Lotus® Domino® need to be carried out.

Back to top

Setting up the approval workflow in SAP

Because you want to represent a new material with additional data attributes, you first need to create a new business object subtype in SAP ERP and create the additional attributes. To ensure that your custom approval workflow can be triggered upon creation of instances of this business object subtype, you also need to establish the corresponding event linkage.

Furthermore, you need to create the sample approval workflow using SAP Workflow Builder. Detailed step-by-step instructions for the creation of container elements, attributes, and the workflow definition and the previously mentioned steps can be found in this blog entry on the SAP Developer Network (SDN).

For the sake of simplicity, no complex agent determination has been implemented in this sample, but rather the initiator of the material creation is also the approver. Obviously, this approach does not make sense for production approval workflows.

Now that the required business object and workflow have been defined, you need make sure that the approval decision is routed to Alloy and thus brought down to the approver's Lotus Notes inbox. Again, for this exercise, you do not implement any complex scenarios including coding and modeling on the SAP side; rather, you leverage the standard outbound/inbound handling supported through workflow pattern customization in the SAP Information Worker Implementation Guide.

The workflow pattern customization takes care of the definition of a workflow application, the decision step to be exposed to Alloy, and the specific settings for outbound and inbound processing. From a Lotus Domino perspective, the application ID and the groupware bound item type are the most important settings on the SAP side. The application ID is used to look up the corresponding application configuration in Alloy on Lotus Domino, and the groupware bound item type's value is used to map the incoming message to a specific form in Lotus Notes to render the data. In this sample, you specify the application ID as ZMATCR and the groupware bound item type as MaterialMasterCreationWorkflow.ApproverTask. Detailed step-by-step instructions for the workflow pattern customization in SAP can be found in this blog entry on SDN.

Back to top

Configuring and customizing the approval handling in Lotus Notes and Lotus Domino

Now that your material creation workflow is implemented on the SAP side, you need to configure Alloy on Lotus Domino so that incoming approval requests are accepted and handled appropriately. The central component of all Alloy-related configuration on Lotus Domino is the NDERP Web Service application on the Alloy Lotus Domino server. Open the database, navigate to Applications, and then click the New Application button at the top to create an application configuration document. Each custom workflow decision needs to be represented by its own application configuration document in the NDERP Web Service application; see figure 2 for a sample configuration document.

In the Application Properties field, specify Customized Decisions from the application drop-down list. In the Application key field, enter the same value that you specified for application ID in the workflow application in the ERP back-end network (in this case, ZMATCR). It is the application ID that maps a workflow application in SAP to a configured Alloy application in Lotus Domino.

The value entered in the Application Name field is used as the description for the approval work items delivered to users' inboxes and for the role assignments in the Alloy administration user interface.

Up to this point, you have configured the necessary mapping between the workflow application that you implemented in SAP and a corresponding Alloy application on Lotus Domino. What's missing is the definition of how the incoming data should be rendered in Lotus Domino. Documents are typically rendered using forms in Lotus Domino; therefore, you need to specify the type of incoming message that is expected and what form it should be rendered with in the user's mail file. Here you need the value that you specified previously for the groupware bound item type in the SAP ERP back-end network.

Enter MaterialMasterCreationWorkflow.ApproverTask in the Bound Item Type field and set the Form name to (GenericCustomApprovalWorkflow). You create this hidden form by copying the default workflow approval form (ERPApprovalWorkflow), which is shipped as part of the Alloy mail template extensions and provides a standard rendering for arbitrary approval messages. Be sure to create a copy rather than use (ERPApprovalWorkflow) directly so that you can make minor changes to this form while preserving the original form, thus avoiding potential issues when you upgrade to future versions of Alloy.

Even though they are not leveraged in our example, it is important to highlight the last two fields on the application form: the Status update form name and the Custom agent fields. The Status update form name field can be used to specify a custom form that is used when status update messages for this workflow application need to be rendered in the user's mail file. This option allows for custom controls and form logic to be implemented for status update messages.

Even more powerful is the Custom agent setting. Use this setting to programmatically control data elements within the incoming messages, that are rendered by the approval forms for this workflow. Note that agent use requires that you are familiar with the content and rules that exist for this item type's data in the SAP system and are comfortable creating agents in IBM Lotus Domino Designer. One common scenario for using custom agents is name lookups, where SAP users can be represented in an incoming message with their SAP user IDs. Such an agent looks up their corresponding Lotus Notes DN or other name formats programmatically and adds it to the message.

Now save and close your new application and wait until you receive the notification "The application was saved successfully."

To recap, up until now you have created a new workflow application in SAP, including a user-facing decision step, configured Alloy on Lotus Domino to accept approval messages from that workflow, and specified a yet-to-create form to use to render them. Not only do you need to create that custom form now, but because you specified extended attributes for the workflow container in SAP, you want the approver in Lotus Notes to have access to those additional data elements. They might be required information for the approval or rejection decision.

As defined previously, incoming approval messages are rendered with a form called (GenericCustomApprovalWorkflow) in Lotus Notes. Let's take a closer look at the necessary steps to create this form. As part of the Alloy installation, you merged the Alloy mail design elements into your organization's mail template. Open the master mail template that includes the Alloy design elements in Lotus Domino Designer and find the form (ERPApprovalWorkflow) to create a copy of it (for example, by pressinging Ctrl+C and then Ctrl+V). See figure 3.

After you paste the copy, Lotus Domino Designer asks you if want future changes to the original form to be applied to this copy. Click No, and rename the form name to (GenericCustomApprovalWorkflow). Also, rename the form alias to GenericCustomApprovalWorkflow. Then, open the form in Lotus Domino Designer to take a closer look at its contents. See figure 4.

As you can see in figure 4, the form (GenericCustomApprovalWorkflow), which is a copy of the (ERPApprovalWorkflow) form, is rather simple. It contains the action buttons to approve or reject, a header area, a comments area, and a body. To enable this form to render additional material information, you need to customize it using Lotus Domino Designer.

To simplify the reuse of your custom workflow decision solution, you do not want to insert custom fields and form logic directly in this form; rather, you can leverage a computed subform approach. This approach allows you to use (GenericCustomApprovalWorkflow) for arbitrary workflow applications that require rendering only additional workflow-relevant data rather than any complex form or business logic. Open the form (GenericCustomApprovalWorkflow) in Lotus Domino Designer, position the cursor underneath the body field, and select Create\Resource\Insert Subform from the main menu to launch the window that allows you to insert a subform. In this window, make sure that you select the Insert Subform based on formula option, as shown in figure 5.

Specify BoundItemType as the default value for the computed subform as shown in figure 6. BoundItemType is a Lotus Notes item that Alloy automatically adds to the Lotus Notes document when processing an incoming message from SAP. The item contains the same value that was specified for Bound Item Type in the application configuration in the NDERP Web Service application.

Using this approach, you can implement specific data handling in separate subforms rather than in the generic (GenericCustomApprovalWorkflow) form, where each subform corresponds to a bound item type, meaning a specific type of incoming approval message. In this case, you know that the expected bound item type is MaterialMasterCreationWorkflow.ApproverTask; therefore, you need to create a subform with that exact name. Enter MaterialMasterCreationWorkflow.ApproverTask in the Name field of the New Subform window, as shown in figure 7.

Forms or subforms in Lotus Notes are designed to render data that is held in a Lotus Notes document. In this case, the overall workflow-related data is handled in the (GenericCustomApprovalWorkflow) form already and the new subform is supposed to render just the information that was specifically modeled into the Workflow Container to represent your material business object. How do you access the attributes that you specified in the workflow container in SAP now within Lotus Notes?

By default, Alloy creates Lotus Notes items for each element defined in the corresponding workflow container in SAP, in this case, the elements for ZMaterialNumber, ZMaterialText, and so on. To avoid naming conflicts, Alloy prefixes these fields with WorkflowContainer00 so that the material number value is stored in an item called WorkflowContainer00ZMaterialNumber. All you need to do is to create form fields in the new subform that reference the corresponding Lotus Notes items created by Alloy. In this case, you want render a table that shows all the relevant information about the new material from SAP.

Use the regular Lotus Domino Designer controls to create a table with two columns, one for a label and a second one to hold your fields with the data values. Create each field as a computed text field as shown in figure 8.

Note the highlights in figure 9; each field in the table refers to the corresponding workflow container element using the Alloy-specific prefix. You might notice that this sample form uses a slightly different set of extended material attributes than those shown in the SDN blog entry mentioned previously. These additional elements would have to be added to the business object subtype and workflow container in SAP ERP.

In addition to the workflow container fields, there is one more field shown in figure 10. The field ZSenderName is meant to demonstrate the IBM Lotus Sametime® integration capabilities that you can leverage in your Alloy solutions (if a Lotus Sametime server is available and configured appropriately).

As part of your workflow definition you could pass user information (represented as SAP user IDs), in addition to other business object data, to show the Lotus Sametime online status of these users in your approval form. Because Lotus Notes requires fields enabled for Lotus Sametime awareness to be of type Name, it is then necessary to fetch the value passed in by SAP and do a lookup for the Notes name of that SAP user. One requirement for Alloy to work properly is to have SAP user names added to Lotus Domino person documents for Alloy users. Thus, a simple LotusScript® agent could be used to look up the Lotus Notes name for a given SAP user ID. For simplicity reasons, we do not cover such a script here, but note that such an agent would need to be referenced in the workflow application document in the NDERP Web Services application.

Finally, if you have not already done so, save and close your new subform and the (GenericCustomApprovalWorkflow) form.

Back to top

Additional Alloy configuration

Are you ready yet? Not quite. Let's recap: You implemented your back-end workflow in SAP, you configured a corresponding application in Alloy in Lotus Domino, and you implemented a custom form or subform to render your additional data from within the incoming approval messages. But how would SAP and Lotus Domino determine who to route such approval messages to?

One design principle in Alloy is that all business logic is owned and managed by SAP rather than Lotus Domino. Therefore, the corresponding role data needs to be configured on the SAP side. More specifically, the application roles need to be configured in SAP User Management Engine (UME), which is part of the SAP Netweaver platform. Be aware that this configuration can be done only after the workflow application has been configured in Alloy on Lotus Domino. After an application entry in the NDERP Web Service application exists, Alloy synchronizes this entry with the Alloy administration on Netweaver, and a corresponding entry shows up in the Alloy administration UI on Netweaver, accessible through the default URL: http://<j2ee-engine>:<port>/alloy.

Detailed instructions on how to map the required application roles to user groups in UME can be found in this blog entry on SDN.

Believe it or not, that's it. You should now be able to test your new custom workflow application. It is important to test the full round-trip operation, meaning from workflow initiation, through approval message routing and handling in Lotus Domino, to processing of an approval decision in SAP.

Back to top

Conclusion

In this article, we described all necessary steps to implement a custom workflow decision scenario in Alloy 1.0. To focus on the key aspects, we have accepted several simplifications that would most likely not be applicable to production solutions. One such example is the agent determination in the sample SAP workflow. Another example is that in many cases you would want to expose existing workflows to Alloy rather than having to modify existing or even create new workflow definitions in SAP. In such cases, it can be required that you code custom outbound and inbound processing in the SAP ERP back-end network. This blog entry on SDN explains how that can be done.

Resources

• Participate in the discussion forum.
  
  
• Read the Alloy articles on the Lotus Notes and Lotus Domino wiki.
  
  
• Refer to the Alloy by IBM and SAP Web site.
  
  
• Refer to the Alloy system requirements.
  
  
• Consult the Alloy support technotes.
  
  
• Refer to the Alloy Administration documentation.
  
  
• Refer to the SAP SDN entries related to Alloy.
  
  

About the author

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Sample scenario: Simple material master creation approval
• Setting up the approval workflow in SAP
• Configuring and customizing the approval handling in Lotus Notes and Lotus Domino
• Additional Alloy configuration
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Notes and Domino Administrator
• Demo: Lotus Notes 8 composite applications
• Webcast: Modernization approaches to reduce the total cost for multi-platform enterprise applications
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Notes and Domino Administrator

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers