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 highlevel presentation of Alloy by IBM and SAP architecture and troubleshooting FAQs. ...

Abstract: Alloy™ by IBM® and SAP 1.0 (hereafter called Alloy) brings SAP data directly into a user’s IBM Lotus® Notes® client, using Lotus Domino® Web services and displaying it a proper Notes UI document. Alloy relies on the Local Metadata database to do this, and this article explains how the database is created and how to confirm that the fetch from SAP is successful. Contents1 Introduction 2 Understanding the Alloy Metadata database 3 Client/server requirements for the Metadata fetch 3.1 Notes client-side requirements 3.2 Domino server-side requirements (Admin specific) 4 Initiating a call to fetch Alloy metadata from a Notes client 5 Verifying the Alloy metadata fetch was successful 6 Conclusion 7 References 8 About the author

1 IntroductionAlloy 1.0 is all about bringing SAP Software to IBM® Lotus® Notes®, whereby an Alloy user is able to perform the supported SAP functionalities from inside the Lotus Notes inbox. Alloy uses Web services to communicate between IBM Lotus Domino® and SAP, providing business users with easy access to key enterprise processes and information like Leave Management, Travel Management, Reports Management, and Workflow Decision Management.

The Notes client of an Alloy user has the SAP configuration downloaded locally during the Notes Client Alloy setup process. This data is stored in the Metadata repository, which plays a key role in Alloy’s functionality.

This article explains how an Alloy administrator or user can confirm whether the Metadata repository is created successfully in the Lotus Notes data folder. Lotus Notes users / Domino administrators of Alloy should find it useful, as Local Metadata is one of the key databases in Alloy, and any issues involved while fetching prevents the use of Alloy functionalities.

Note that we assume the Alloy setup has been completed according to the Alloy Admin guide. Although this article covers some of the points related to setup, they are specific to Metadata and are not detailed. Visit the IBM Lotus Domino and Notes Information Center for more information on deployment and setup of Alloy. 2 Overview of the Alloy Metadata databaseThe Alloy Metadata database is a repository of SAP configurations (for example, Leave Types or Report Template) that are provided to the user. It has information about users’ roles and relevant information for Leave, Trip, and Reporting. Sidebar elements, such as related reports, are also stored in the Metadata repository. This database is created when the Alloy user logs into the Notes client for the first time.

To see how the Metadata database fits in, let’s look at the architecture of Alloy (see figure 1). Figure 1. Alloy architecture You can see that the Alloy Metadata database (outlined in red) resides in the Notes client data folder. For example, if the domain name is “Peaks” for the user Duke Lawson, then the user’s
Metadata database would be called “NDERPMDDukeLawsonPeaks.nsf”. see figure 2 for the same.

Figure 2. Path of the Local Metadata database

If you attempt to open the database, only the About the NDERP Metadata database page will display because the views are hidden. You can, however, open the database by creating a workspace icon for it, right-clicking it while pressing Ctrl + Shift, and selecting Application > Go To.

All the hidden views should then be listed (see figure 3), and when you select any view and click OK, that view will open. Figure 3. Hidden views of Metadata database You can choose any of the above views to see its corresponding data. The All Documents by Scenario view holds all the combined data applicable to that particular user, as shown in figure 4. Figure 4. All Documents by Scenario view data 3 Client/server requirements for the Metadata fetch Assuming you’ve already set up an Alloy server, let’s now discuss the components on both the Notes client and Domino server sides that are necessary for fetching /creating the metadata.

Most of the components below are generic and are used for performing other Alloy tasks as well.

3.1 Notes client-side requirementsInstall the Alloy Eclipse plug-ins :You can install the plug-in to the existing Notes client using the supplied add-on installer. This plug-in forces the calls to fetch the metadata from SAP via the Domino server and put it into the Notes Local Metadata database. Refer to the IBM Lotus Domino and Notes Information Center for more information on installing the Alloy plug-ins.

Update the user’s Notes.ini file :Fetching the metadata is done via a Web services call to the Domino server. The Alloy client requires the Notes.ini setting:

where the http address matches the Web services application name and address specified in the server’s Domino Directory (Names.nsf) Person document for that user.

You can always open this in a browser, to confirm whether it’s working or not; Figure 5 shows successful execution of the URL.

Figure 5. Output of Metadatawebservice in a browser For more information on the Notes.ini configuration, see the IBM Lotus Domino and Notes Information Center. 3.2 Domino server-side requirements (Admin specific)In an Alloy server -side setup there are several items that are important for metadata fetching:

