Getting started with IBM Lotus Notes and Domino and Alloy 1.0 by IBM and SAP
Introduction
This article is intended to be a reference for Administrators and Developers new to IBM Lotus Notes and Domino and Alloy 1.0 by IBM and SAP. There is a wealth of information available for audiences with a range of experience with both SAP and Domino, but a noticeable lack of cohesion with regard to starting with a SAP/Alloy environment, installing and configuring a Domino server, installing and configuring the Alloy server, installing Alloy clients, and doing basic work-flow customization for exposing SAP objects in a Notes client. Individual pieces of this are available, but there are gaps and a lack of very basic knowledge necessary for folks new to Notes and Domino. This document is an attempt to address that, and provide one location for administrators looking for the variety of information available. This will be a working document, and will be updated periodically with more information to fill gaps as new content is created.
What is Alloy by IBM and SAP?
Alloy 1.0 by IBM and SAP was released in February, 2009. Its development and release was predicated on the belief that traditional business users need a seamless interface to back-end SAP information without leaving the comfort of the productivity tools (mail inbox, calendar, document management) they use to complete their day-to-day activities. Alloy provides these users with access to SAP information from within a Lotus Notes client, which minimizes training needs for the millions of users already familiar with Notes, and improves the productivity and decision-making ability of workers who do not traditionally use a SAP GUI or Portal.
For more marketing information, please see the Alloy Solution Briefing and a SAP Insider article about "How to Increase the E.R.P (Effectiveness, Responsiveness, and Productivity) of Your Business Users", both of which (and more) can be found on the Alloy product website.
To understand how SAP/Alloy/Domino/Notes interact, let's take a look at a high-level Alloy architecture diagram.
Figure 1: Basic Alloy Architecture
As you can see, there is an Alloy component that sits on top of all 3 main layers: the SAP NetWeaver and Domino servers, and the Notes Client. The basic workflow, from an end-user perspective, is this:
- User initiates Travel or Leave request (or other, customized request)
- The request is sent to the Domino Alloy Server as an XML stream. The user authenticates with Domino with the Notes User ID
- The Domino Alloy server sees that this is an Alloy request, and uses SAML (Secure Authentication Markup Language) to request a SAP logon ticket from the SAP Alloy Add-On software . The SAML request includes the SAP user id associated with the Notes ID, along with a unique source id and artifact information. The SAP user id is retrieved from the user's Person document in the Domino Directory
- The SAP Alloy Add-On passes back the logon ticket which allows the Domino Alloy server to only need to authenticate o nce per individual user request. All future WebServices calls between Domino/SAP pertaining to thi s request will automatically authenticate with the credentials provided previously
- Based on the SAP Workflow, an Approval request is generated, and routed to the proper resource for Approval/Rejection. Domino uses standard replication to route Approval requests. That user authenticates in a similar fashion when sending back their decision, all handled via WebServices
- Alloy updates the SAP business objects based on the outcome, and the end-user is notified of the decision
This article will focus on how to set up the environment shown in the 3 yellow boxes above.
Education offerings for Notes/Domino There are a number of courses provided by IBM (and others) to help get new Notes/Domino administrators and users off the ground. For a complete list of education offerings from IBM, please refer to:
Education Offerings on IBM Lotus Notes Domino 8/8.5 In particular, new Domino Administrators should benefit from D8900 - IBM Lotus Domino 8 System Administration Bootcamp and D8770 - Managing IBM Lotus Domino 8 Servers and Users. These two courses contain the fundamental skills Administrators will need to manage an Alloy environment.
New end-users will most benefit from N8010 - IBM Lotus Notes 8 Mail and Calendars Parts 1&2.
Application Developers wishing to learn the IBM Lotus Domino Designer client will benefit from D8510 - Fundamentals of IBM Lotus Domino 8 Application Development. This should give developers the foundation they need to become familiar with the Domino Designer client, and modify the Domino mail template to customize Alloy work-flows.
If you are not able to take any of the courses available, there is a significant amount of 'Learning Notes and Domino' material available for free. A great resource to begin learning Domino is found here:
Learning Domino for Administrators Here is a link to a wealth of Notes client learning materials:
Learning Lotus Notes clients Finally, here are a number of learning roadmaps available for the Domino Designer, based on what type of applications you wish to develop:
Learning Domino Designer
Installing Domino As I mentioned in the introduction, this article will assume that there is a working SAP environment, and that the reader is focused on the Domino/Alloy requirements. Alloy 1.0 is currently only supported on Domino 8.0.2 servers running on a supported Windows operating system. Given these prerequisites, there is a very good 'cookbook' for deploying a Domino server available through our developerWorks website. This should be used as the first reference for establishing your Domino environment. It can be found here:
Deploying the IBM Lotus Domino server: A Cookbook
The Cookbook describes 3 different types of Domin
o server that are available to install, and goes on to describe the installation of the Domino Enterprise Server. This is the same type you will want to install for your Alloy server.
Once this is complete, you will have a basic, working Domino server. As is, it will function just fine as a mail or application host. To make it more useful, you will need to add users, configure Notes clients, establish other services, etc. These are normal Domino administration tasks that help create a more robust Domino environment. Full scope of what you can do with Domino administration is beyond what this document can cover. In addition, further, very advanced configuration is required once the Alloy component is installed. It is recommended that anyone not familiar with Domino who wishes to deploy Alloy should explore the education offerings available, or spend a significant amount of time reading the material found on the learning roadmaps linked above.
Installing Alloy
The
Alloy installation guide found in the Domino Information Center is a great resource. The basic steps that need to be taken are:
- Installation of the Alloy code on top of the Domino server
- Creation and configuration of administrative users for both SAP workflow and application management
- Modification of master mail template to include Alloy design elements
- Creation and configuration of the Web services application (NDERPws.nsf)
- Configuring the default workflow applications and the roles required for each
- Configuration of security, internet port settings, and SSL
- Mapping of Notes user IDs to SAP user IDs
One detail to note here: while setting this up, you will need to enable HTTPS on the Domino server. This will require requesting trusted certificates from a Certificate Authority. These certificates will need to be stored on both the Domino Alloy server, and the SAP NetWeaver J2EE server. The public CA certificates from both Domino and SAP servers need to be added to the Java trust keyfile found at $DOMINO_DIR\jvm\lib\security\cacerts.
There may be additional types of configuration required, such as any additional internet, firewall, or Notes domain certificates that may be necessary for communication between servers. These are environment dependent, and will vary based on the infrastructure in which you are setting up your Alloy servers.
There has also been a new article written and posted to the Lotus Domino/Alloy Wiki showing best practices and tips for deployment of a Domino Alloy server. Please review this article for additional information on some of the steps listed above, and tips for successfully deploying:
Alloy by IBM and SAP: Best practices and tips for deployment
A more complete Alloy Server Installation cookbook is beyond the scope of this article, but may be delivered as a separate document in the future.
Installing the Alloy Client
As with the Alloy server component, the
Allo y Client installation guide is a great resource. There are two main methods for installing the Alloy Client software: using the installer that is bundled with the software, or by deploying it via provisioning from a centralized update site for managed Notes clients. For environments with fewer seats, the Alloy installer may be the best solution. For deployments to a larger community, using a Domino-based Alloy Update Site along with the Domino Widget catalog and Domino Policies is most effective. Alternately, the add-on installer can be hosted centrally for users to manually execute if required.
Installing via Alloy Plug-in installer
The plug-in installer can be found either on an Alloy DVD, or in a Webkit downloaded from IBM or SAP. If installing from DVD, copy the client plug-in's install folder (it should be titled 'Alloy_Client_Kit') to your local hard drive. Once there, navigate to the 'deploy' subfolder, and edit the plugin_customization.ini found there. You will need to uncomment the line
#com.ibm.nderp.client/NDERPMDWS_URL=
by removing the '#' from the beginning. Next, update the NDERPMDWS_URL with the URL of the Domino Alloy server's web services application address, which should be something like this:
com.ibm.nderp.client/NDERPMDWS_URL=https://alloyserver.ibm.com/NDERPws.nsf/MetaDataService?openwebservice
Tip: Test this URL in a web browser (make sure the Alloy server is up and running) and log in with a Domino user ID that is mapped to a SAP user ID. You should get a result like this:
Figure 2: Alloy web service output
Once the edit is made to the plugin_customization.ini, make sure the Notes client is shut down, and launch the Alloy installer using the 's
etup.exe', or 'Alloy.msi'.
Click through the Welcome screen:
Figure 3: Welcome screen
- Read and accept the license
Figure 4: License screen
- Click 'Next' on the screen reminding you to make sure Notes is not running
Figure 5: Reminder screen
Click 'Install' to begin the installation
Figure 6: Install screen
This begins the install, and you can watch the progress as the plug-in is deployed
Figure 7: Plug-in installing
Once the install is complete, click 'Finish'
Figure 8: Install Complete screen
At this point, you can restart Notes, and begin using your Alloy client!
Note: If you are installing the Alloy plug-in via the self-extracting executable, you will need to create a temporary plugin_customization.ini to pass as an argumen t to the executable. Please review the installation guide linked above for complete instructions.
Installing via Alloy Update Site and Widget Catalog
The other method of installing the Alloy plug-in is by using a more traditional managed client paradigm. This method uses a number of fairly advanced Domino features, including Policies, NSF-based update sites, and configuration of Widget catalogs. All of these features are too large to cover in an article of this nature, but the steps are documented clearly in the Alloy Installation guide, and helpful Domino Administration links are included as well. I will cover the high-level steps here, and leave it to the reader to review the complete documentation for more detail. &n bsp;
The basic steps for this installation method are:
- Extract the 'updatesite' folder from the Alloy install kit and upload it to an NSF-based update site hosted on a Domino server
- Modify the 'extension.xml' Alloy widget file included with the Alloy server install, and tailor it to the specifics of your environment
- Create a Widget catalog on a Domino server, and create an Alloy deployment widget using the previously modified 'extension.xml'
- Create policies to deploy the Alloy Widget, and to update the notes.ini on the clients where Alloy is to be installed
- Test the policies on a Notes user to ensure everything works properly
- Assign the desired users to the policies in order to deploy when they next start their clients
Customizing Alloy Workflows
The customization of workflows in Alloy is a fairly simple procedure for basic approval workflows. Greater complexity can be added with Status Update workflows, or custom agents to extend and control data elements within the approval messages. These require a greater familiarity with rules of specific item data types in the SAP ERP system, more powerful programming capabilities in the Domino Designer client, and deeper knowledge of Domino architecture. As this article is intended to be used to help administrators and programmers new to Domino, you will need to start with the basics, and that is becoming familiar with the Lotus Domino Designer client. The Designer client is a very powerful programming UI that allows you to create or modify Domino databases (applications), Web-hosted applications, or composite applications which can blend components from various sources and tie them together via 'wires'. The Designer allows you to use a number of different programming methods, including Lotus Notes Formula and LotusScript languages, Java, XML, JSPs and others.
To begin your education on the Domino Designer, the Designer client itself has a comprehensive help system that should be the first place to begin reading. Launch the Domino Designer client, and click the 'Designer help' button on the default Home page that opens.
Figure 9: Domino Designer client
In the Designer help, for the purpose of basic customization of Alloy workflows, focus your attention on the 'Introduction to Domino Designer' chapter under the Application Design' twistie, in particular Database Forms, Subforms, and Fields.
Figure 10: Domino Designer Help
In addition to the product help documentation, there are good resources on the Web to help you along your path to learning the Domino Des igner. Check out the
Domino Designer Wiki, which has a number of links to good reference material. The
Domino Designer 8.5 Information Center is also very valuable. It is updated for the 8.5 version of the Designer client, but the majority of the content applies to the 8.0.2 Designer client as well. A fun way to walk through the basics of the Domino Designer and application development is to take the ancient
Domino Designer QuickStart Tutorial. It is based on Domino Designer 5.0, but a surprising amount is still relevant and is very good for showing steps to create a basic application, and for learning the fundamentals of th e Domino Designer client.
Once you have become more comfortable with the Domino Designer, you are ready to begin simple modification of Alloy approval workflows. There is a very good set of articles describing both the setup of a Material Master workflow from both the SAP and Alloy/Domino side. First, review how to set up the SAP Business Workflow in the article:
How to set up an easy Material Master creation Workflow for Duet or Alloy then, there are two excellent articles on how to modify the Domino approval workflow forms to handle ne
w approval requests using the Material Master objects and workflow. See
Implementing custom workflow decisions in Alloy 1.0 by IBM and SAP and
The one with the customized Alloy workflow UI Both articles describe essentially the same customization steps, but with various levels of detail, and slightly different techniques. Both are very helpful. In the first article, you may notice that the screen shots of the Designer client do not look the same as what you may be seeing in your environment. The Domino Designer 8.5 client was used for that article, so the UI looks a bit different, but the essential steps and content are the same.
The most important thing to take from these articles is the use of the Bound Item Type to specify the new form to use for the approval message, and also to allow a more flexible method of showing workflow-relevant data based on what specific Workflow is being used.
Conclusion
Alloy 1.0 by IBM and SAP ties together two very complex and powerful tools that allow businesses to perform their day to day activities: IBM Lotus Notes/Domino and SAP ERP software. Trying to learn both environments is a monumental effort, and most companies will rely on experts in one or the other to collaborate when joining the two together. This article is intended to be a reference for administrators and developers who may be well versed in SAP ERP, but with little or no experience with IBM Lotus Notes and Domino. It provides helpful links and tips to take the reader from ground zero to having a working, customized Alloy infrastructure in the order of the logical steps needed to get up and running.