So you want to roll out Duet
This page talks about installing the Duet 1.5 client software, the tools involved and what to do if things don't work out as expected.
In addition to the information mentioned here, please also take a look at this blog where other potential issues with a SP3 installation are listed.
The installation script
You can still use the steps and script mentioned below as a template for the intsallation. However, with SP3 the setup.exe should do all that for you. There are two new parameters that can be used when calling setup.exe:
Like mentioned here, you can run setup.exe /InstPreReq first in order to get your client up to date for Duet. The logs of this installation will be written to the clients %temp%\DuetSetup.log file from where you can see what might be missing on the client. Once everything is OK, you could run setup.exe again (this time without parameters) and Duet -- with the CCD -- will be installed.
In order to install Duet, I recommend using the sample install script which is available at https://connect.microsoft.com/content/content.aspx?ContentID=12633&SiteID=426 . It takes care about a lot of prerequisites that need to be in place or installed. You can also modify it to your organization's needs. When you run it, it will log all of its actions into a logfile, so if the installation does fail it will tell you why. Note the log location(s) in the script, by default it will write logs to the c:\temp\duet directory:
Once Duet is installed, and the actual Duet end-user logs on to the PC or laptop, Duet starts up for the first time and tries to initialize. Let's have a closer look at the crucial sequence of events that happen and the components involved.
The Duet Utility
The Duet Utility is an application that the Duet client setup program installs and which runs in the background under the currently logged on user's identity. It provides the synchronization status to the user, notifies the user about relevant events and allows the user to monitor error conditions. This application is used for the initial deployment, and for hosting various components that are necessary for the Duet client components to function. The process for the application is automatically started when a user logs on to the computer and is terminated when the user logs out. When a user is logged on, an icon representing the Duet Utility appears in the notification area, which is at the far right of the taskbar.
The initial deployment
When the Duet Utility is run for the first time the so called initial deployment is started which does a one time Duet client configuration. The most important steps performed in this initial client deployment are
- calling the Microsoft Duet ReadService URL in order to download metadata. Part of this metadata is the URL for the so called TicketIssuer.
- calling the SAP TicketIssuer component; this component returns a so called SAPLogonTicket which is used for all subsequent calls to the Duet server and is the means by which Single-Sign-On is achieved in your duet landscape.
- calling the SAP ServiceMapper
- calling the SAP ServiceProvider
- calling the deployed Duet applications' so called "cached calls". Those retrieve the initial set of business data for the Duet applications to work with.
- Exchange Account Configuration; Create hidden folder, Create Exchange Rules, Create Configuration Messages in the mailbox
Ideally, this is how it looks like:
In order for these initial deployment steps to work out in that order, several things need to be configured and working properly. The two most crucial components are the Microsoft Duet ReadService and the SAP TicketIssuer.
The job of the ReadService is to return the metadata for those Duet applications that the user is allowed to work with. In order for this to happen, this user must be at least assigned to the so called Scope SAP.Office.Framework in the Authorization Manager (AZMan). In order for this to be the case, verify that the user is assigned to the relevant Duet applications' groups in the User Management Engine of your SAP Duet server J2EE. Additionally, a synchronization between those groups and AZMan must have happened using the Duet server side functionality "Copy to AZMan Service". You can verify if your users was successfuly added to the scope in AzMan by opening the CachedAuthStore.xml file (usually in C:\Inetpub\DuetAzManService\Logs) via the AzMan.msc console on the Duet server.
Part of the metadata that the ReadService downloads to the client is the URL to the TicketIssuer component. The TicketIssuer can be seen as the gateway to your SAP systems (which were configured to trust the Duet server when the certificates got exchanged during setup) since it issues a SAPLogonTicket http://help.sap.com/saphelp_nw04/helpdata/en/a0/88a340fa432b54e10000000a1550b0/frameset.htm. In order for this to happen, you need to configure SSO via SPNego in your Duet landscape as described in the Duet documentation as well as in this excellent Blog by Holger https://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/8235. When I say gateway I mean that if the TicketIssuer for some reason does not return a SAPLogonTicket, all subsequent calls will fail and initial deployment can not finish successfully. Apart from a SPNEGO landscape configuration, there are a couple of things which need to be in place on the PC or laptop in order to receive a SAPLogonTicket from the TicketIssuer.
- Windows Integrated Authentication needs to be enabled in the Web browser
- Automatic logon in Intranet zone needs to be enabled in the Web browser
- The DNS host name of the SAP Duet Server J2EE needs to be added to the list of local intranet sites
Here's how to do that http://help.sap.com/saphelp_nw70/helpdata/en/43/49a2aefd975f89e10000000a1553f6/frameset.htm or again, a blog by Holger https://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/8243. The second thing that needs to be ensured is that time difference between the Client and the Server is not too big (there is a default time difference for Kerberos which is usually about 5 minutes).
So let's say the ReadService call was successful and the subsequent TicketIssuer call as well. Next in line are various calls to the SAP Duet server J2EE Engine in order to get a list of URLs for all the Duet applications which should run on this client. Those URLs tell the Duet client runtime how to get data from the SAP system and how to write data back to the SAP systems. For each of those calls, the SAPLogonTicket is used for authentication purposes. In the initial deployment step, some of the URLs are called to fetch application data which is then stored locally on your Duet client. In case of Duet Sales Management, those URLs are called in order to trigger the download of sales accounts, sales contacts and sales activities to the Duet client.
Last but not least, the user's exchange account configuration takes place, and the so called "deployment stage" of this Duet Client is set to "Finished". The Office Outlook add-in will not load if the Duet Client deployment is not successful and the deployment stage is not finished.
Client side tools
By now, you probably figured out that there are a lot of dependencies between various components and configurations. If one of those components fails to do its job, the Duet deployment will not succeed and hence Duet will not be usable on the PC or laptop you are installing on.
There is a way to make sure that your initial Duet client deployment will work out before you do the actual installation. Using the Client Central Diagnostics (CCD) tool you can run various tests to diagnose, check, and track possible problems in clients. The CCD helps you to diagnose general issues: whether a client is capable of running Duet, the status of Duet services, the status of cached content for Duet and more. The CCD is composed of two parts:
- Client component: performs various checks and analysis on the client, and generates a file consisting of its results for use in the server component
- Server component: available in the Duet host, it schedules and activates tests for one or several clients. In addition, it collects and presents the results of a test to help you to provide support for one or several users.
When you deploy Duet, the CCD server component is automatically installed. You must install the CCD client component on each client you want to diagnose (this is done automatically if you use the sample script mentioned above). The client part of CCD mainly consists of the SAP Duet Client Support Tool which is able to execute tests and report on the test status. So the same tests that the support tool executes when you choose "Landscape", it executes as part of the CCD and reports the results back to the server.
Currently (18.06.2009, Duet 1.5 SP2) there are 23 tests which fall into 4 categories
- Client Business Status
- Client Technical Status
- Prerequisite Tests
- Server Connectivity
Let's look at the Server Connectivity category. We will find some familiar names in there, basically those are the services consumed by the Duet Utility for the initial deployment as seen before:
- Microsoft Duet Read Service
- Service Mapper
- Service Provider
Ideally, when you execute the tests for Server Connectivity, this is how it looks like:
Unfortunately, this is not always the case, and as we've seen before there are various reasons why one or more of those tests could fail.
Reasons for the Microsoft Duet Read Service to fail
- there could be a general problem authenticating users on the IIS server, see if SAP note https://service.sap.com/sap/support/notes/954806 applies
- the user is not assigned to the scope SAP.Office.Framework in the Authorization Manager (AZMan)
- the user is not assigned to the relevant Duet applications' groups in the User Management Engine of your SAP Duet server J2EE
- a synchronization between those groups and AZMan has not happened using the Duet server side functionality "Copy to AZMan Service"
- the user is not assigned to the relevant Duet applications' groups in the User Management Engine of your SAP Duet server J2EE
If the ReadService test fails, you will most probably see all other Server Connectivity tests fail as well. So even though you have 5 failed tests, they all come down to the root cause of the failing ReadService call.
Reasons for the SAP TicketIssuer to fail
- SPNEGO has not been configured correctly in your Duet landscape; for configuration and troubleshooting see
- Windows Integrated Authentication and Automatic logon in Intranet zone and are not enabled in the Web browser
- The DNS host name of the SAP Duet Server J2EE is not part of the local intranet sites in your web browser
- the time difference between the client and the server is too big; there is a dedicated test support tool test for that as well
If the TicketIssuer test fails, you will most probably see all other Server Connectivity tests fail as well. So even though you have 5 failed tests, they all come down to the root cause of the failing TicketIssuer call, since the SAPLogonTicket produced by the TicketIssuer is needed for subsequent calls.
Reasons for cached calls to fail
Not only technical calls like the TicketIssuer or the ReadService can fail; for initial deployment also the applications' cached calls might have problems due to
- Timeouts; the corresponding processing on the server (J2EE and SAP backend) takes too long.
- connectivity errors between the client and the server, like the Duet client cannot resolve the hostname of the duet Server
- failures on the Duet Server J2EE which are general runtime errors due to bugs
The applications' cached calls are not tested by the Client support Tool / CCD; those are only executed by the Duet Utility. As said before, failing cached calls also lead to an unsuccesful initial deployment of Duet.
Which tests will be RED in case initial deployment has not succeeded yet
The following 2 tests will fail and have a RED status if your Duet client has not gone through a succesful initial deployment:
- Client's deployment stage, tha value will not be equal to 7 (which is the status for finished)
- Verify Mandatory Control Message exists; as the Exchange Account setup has not been done yet
Where to find logfiles
All client side Duet related logfiles can be found in the %temp% directory.
With Duet 1.5 SP2, the Client Central Diagnostics (CCD) tool has a new feature which automatically collects these logfiles, zips them and copies them to a central server share. See the corresponding section in this article for details.
Server side tools
Duet Administration UI
From the Duet Administration UI, you can view and monitor the statuses of Duet components from SAP including Duet clients activities. The Dashboard in the Duet Administration tool complements the information in the log files and provides a central point from which you visually obtain summarized information of the identified problems in the Duet landscape. The Dashboard shows the date of the status of the components and provides notices if any errors occurred during configuration of the components. In addition, it contains panes that display indicators and status information in the Duet environment, like the Users Monitoring.
From the Users Monitoring pane, you can monitor the status of Duet clients for a single user or a group of users. You can search for a single user or display groups of user which share the same criteria. One important thing to notice is that if you search for a single user here, and you get a message which says " User <username> is not Duet user ", that means that for this user, no duet client has been successfully set up yet. Or, in other words, the initial deployment of a Duet client has not yet worked out for this user in this Duet landscape. Maybe a Duet installation has never been attempted for this user, maybe a Duet installation has been attempted, but failed before the Duet Utility could successfully call the ServiceProvider. Only a complete initial deployment of the user's client will make him an active Duet user and hence visible in the Duet Administration UI.
If you navigate into the details of such a Duet user, you can see this user's Duet client interaction with the Duet Server on the "Web Services" tab. The UI differentiates between CRUD calls and other calls. CRUD (Create, Read, Update and Delete) services are triggered whenever a business object on the Duet client changes. That happens when the end-user creates, updates or deletes an item. The CRUD services are handled one after the other. If one fails, others wait on the client until it succeeds.
The table behind has two types of client web-service calls; cached on the client and online. Cached calls are not triggered by the user directly but periodically called by Duet applications. The server response is cached on the client. Online calls are usually triggered when a user clicks a button, link etc. The request is processed on the Duet Server and then returns to the client.
This picture shows a Duet client which successfully called all cached and online calls:
This picture shows a Duet client which ran into problems when calling two cached calls for Duet Sales Management:
Note the "Advanced Info" button in the header line of this table. Clicking this button gives you a more detailed and technical explanation why this call failed. Typical problems in this case are
- connectivity issues between the SAP Duet Server J2EE Engine and the corresponding SAP backend system (ERP, CRM,...)
- Single-Sign-On errors
- the user is locked in the SAP system
- shortdumps in the SAP system
- runtime errors on the SAP Duet Server J2EE engine
In a case like the one depicted here where cached calls fail for a user, the initial deployment of a Duet client for this user would not finish successfully.
Client Central Diagnostics
- work in progress