Abstract: The purpose of this article is to provide a technical overview of the factors and components involved in troubleshooting issues that may arise with Alloy™ Software by IBM® and SAP 1.0. Included is a high-level presentation of Alloy by IBM and SAP architecture and troubleshooting FAQs.
- Alloy architecture
- Application roles
- Metadata handling
- Scope of troubleshooting in Alloy (client, server and SAP)
- Troubleshooting Notes Client with respect to Alloy
- Configuration checkpoints
- Troubleshooting checkpoints
- Troubleshooting Lotus Domino with respect to Alloy
- Configuration checkpoints
- Troubleshooting checkpoints
- Some troubleshooting FAQs
- About the authors
Troubleshooting is a vast topic and touches all parts of the system. There are elaborate guides available for each aspect of a product, such as installation, system requirements, setup, and administration. For a new user or administrator, however, it’s usually helpful to get started with a couple of handy tips and then refer to these guides f or any further details. The main purpose of this article is to provide these tips.
Let’s begin with a schematic of the product architecture (see figure 1). For general information about this and all aspects of the product, visit the Alloy by IBM and SAP product page.
Figure 1. The architecture behind Alloy
All communication in Alloy between IBM Lotus® Notes® & Domino® and SAP Business Suite is through IBM Web Services. This communication can be either synchronous or asynchronous, with SAP invoking Web Services for sending asynchronous responses to Lotus Domino.
Metadata is obtained from SAP and synchronized with SAP updates. This synchronization can be either scheduled or on-demand by the administrator/user. In the Alloy 1.0 release, three scenarios are supported—Leave, Trip, and Reporting—along with the Generic workflows.
Roles control the scenario-specific actions users can perform in Alloy. SAP manages the roles, and Alloy reads them to control the scenario-specific menu options exposed to the users.
In Release 1.0 the following user roles are provided:
- Manager roles:
- Workflow Decision Management
- Leave Management
- Travel Management
- Employee roles:
- Leave Management
- Travel Management
- Reporting Management
Alloy reads the SAP configurations, for example, Leave Types or Report Templates, and provides them to the user:
- Client updates automatically
- Application logic is driven from SAP customizing
- The sidebar elements are stored in the Metadata repository too
For details about the different options available for the supported workflows, refer to the Alloy by IBM and SAP in Notes and Domino 8.0.2 information center FAQ page.
Scope of troubleshooting in Alloy (client, server and SAP)
You can see from the architecture diagram in figure 1 that there can be failures at several points, which need to be understood for thorough troubleshoot ing. These failures can be due to the Alloy setup c onfiguration on Lotus Domino or SA P. This document focuses on the troubleshooting and diagnostics on the IBM side.
The WebService communications flow from IBM to SAP for outbound, and from SAP to IBM for inbound. There are different views and logs that can help monitor the status of outbound and inbound flows.
Also, there are configuration settings in the Notes.ini file on both the Notes client and on the Domino server required for proper functioning of the product. These are added by the installer and through the server-side Admin GUI, full details about which are described in Alloy Information Center installation guide topic, which includes a quick checklist about these settings.
Troubleshooting the Notes Client with respect to Alloy
We approach troubleshooting from two a spects, configuration checkpoints and troubleshooting checkpoints. Let’s start with configuration checkpoints.
Plug-in insta llation
Make sure that the correct version of the plug-in responsible for fetching the Metadata from SAP is installed on the Notes client. This plug-in also provides the Alloy side-shelf menu (see figure 2), which you can verify by selecting File > Application > Application Management.
Figure 2. Plug-ins
The required Notes.ini settings are as follows:
1. The path to the Metadata Web Service URL, for example:
To confirm that it’s working, ensure this URL can be successfully invoked from the browser; you should get a screen as shown in figure 3.
Figure 3. Metadata Service Output in browser
2. The Mail-in database path to the server, for example:
$NDERPMID=Mail In Database@tpo
Note that, the above setting is automatically updated in client Notes.ini from the Alloy server configuration. User should never edit this setting directly as it will eventually
be overwritten using the value from Alloy server configuration.
Merged mail8 template design for Mail database
For users to be able to use Alloy functionality from their Notes client, the Admin must merge the mail8.x.ntf template with Nderpmail.ntf (which has Alloy design elements), using the Update mail template utility in Nderpws.nsf.
You can verify that the user has the correct template by selecting File > Application > Properties. Click on the fourth tab of the Database Properties dialog; the template version should reflect the merged template name (see figure 4).
Figure 4. Database properties
You can also confirm the user’s mail file design by opening it in the Designer and manually checking all the related designs of Alloy, to ensure that it’s incorporated into the existing template, as shown in figure 5. That way you can check for any issues with the user’s template.
Figure 5. Example Alloy forms in Designer
Now that we’ve confirmed the configuration checkpoints, let’s move on to the troubleshooting checkpoints.
Trouble shooting checkpoints
Let’s go through some of the useful troubleshooting checkpoints in the Notes client.
Metadata gene ration
The progress of metadata generation on Notes client can be tracked through the progress bar, as shown in figure 6. The progress bar shows the Meta data Web Service calls made and current operations/calls going on the Notes client, along with any interruption or failure therein.
Figure 6. Progress bar during metadata fetching
Client logs and traces can also help us understand a problem (see figure 7).
Figure 7. Client logs
L ocal Metadata da tabase
This database is the backbone of Alloy; without it, the product’s functionalities would not be available to users. Make sure the Local Metadata database was created in the Notes \Data directory and has all the proper entries.
You can always check for the existence of the database in the above mentioned path (see figure 8).
Figure 8. Local Metadata db path
To deter users from meddling in this database, all its views are hidden; however, you can still see them by doing the following:
1. Right-click on the database icon in the workspace and press Ctrl + Shift at the same time.
2. Select Application > Go To; you can now see all the hidden views (see figure 9).
3. Select any view, click OK, and that view will open.
Figure 9. Hidden views of Metadata database
If you open the All Documents by Scenario view, for example, it would typically look like that shown in figure 10.
Figure 10. Data inside one of the views of Metadata db
The metadata is created based on the Roles (to be covered in the server-side section below) assigned to the user on the server side. So this will be useful information for checking whether the user has proper data populated in the Metadata database.
Menus for Alloy
Now that we’ve confirmed that the Metadata was fetched properly, let’s proceed to the next checkpoint. The plug-ins should add three items under the Create menu of the Notes client (see figure 11), so that users can access all the applications/Roles configured for them.
Figure 11. Alloy menu items in Notes client
Opening any one of these should open the respective form; for example, figure 12 shows a Leave Request form.
Figure 12. Leave Request form
In some cas es, you may get a Notes error such as the following:
“An error occurred while retrieving the information needed for this request”
when clicking one of the menu items.
The error means that, although the menus got created per the Roles specified on the server side, there were some issues fetching the complete set of metadata. So, you need to check where it went wrong with the help of available data.
Client log/trace from menu
Any error logged in the Notes client can be viewed using Help > Support > View Log / View Trace. It is always helpful for troubleshooting to check the path where the Notes client stores the Log files (%NotesHome%\data\workspace\logs ). Figure 13 shows an example trace log.
Figure 13. Client Trace Viewer
This Log/Trace viewer is always helpful in determining issues related to the Notes Client.
You can always increase the logging level to get more granular information in the logs. Logging levels can be set to SEVERE, WARNING, FINE, FINER, FINEST, or INFO (default). Here is the path where you can set it:
- n otes\data\workspace\.con fig\rcpinstall.properties
- -com.ibm.n derp.level=FINEST
Note that, FINEST is the most verbose level and thus should be used with caution, as it will increase the size of the generated log. It is recommended to use this level only for short period
of time for troubleshooting and later revert back to INFO.
Troubleshooting Lotus Domino with respect to Alloy
Alloy’s main server-side component is the NDERP Web Services (NDERPws.nsf) database. It hosts Domino Web Services for inbound communication from SAP and also acts as a Web Service consumer for outbound communication with SAP. The server configuration details can also be viewed from this database.
SAP J2EE URL. All Alloy-related server configuration is done in NDERPws.nsf. The Admin must edit/confirm that the SAP J2EE server address field is set correctly in the Server Configuration document (see figure 14).
SAP Name Mapping. Each Alloy administrator and user's IBM Lotus Notes user name be mapped to a valid SAP user ID. For each Notes user, name mapping is performed in the user's Person document in the Domino Directory application on the Alloy server. You can use the sap=sapid mapping convention in either the User name field or the Short name field. Alternatively, you can use the SAP user ID without the sap= prefix if you specify it as the first entry in either the Short name filed or any Person document form field that you so designate.
Figure 14. Alloy Server Configuration document
The other settings (for example, SAML, SLD Registration) are all explained in detail in the Installation Guide on the Alloy by IBM and SAP Support page.
If the Web Services communication between Domino and SAP shows any errors, the first Admin-side check is to confirm that the URL mentioned above is reachable.
Applications and Roles
Applications and Roles management is supported in the NDERPws database (see figures 15 and 16). If a user is not able to see menu options enabled for Alloy in the Notes Client, this is one place to check. The menu options are controlled by the Roles assigned to the user, s o a missing menu can be result of a missing role. In that case, the SAP Enterprise Resource Planning (ERP) application needs to assign the appropriate roles, and the Alloy Admin needs to invoke actions like New Application, Create/Update Roles to sync up with SAP.
Figure 15. Alloy Applications view
Figure 16. Alloy Roles/by Role Name view
The Roles view can be used to identify what roles have been assigned to a user and, accordingly, check that the data has been fetched on the client side.
Below are some of the Notes.ini settings required on the Domino server side:
- AMgr_UntriggeredMailInterval=1 (#Tuning of Request Handler agent to process outbound requests)
- JavaMaxHeapSize=512MB (#For more details refer to Alloy Administration Guide)
SAP ID and Mail ID mapping in Names.nsf
SAP does not keep any reference for a Notes User identity; instead, IBM maps the SAP user identity (SAPID) to the Notes User ID. This mapping is done in the Domino Names.nsf database (see figure 17).
Figure 17. SAP Id mapping in Names.nsf
If Outbound or Inbound communication starts failing with messages like “User cannot be mapped to SAP ID,” the place to look is in Names.nsf.Refer to figure 14, SAP Name mapping
details for checking the convention followed for mapping Notes User ID and SAP ID.
NDERPws.nsf has the views Outbound Requests > Unprocessed/Processed/Suspended/All, which are used for outbound processing.
When a Notes Client user submits a request, it lands in the Unprocessed queue. When processed by the Outbound component and a successful Web Service call is made to SAP, the request is moved to the Processed queue.
In the case of any failure, a fixed set of retries are attempted. If the request still fails, it is moved to the Suspended queue (see figure 18). An Admin can check the Suspended queue and re-try if necessary.
Figure 18. Request in a Suspended queue
Inbound processing failure points
- Inbound processing is initiated by SAP. If after successful processing of a request through the Outbound Web Service, the expected Inbound (Mail, Report, Approval, etc.) is not delivered to the user’s mail file in a reasonable amount of time, it could mean there is a failure in Inbound processing.
- If the Inbound was not initiated by SAP at all, then IBM side will not have any awareness of it (success or failure).
- If the Inbound was initiated by SAP and IBM-side Inbound processing has failures, then Domino’s Log.nsf will show the exception.
- If an Inbound message was handled correctly by Inbound processing, it will show up in the Business Objects view in NDERPws.nsf (see figure 19). In that case, there could be a failure in sending to the user’s Mail.box, so you need to check the server’s Mail.box or router logs.
Figure 19. Alloy Inbound Business Objects view
As mentioned above, the default logging level is INFO. To reproduce any issue in greater detail, you can change it to a finer level and restart Lotus Domino. Other possible levels are SEVERE, WARNING, FINE, FINER, and FIN EST:
- com.ibm.nderp.level = FINEST
Note that, FINEST is the most verbose level and thus should be used with caution, as it will increase the size of the generated log. It is recommended to use this level only for short period of
time for troubleshooting and later revert back to INFO.
Log.nsf, console log
With the logging level set to the appropriate granularity, the Admin can check Domino’s Log.nsf or console for exceptions, error messages, etc.
Some troubleshooting FAQs
Below are some common issues and some tips for resolving them.
- Some Alloy actions are missing from the Create menu, for example, Leave Request and Report from Catalog (see figure 20).
Figure 20. Alloy menu with only Trip Request
Check the Roles assig ned to this user in NDERPWS. The REMAUser and LEMAUser Roles may be missing.
- User does not see any actions from the Create menu.
Check for the following:
1. No local Metadata is present or
2. Roles are missing in NDERPWS or
3. Client call is not going through.
- The Local Metadata databas e is deleted by mistake.
Restart the Notes client; the jobs in the plug-in will create a new Local Metadata database and will synchron ize all metadata from server to client.
- User did not get metadata in the Notes Client.
On the client:
1. Make sure the Notes.ini entries are correct.
2. Check if Metadata service (NderpwsURL) is working from browser; for example, http://188.8.131.52/NDerpws.nsf/MetaDataService?openwebservice
3. Also, check client trace/log.
On the Domino server:
1. Check that the SAP J2EE URL is working; for example, http://sapj2eedev.notesdev.ibm.com:50200/
2. Check if Reporting Metadata, Roles are present on NDERPW S for the user.
3. If all this is fine, wait for next refresh; or on the client, delete the local Metadata database and restart the client, which triggers refresh of Metadata.
4. As a last option, on the Domino server, do a Clear Catalog; and on the client, delete the Local Metadata db and restart the client.
- How do you confirm that the request is out of Notes/Domino and waiting for an SAP response?
This is an important aspect of troubleshooting as this can help identify exactly where the issue is. We can check two things here:
1. Once you submit a request from the Notes client and it has reached the NDERPws.nsf Outbound queue (Unprocessed), it means the Notes client has done its job and now the request is available to the server.
The request will fail at the Client level only if there is a configuration issue. Usually, if the metadata is fetched properly, then there is less chance that the request will fail on the client side. Most client issues are related to metadata fetch, but there are some other factors that must be considered (mentioned in the Client section above).
2. Now the NDERPws.nsf processes the request and puts it into the Processed queue, meaning that the request i s now out of Lotus Domino and is delivered to SAP. You can also monitor the server console as i t logs the successful transaction of the request, indicating the request has left the Domino server.
Until we get the Inbound response, we can assume the request is sent to SAP and that Lotus Domino is waiting for the response. Once SAP invokes the Inbound response and it’ s processed by Lotus Domino, you can see it in the Business Objects view of the NDERPws.nsf. This is applicable to almost all the scenarios supported in All oy 1.0 release.
As far as the troubleshooting process is concerned, it should always be a step-by-step approach, and you should concentrate on taking the right path rather than hurrying for a solution. In the case of Alloy by IBM and SAP, you must determine whether the issue is on the client side, server side, or SAP side and, using this document, you should be able to get on the right track toward a solution.
- IBM Support Technote, “Domino 8.0.2 and Notes 8.0.2 system requirements for Alloy v.1.0”:
- developerWorks article, “Performance report: Alloy by IBM and SAP 1.0”:
http://www.ibm.c om/developer works/lotus/library/alloy-performance
- Browse and search all Alloy Technotes:
- IBM Software Support RSS feeds:
- Alloy articles in the Notes and Domino wiki:
- Alloy content in the Not es and Domino information center:
- Alloy demo, “Optimizing decision making and improving productivity”:
- Alloy product page:
- Report Alloy issues to Support:
About the authors
Shrikant Veeturi is a Systems Software Engineer with IBM in Pune, India, currently working on the joint Alloy by IBM and SAP project.
Amita A. Va dhavkar is a Senior Staff Software Engineer with IBM in Pune, India. She currently works on the joint Alloy by IBM and SAP project.