NderpWs.nsf (the Web services database). The Web services application (NDERPws.nsf) resides on the Alloy server and acts as a routing intermediary for requests and responses between the SAP system and the user’s Alloy client interface. This database holds the Domino Web services required for the inbounds from SAP (BoundItemService) and metadata calls from the Notes client (MetaData Service).

It’s important to specify the entry of the SAP J2EE application server URL in the Nderpws.nsf configuration as the Metadata Service contacts this URL to call the Web services.

4 Initiating a call to fetch Alloy metadata from a Notes clientNow we can discuss how the metadata is fetched. Let’s assume that User A, who is an Alloy user, has launched and logged into the Notes client. As soon as the user logs in, the Alloy plug-ins are loaded and invoke the MetadataService Web services calls, using the Web service URL from the Notes.ini:

1. The first call that’s made is to get roles assigned to this user. These roles are maintained in the Domino server and would have been populated as part of the Alloy setup. Currently for Alloy 1.0 there are two roles each assigned for LEMA and TRVL, and one role for REMA (see table 1).

Table 1. Roles and scenarios

Applications (scenarios)

Roles assigned

Leave Management (LEMA)

User, Manager

Trip Management (TRVL)

User, Manager

Reporting Management (REMA)

User

2. The rest of the metadata Web service calls are initiated based on the roles retrieved. Assuming that the user has all the above five roles assigned, the metadata related to all the five roles should be fetched. For any role that is not assigned to the user, no metadata calls are made for that particular role/application.

Figure 7 shows some of the calls made by the plug-in to fetch the metadata, which can be seen in the progress bar of the Notes client. (All the different calls are presented collectively in the graphic.)

Figure 7. Progress bar in Notes client fetching the local metadata 3. The progress bar informs the user about the operation that is in process. Once the Web services call is made from the client, the Domino server contacts the SAP Web services exposed for the metadata fetch. These Web services calls can be synchronous or asynchronous.

For example, Leave Management and Trip Management metadata calls are synchronous, and the data is returned as a response to the Web services call. Reporting Metadata calls, on the other hand, are asynchronous, with SAP sending the Report Templates at a later time as separate inbound requests.

4. When the progress bar finishes with “No operations to display at this time” (see figure 7 above), it means there are no remaining operations from the client side, and all the Web services calls have completed. So either the metadata has been fetched completely or, if an error comes up, it will be logged into the Notes client log, which can be seen via Help > Support > View Trace / View Log. You can check the Domino server logs as well for any exceptions or failures.

Now let’s confirm whether the metadata was successfully fetched. 5 Verifying the Alloy metadata fetch was successfulOnce the progress bar finishes, open your mail file and confirm that the Create menu contains the items for LEMA, REMA, and TRIP, and that selecting each one opens the corresponding form / report catalog.

Figure 8. Alloy items under the user’s Create menu If you select Leave Request, you should see the form shown in figure 9.

Figure 9. Leave Request form

Selecting Trip Request should display the form in figure 10.

Figure 10. Trip Request form

And selecting Report from Catalog should display the Report Catalog in figure 11.

Figure 11. Report Catalog If you see all the above figures, then the metadata fetch was successful. If you select an item and it doesn’t open, an error will display, in which case you can try to re-fetch it by restarting the Notes client, or you can contact the Admin.

The other way of verifying a metadata fetch is by opening the Metadata database locally and confirming that the values F4Help, Leave Request, Related Reports, Report Template Request, RolesRequest, Trip, and (Not Categorized) are populated (see figure 12).

Figure 12. Successfully fetched All Documents by Scenario view NOTE: In the event of errors, you can check the Notes client logs and Domino server logs as well for further troubleshooting. For example, if you select Create > Leave Request and you get a Notes error such as:

“An error occurred while retrieving the information needed for this request.”

it means that the metadata was not fetched properly, in which case you can retry or contact the Admin for further troubleshooting help. 6 ConclusionIn general, to ensure a successful metadata fetch, you must make sure that all the elements related to the process are properly configured and installed. This article has outlined these metadata-specific elements on both the client and server side, explaining how those elements are properly configured and working. The Metadata database is an integral part of Alloy for IBM and SAP, and ensuring a successful metadata fetch is key to the smooth running of the product.

About the authorShrikant Veeturi is a Systems Soft
ware engineer with IBM in Pune, India, and currently works on the joint Alloy by IBM and SAP project. He has approximately 3.5 years of IT experience.