![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.
| Alloy by IBM and SAP wiki |
|---|
Alloy software by IBM and SAP provides business users with easy access to key enterprise processes and information, enabling IBM Lotus® Notes® users to act on various SAP workflows and access SAP data from the Lotus Notes mail client.
Users don’t even need to be aware of the existence of the SAP system in their organization. There’s no need to switch to an SAP back-end user interface (UI) for using SAP processes; users can make informed decisions from within Lotus Notes because all the relevant business data is available there.
Alloy is an end-to-end integration of SAP workflows from within Lotus Notes. All the communication between SAP and Lotus Notes occurs through the Web services database NDERPws.nsf, available on the Alloy IBM Lotus Domino® server. In the current Alloy release, leave, travel, reporting, and generic workflows using customized decisions are enabled.
While the Alloy by SAP and IBM Administration Guide covers many details about different aspects of the Web services database, the intent of this article is to cover some of the main topics in depth. It is assumed that you know basic Alloy functionality.
This article explains the Web services that IBM provides or consumes through the Web service database, and it shows how the database is used in various scenarios. Also included is a brief overview of the actions and views available to Alloy administrators and users.
Role of the Web services database in Alloy architecture
Figure 1 shows a schematic of the Alloy architecture, through which SAP workflows are enabled in Lotus Notes. Alloy supports bidirectional communication between IBM and SAP for sending user requests such as Leave, Travel, and Reporting to SAP.
Alloy consumes Web services provided by SAP, such as metadata, application management, role management, reporting/travel/leave workflow, and data consistency services (added in Alloy 1.0.1 version).
Figure 1. Alloy high-level architecture
In Alloy 1.0, the leave, trip, and reporting scenarios are supported and ready to use without modification, and extensibility is provided through support of workflow decision management. To support these scenarios, SAP metadata must be present on Lotus Domino and on the Lotus Notes client side.
This metadata is obtained from and synchronized with SAP regularly by use of the metadata service. This synchronization can be scheduled or can be based on administrator or user demand.
User requests are sent to the Web services database, and the request handler agent picks these requests sequentially and performs the appropriate Web service calls to SAP. This processing flow is termed outbound.
SAP processes these requests and also communicates with the SAP back-end server to gather the necessary response data. IBM provides a generic Web service, BoundItemService, that SAP uses to send responses to IBM. The BoundItemService residing in the Web services database processes these responses and routes them to appropriate users. This flow is termed inbound.
The outbound requests are processed by the request handler agent in a queued fashion, for which the Web service database has implemented such views as these:
- Outbound requests/unprocessed
- Outbound requests/suspended
- Outbound requests/processed
- Outbound requests/all
Administrators can see the requests sent from Alloy users in these queues and can also see the inbound responses from SAP in the Business Objects view in the Web service database. We cover this view in more detail later in the section, “NDERPws from a user perspective.”
The Web services database is also an interface for the administrator to run administrative tasks. See the section, “NDERPws from an administrator’s perspective.”
Creating and setting up the Web services database
The basis for all the design components in the Web services database is the NDERPws.ntf template. This template is added to the Data directory of the Lotus Domino server when you install the Alloy server on Lotus Domino.
The installation also adds language-specific templates (for example, NDERPws_it.ntf, NDERPws_de.ntf, NDERPws_ja, NDERPws_fr.ntf) that you can use to set up the Web services database for a different locale.
The following brief, general steps are used to create and configure NDERPws.nsf. For complete details, see the Alloy by SAP and IBM Administration Guide.
- In the Lotus Notes client, log in as Administrator and select File - Application - New.
- In the New Application window (see figure 2), complete the Server field (which is the Alloy server name) and the Title and File name fields.
Figure 2. Creating the NDERPws database
- Specify the template as NDERP Web Service. If you are using a non-English locale, then use the language-specific template instead of NDERPws.ntf to create the database.
- Click OK to create the database.
The database is now ready to be configured for Alloy. On the left side of the initial page of the database, you see the Application, Roles, F4 Help, and Sidebar panel views:
- Applications. You can have a fixed set of applications; however, these SAP workflows that are implemented in Alloy are ready to use without modification:
- LEMA - Leave management
- TRVL- Travel management
- REMA - Report management
You can also have multiple customized decision workflows. For example, suppose you want to configure an SAP purchase order or SAP material management workflow. They are not provided as ready to use without modification in Alloy, but you can use the extensible generic workflow of Alloy to map these as applications.
When you create a predefined application (LEMA, REMA, or TRVL), you are telling SAP that all the data related to this application can be pulled to Lotus Domino (IBM side) from SAP. If there is no LEMA application created, SAP does not send any leave-related data to the Lotus Domino side.
- Roles. Users can have a role of either USER or MANAGER for an application. The role LEMAUser means that you can create a Leave request. The role LEMAManager means that you can both approve and reject leave requests for your employees.
- F4 Help. This view is part of the reporting metadata and is common to all REMAUsers. The report template includes a Parameter window in which users can edit values or select from predefined lists for different parameters. There can be one or more such parameters having a predefined list of values for a set of report templates.
SAP sends all these sets of values (termed F4 Help) the first time any user logs in to the Lotus Notes client. After that, Alloy performs prescheduled checks for any updates.
- Sidebar panel. This panel is the Alloy-specific panel in the sidebar of the Lotus Notes mail client. It can be configured to display context-specific data relevant to the current Alloy context. For example, when you open a leave request in the Lotus Notes client, the sidebar shows your leave balance. When you open Reports, the sidebar shows related reports links, delivered reports links, and so on.
In NDERPws, the Sidebar panel view shows the configuration documents for the client sidebar panel. The settings in these documents dictate what is displayed in the client sidebar for different Alloy contexts (for example, leave context, reporting context, and so on) The configuration available in NDERPws is fetched to all Alloy clients during a metadata synchronization.
Configuring the server and mail-in database
To set up the NDERPws database for Alloy, the administrator performs the following steps:
- Click Open Server Config on the Actions bar at the top of the NDERPws Applications view. The Server Properties form opens, in which you configure the Server/Client settings specific to Alloy, as shown in figure 3.
- In the top section of the form, make sure that the option Outbound request processing is enabled (this field is new in Alloy 1.0.1).
The SAP J2EE server address field is the address of the server where all the SAP Web services reside. Lotus Domino makes a call to the respective SAP Web services using this address. You can also specify the SAP J2EE server address using the $NDERPJ2EEServer=http://<Server>:<Port> server Notes.ini parameter, for example:
$NDERPJ2EEServer=http://sapj2eedev.notesdev.ibm.com:50200 - Under the SAP Name Mapping section, the Lotus Notes ID must be mapped to an SAP ID, which is contained in the user’s Person document. To map the SAP ID field, you can select the option SAP=statement in the User name field, as we do in figure 3. If instead you select the option Use first name specified in a form field, then it can be mapped to any form field in the Lotus Domino Person document in Names.nsf.
Figure 3. NDERPws server configuration settings
Figure 4 shows the Metadata Fetch Schedule settings from SAP to IBM. Metadata specify the scope for the user actions and visibility. For example, if your role is LEMAUser or REMAUser, then you cannot raise a travel request as you are not authorized to do so; you must instead have a role of TRVLuser.
Assignment of roles to different users occurs in SAP and is synchronized in Alloy Lotus Domino.
Figure 4. NDERPws client configuration settings
The settings in figure 4 trigger a metadata fetch as follows:
- Report catalog after every hour
- Roles every day at 2:00 AM
- Leave every day at 4:00 AM
- Trip every day at 5:00 AM
- Related reports every day at 4:00 AM
- Sideshelf every day at 2:00 AM
The mail-in database is where all your outgoing and incoming mail messages are deposited. To set this database, specify Mail In Database in Names.nsf (same as in NDERPws.nsf), after which the following setting is added to the Lotus Domino Notes.ini, using configuration settings from figure 5:
$NDERPMID=<Alias for the mail in Database>
For example,
$NDERPMID=Alloy Mail In Database@YourDomain
The Alloy by SAP and IBM Administration Guide contains the complete details for setting up NDERPws. Here we provide only some simplified instructions.
As explained earlier, to pull the data related to an application from SAP to the Alloy server, the administrator creates the respective application. To create and configure the supplied applications of LEMA, REMA, or TRVL, follow these steps:
- Go to the Applications view in the NDERPws database, and click New Application on the Actions bar at the top.
- In the Application Properties window, select the application that you want to create from the drop-down list at the top; for example, here we use LEMA (see figure 5).
Figure 5. Select the application
- Click Save & Close; the application is created, and you can see the document in the Applications view. For details on how to configure the Customized Decision application, see the Administration Guide.
When administrators delete an application, they receive a confirmation message and, after successful deletion, receive the appropriate status message.
As mentioned previously, roles decide the scope of actions and data visibility for a user. To create roles, administrators select the Roles / By SAP ID view and click Create/Update Roles at the top (see figure 6). When a new NDERPws database is created, the administrator must pull all the user roles from SAP; later, the administrator can use the same action to synchronize the roles data for getting the latest updates from SAP.
User roles are automatically synchronized on a scheduled basis according to the schedule defined in the client properties of the NDERPws configuration. Administrators can initiate the synchronization manually, using the Create/Update Role button.
Figure 6. Create/Update Roles
Catalog refers to the Report Catalog, which is the repository for all the report templates configured for a user. The SAP administrator initially assigns report templates to users and roles, and the same are fetched to the Lotus Domino side during the report catalog metadata-fetch operation.
The report template is defined under a report category, such as travel or costing, and it defines exactly what data and columns the report provides. It allows users to query this data based on input parameters, with which they can specify discrete data values or ranges, date ranges, delivery format such as ZIP or DOC files, and scheduling such as daily, weekly, and so on.
Users can also request report data based on these parameters. For more details, see the developerWorks® article, “Managing reporting in Alloy by IBM and SAP 1.0.”
In the event that there are issues with report templates or that they are otherwise not usable, users can request that the report catalog is cleared. To do this task, the administrator selects the Reporting / Report Template view and clicks the Clear Catalog action (see figure 7), for one or for multiple users at the same time.
Figure 7. Clear Catalog
Alloy has its own design components in NDERPmail.ntf that must be merged into an existing Lotus Notes mail template (for example, Mail8.ntf) during the initial deployment of Alloy.
The administrator can do this operation from the top of the Applications view, using the Update Mail Template button from the Actions bar and then replacing the design of the mail databases with the newly merged template (see figure 8). Then, to replace the design, the administrator can use either the Lotus Domino server command Load design or the Lotus Notes client menu commands File - Application - Replace Design.
Figure 8. Mail template merge window
The NDERPws template specifies some default sidebar panel data, so this data automatically displays in the NDERPws database when it is created from this template.
Administrators can make further changes to the side-shelf format based on users’ requirements; however, these changes are not customizable on a per-user basis. In other words, in one Alloy installation, all users see the same side-shelf format; the data can vary based on the user, but the format is the same for all.
The type of data that displays in the side shelf depends on a user’s current context (reporting, request approval) and the user's role (manager, employee) as specified in the sidebar panel data. For more details, see the Administration Guide.
Now let’s discuss the various views in the NDERPws database and their use.
Outbound requests go from IBM to SAP, and whenever a new request is raised, it reaches NDERPws (also configured as the mail-in database in Lotus Domino’s Names.nsf). The initial state of this request is Unprocessed (In Process). After it reaches the SAP J2EE server (Web server from SAP) and a work item has been created for it, the state of the request changes to Processed.
If there is an error during Web services communication between IBM and SAP, or if SAP detects a business error in the received request, an error occurs in the outbound flow, in which case the request goes to the Suspended state. Administrators can open any request in the Suspended queue to see a description of the reason for failure.
In addition, administrators can see the following:
- The state of requests in the NDERPws Outbound Requests view (see figure 9). In case of failure, they can check the error message.
- Requests from all Alloy users. They restore appropriate suspended requests into the Unprocessed queue, so that they can be retried later. Individual Alloy users can see only the requests raised by themselves.
Figure 9. Outbound queues
Monitoring inbound business objects
Inbound messages contain the responses from SAP and, because the entire communication occurs over Web services, the inbound messages from SAP are in the form of SOAP XML files.
These messages are parsed and processed and converted by NDERPws into Lotus Notes documents and forwarded to the appropriate user’s mail inbox. Both administrators and users can see the inbound objects in the Business Objects view in the Web service database (see figure 10).
Figure 10. Business Objects view
Now let’s look at the other NDERPws views; specifically, Applications, Report Templates, Report Parameter Help, Roles, and Sidebar Panel data.
- Applications. This view contains the different applications configured in Alloy, such as the default leave, travel, reporting, and multiple customized decisions applications (see figure 11).
Figure 11. Applications view
- Report Templates. SAP has a configured set of report templates for Alloy users. These report templates are pulled to the Lotus Domino server and eventually to a user’s local metadata database as a part of the metadata fetch. Administrators can select the Reporting / Report Templates view to see the report templates configured for each user under the user’s name (see figure 12).
Figure 12. Report Templates view
- Report Parameter Help. F4 Help (available for Reporting/Report Templates only) documents can be seen using the Reporting - Report Parameter Help view, which contains the available list of values for different report parameters provided by SAP (see figure 13).
These documents are also pulled to a user’s local metadata database during metadata synchronization, so they can be used in the form of drop-down help lists when users perform various actions such as Personalize report template and Run report.
Figure 13. Report Parameter Help view
- Roles. An administrator and a user can see the roles assigned to a user in this view, under Roles - By Role Name (see figure 14).
Figure 14. Roles view
- Sidebar Panel / Panel data. This view contains the available configuration data of the Alloy side shelf (see figure 15). The configuration can be changed by the administrator, if required. All sidebar configuration data is also sent to the user’s Local Metadata database during metadata synchronization and, based on this data, the Alloy side shelf is rendered in the Lotus Notes client.
Figure 15. Sidebar Panel / Panel Data view
Here are some tips for troubleshooting common issues.
Resolution: Check whether the administrator has created a LEMA application and has updated roles after that creation, using the Create Application and Create/Update Roles actions in the NDERPws database.
Not all the actions in the Mail database are in the (expected) French locale
Resolution: This problem could occur because of an incorrect merge of the mail templates. The administrator must use a clean French mail template, merge it with NDERPmail_fr.ntf, and, after the merge, make sure to run the Lotus Domino load design command or replace the design of the mail database through the Lotus Notes client.
Resolution: Check whether the NDERPws database has F4/Report Parameter Help documents available; if not, it’s likely that the Web service call failed. The administrator can investigate the failure on the IBM and SAP sides. If these documents are present in NDERPws, the user’s local metadata gets them during the next metadata synchronization, after which the user is able to use the help lists.
User’s report catalog is unusable
Resolution: Ask the administrator to clear the corresponding report catalog on NDERPws. The next time the Lotus Notes client synchronizes with the report templates on NDERPws (which occurs at an interval set by the administrator), the user’s report catalog is reset to a usable state. Thus, all the report templates configured on the SAP side by the SAP administrator become available to the user, after which the user can create personalized templates based on these templates.
Users are unsure how to update their Alloy sidebar panel data
Resolution: The data in the Alloy sidebar panel is automatically refreshed based on a schedule set by the administrator. You can also refresh the sidebar panel data manually.
To do this step manually, click the Refresh button on the sidebar panel's Action bar. This action refreshes leave and report data in the Alloy sidebar panel and displays any customization that the administrator might have made to the panel (for example, the addition of a new HTML link) since the last refresh.
Note that refreshing the sidebar panel does not affect report catalog synchronization, which is performed based on an interval set by the administrator.
A user requested a report quite a while ago, but it’s still not delivered to the user's inbox
Resolution: Check the suspended queue in NDERPws to determine whether the user’s report request has been suspended; if it has, open the request to see the reason. If it is some kind of transient error, check whether the administrator can restore the request to the Unprocessed queue, so that it will be retried.
Resolution: The administrator can create custom views based on the data available in the Business Objects view. He can categorize and sort based on recipient, date, boundItemType, and so on, to get the desired view for the manager.
The Web services database is a crucial part of the Alloy functionality as its design provides the means for all SAP and IBM communication. The database serves as an interface for administrators to set up the Alloy application workflows and user roles, while users can monitor requests and troubleshoot problems, using the appropriate views.
- Participate in the discussion forum.
-
Read the developerWorks article, “Managing reporting in Alloy by IBM and SAP 1.0."
-
Read the developerWorks article, “Performance report: Alloy by IBM and SAP 1.0."
-
Read the IBM Lotus Notes and Domino wiki article, “Basic troubleshooting guidelines for Alloy software by IBM and SAP 1.0."
-
Read more articles about Alloy on the Lotus Notes and Domino product wiki.
-
Refer to the Alloy content in the Lotus Notes and Lotus Domino Information Center.
-
Refer to the IBM Support Technote, “Domino 8.0.2 and Notes 8.0.2 system requirements for Alloy v.1.0."
-
Refer to the product page for Alloy by IBM and SAP.
-
Watch the Alloy demo, "Optimizing decision making and improving productivity."
Amita A. Vadhavkar is a Senior Staff Software Engineer with IBM India Software Labs, Pune, India. She currently works on the project Alloy Software by IBM and SAP. Since she joined IBM in 2003, she has worked on various technologies in product development, such as WebSphere, service-oriented architecture, and Lotus. You can reach Amita at avadhavk@in.ibm.com
Prashant U. Admile is an Associate Software Engineer with IBM’s India Software Labs in Pune, India. He currently works on the Alloy software by IBM and SAP project, and since joining IBM in 2007, he has also worked on the Level 3 Lotus Domino server team. You can reach Prashant at pradmile@in.ibm.com.
