A few weeks ago I wrote about my experiences starting out with the Microsoft Exchange Web Services API and on using the subscription API. In the second article, I said I would write a code walk through that shows how to do the stuff. I had thought of doing a complete walk through like the Dynamic OpenClient code that I did back in November last year, but I wasn't as busy back then as I am now, and I had the time to actually write up the example properly.
I also know that a lot of people are very interested in this, based on the comments that I have have in off-line posts and in response to the survey for the OpenEdge client stuff, and I really don't want to neglect those of you that have asked about it. So I'm compromising, and hopefully this will provide enough information for those that care.
This is part 1 of a multi-part series that will cover the process of connecting to Microsoft Exchange Web Services, submitting requests to Exchange, receiving notifications from Exchange, creating appointments, tasks, and e-mail, and using Exchange Impersonation. There will also be OpenEdge examples interspersed within it. Each part in the series will have a downloadable zip file with the code in it that actually runs (at least in my environment).
This post is going to talk about the series of posts and get you set up to start working with it. I am assuming very little, so if you find that things are pretty boring, or you know how to do something, feel free to skip ahead.
In the article that I wrote on the subscription API, I walked through the way that subscription model works. Over the course of this series of articles, we are going to build the Java EWS Web Service and the Java HTTP Servlet.
We'll be running the code on our local workstations so that you don't need a Linux installation.
My interest is in exposing this API to OpenEdge, so I will also be providing some prototype code that shows the OpenEdge EWS API and the ABL Event Handling, although I expect that the majority of Java developers will not really be interested in this.
As my interest is in a service-oriented solution, I also have to concern myself with the complexities of things like Exchange Impersonation which allows a domain user to act on behalf of other users.
There are a lot of moving parts in this prototype so this article will focus on how you go about configuring your environment so you are ready to work through the examples I will be building in the remaining parts. At this point, I don't know how many parts there will be to this series. I know that I will have at least the following articles:
- Part 1 – Introduction and Setup (this article)
- Part 2 – Creating an Appointment
- Part 3 – Using Exchange Impersonation
- Part 4 – Setting up a Subscription
- Part 5 – Getting User Availability
- Part 6 – Creating a Task
- Part 7 – Creating an E-Mail
Needless to say, this list may change, but I know I need to cover these areas. There are likely to be more further down the line.
The rest of this article is dedicated to helping you get your environment set up so that you can work through the examples in the rest of the series. There are several things that you need to have running, and some of them I am going to take for granted that you have set up. For example, I am not going to walk through setting up your OpenEdge Architect environment or your Windows Server/Microsoft Exchange Server configuration. Those are your problems to resolve.
Later, when we get to Exchange Impersonation, I am going to walk you through how to set up an impersonation account, but that is not part of this initial set up. For this initial setup I will assume that you have a working Microsoft Exchange Server that you can get at and play on it. I suggest asking your Exchange admin to create you three or four recipient mailboxes for experimentation. I have four that I created:
- Freddie F. Frogg (email@example.com)
- Harriet H. Hippo (firstname.lastname@example.org)
- Edward E. Elifant (email@example.com)
- Gerald G. Gerarf (firstname.lastname@example.org)
I also have an Exchange Impersonation account (email@example.com) that I will be using for Exchange impersonation later. Don't worry about this account just yet. We'll get to it later.
So here is the list of software that you need to install to get things going:
- Microsoft Exchange Server 2007 – This code should work with the first 2007 commercial release. I ran and tested against 2007 Service Pack 2. There is nothing special in this code, though. I'll talk more about Exchange Configuration a little later.
- Java EE6 and Glassfish V3 – This is a really simple installation process. All you need to do is set it up with its default parameters, and you should be good to go.
- soapUI 3.5 – You will need this to prove that the Web Service is working.
- OpenEdge 10.2B – installed on a client and on an AppServer. You will need a full AppServer license as the one that comes with OpenEdge Architect does not allow remote connections if my memory serves me right.
- Eclipse for Java EE – All the Java code is built inside Eclipse (3.5.2) with the Java EE IDE feature (220.127.116.11). I have the Web Tools Platform (3.1.1) installed as well. As I always install this with Java EE, I'm not sure how much of this is used. There is also a Glassfish plugin for Eclipse EE that you really should install as it makes testing so much easier.
- OpenEdge Architect or Eclipse pointing to the OpenEdge Architect plugins.
Update: Since I wrote this article, I have installed and tested Microsoft Exchange Server 2007 SP3 and Microsoft Exchange Server 2010. There is one minor modification you will need to make to the sourced code that accompanies this article for it to work with these. Line 132 of the source code file "EWSTest.java" that accompanies this article reads:
It may need to be changed to read:
Because so many of you are OpenEdge developers who have little to no experience with Java, and because this solution is predicated on a Java connection, I am going to spend some time walking through the setup of your Java install. Once we have walked through the Java install, I am going to point out how to resolve several problems that you are likely to encounter. So the rest of this article covers:
- Installing Java EE6 and Glassfish
- Installing Eclipse EE and setting it up to work with Glassfish
- Fixing certificate problems
- Changing the EWS folder permissions
- Running a quick test to prove it all works
Let's get started.
The Java EE6 and Glassfish installation is a reasonably simple installation. Before you install Java EE6, though you need to make sure you have a Java SE6 JDK (not just JRE) installed. If you do not have an SE6 JDK installed, download and install it. Accept all the defaults during the install and it will be installed in C:\Program Files\Java\jdk1.6.0_xx. If you are running a 64-bit version of Windows, the JDK will be installed in C:\Program Files (x86)\Java\jdk1.6.0_xx.
Once you have installed the JDK, go ahead and download and install the Java EE6 and Glassfish V3 Application Server. The install is also a fairly easy installation. Just make sure that as you go through the install, you point the code at the JDK that you just installed. Also, make sure you remember the password for the admin user because you will need it later. My own install of Glassfish is in C:\Apps\GlassfishV3.
Once you have installed Glassfish, a new program group will be added to your Programs folder called "Java EE 6 SDK". Find this group, open it, and choose the "Start Application Server" option. Once the server has started (the command window will disappear), double click on the "Administration Console" and your browser will open the Glassfish Enterprise Server Administration Console.
Once the Administration Console has run, login using the admin user and password. Assuming your login works, things are as good as they can get for now and we will test it later. The next step is to install the Eclipse Enterprise Edition and configure it to work with Java.
Just before we do that, go back to the "Java EE 6 SDK" program group, and choose the "Stop Application Server" option.
The next step is to download and install the Eclipse IDE for Java EE developers. This is a 190MB download so it takes a little while if you are on a slow line. Once you have downloaded it, install it by unzipping it into a directory (for me, C:\Apps\Eclipse\EclipseEE). Create a shortcut to the "eclipse.exe" file that is in the "eclipse" directory under your install path.
Now go ahead and start Eclipse for the first time. When you do, you will be prompted for a workspace. Choose a path to a new, empty directory. You will then be presented with the "eclipse Java EE ide" welcome screen. Click the "Workbench" icon in the top right corner of the screen.
The next thing to do is make sure that you have the latest patches. From the Help menu, choose "Check for Updates".
Setting the default Java Runtime Environment
The next step is to set up Eclipse to use the Java JDK that you installed a little earlier. From the Eclipse "Window" menu, choose "Preferences" (the last menu option). In the tree on the right of the Preferences window, expand the "Java" node and select "Installed JREs".
Choose the "Add…" button on the right side of the "Installed JREs" pane and you will be presented with a dialog entitled "Add JRE". Select "Standard VM" in the selection list and choose the "Next >" button.
On the "JRE Definition" wizard page, select the "Directory…" button and navigate to the install directory for the JDK that you installed above (normally C:\Program Files\Java\jdk1.6.0_xx). Choose the OK button and the Finish button on the wizard page and you will be returned to the Preferences page.
In the list of installed JREs, make sure that the new JDK that you just added has a check mark to the left of it so that it becomes the default JRE for Eclipse. Choose the OK button for the Preferences page, and we are done with the JDK setup.
Setting up Eclipse to work with Glassfish
The next step is to configure Eclipse so that it is easy to deploy code to the Glassfish server. At the bottom of the Eclipse window is a tab entitled "Servers". Select this tab. Right-click inside the pane for the Servers tab, and select "New->Server". Just below the "Server's host name" prompt is a hyperlink entitled "Download additional server adapters". Select this link.
In the "Install New Extension" dialog, select "Glassfish Java EE5, Java EE6" and choose next. Complete the wizard, and the Glassfish adapter will be installed. Once it is installed, you will be presented with the New Server dialog.
Make sure you select the "Glassfish V3 Java EE 6" option from the Glassfish folder, and choose the "Next >" button.
On the next page, select the JDK JRE that you set up earlier and make sure to point the Application Server Directory to your Glassfish install directory. Note that under the directory that you installed Glassfish, there is a subdirectory called "glassfish". You need to be pointing at that directory.
On the next page of the wizard, you are asked for the user name and password for the administrator. As this is a development machine, go ahead and specify it and check the "Preserve Sessions across Redeployment" flag. You can then go ahead and choose the Finish button and the New Server Wizard will close. In the Servers tab, you should now see a entry entitled "GlassFish v3 Java EE 6 at localhost".
Select the server that you just added, and choose the green and white arrow button in the toolbar at the top right of the "Servers" pane. Eclipse will automatically switch to the Console tab and you should see output like the following in that pane:
Waiting for DAS to start .......... Started domain: domain1 Domain location: C:\Apps\glassfishv3\glassfish\domains\domain1 Log file: C:\Apps\glassfishv3\glassfish\domains\domain1\logs\server.log Admin port for the domain: 4848 Command start-domain executed successfully.
If you now switch back to the "Servers" pane, right-click on the "GlassFish v3 Java EE 6 at localhost" line, and choose "GlassFish Enterprise Server -> View Admin Console", you should end up with a window as above. Your GlassFish Server now works from inside your Eclipse EE environment.
The first problem you are likely to run into with Exchange Server is a certificate related issue with your Exchange Web Server. To figure out if this is a problem, make sure that you can get at the Exchange Web Services WSDL. The Exchange Web Service is installed by default on the Client Access Server (CAS). Ask your Exchange Administrator for the name of this machine. The URL to the WSDL is:
If you type this URL into Microsoft Internet Explorer, you may get a certificate error as shown in this screenshot. If you get this error, you need to import this certificate into your browser's certificate store and you need to add it to the Glassfish certificate store, too.
Importing the certificate into the browser's certificate store
You need to choose the "Continue to this website" link if you see this and when you do you will be prompted to log in. After logging in with your domain username and password, you will see a page full of XML with a certificate error in the title bar. Right-click in the pane that contains the XML, and choose "Properties". You will be presented with a dialog with a "Certificate" button at the bottom right. Choose the "Certificate" button and you will arrive at the following dialog:
Your certificate will likely have different information in it. What I am going to recommend right now is not the way that I would do this in production. Right now I am working around a problem that you need to deal with to be able to make this stuff work. In production, you really do need to set up a trusted certificate authority within the organization, but that is way beyond the scope of this article.
The next step is to choose the "Install Certificate" button above. This will start the "Certificate Import Wizard." You will need to install this certificate in the "Trusted Root Certification Authorities" Certificate Store. Page 2 of the Certificate Import Wizard contains a radio-set that allows you to select where to install the certificate. Choose the "Place certificates in the following store" option and then choose the "Browse…" button. You will then be presented with a dialog that allows you to select the certificate store.
Choose the "Trusted Root Certification Authorities" entry and choose the OK button. Finish going through the wizard and you will eventually be presented with the following dialog (or something a lot like it):
Choose the "Yes" button and the certificate will be installed for you. Close down your browser, open it up again, and try and navigate to the URL above again. This time you should not see the Certificate Error message that we saw above and you should be able to log in and get to the WSDL.
Exporting the certificate
We're not done with the certificates yet, though. The next thing we have to do is export the certificate from the certificate store so we can load it into Glassfish's certificate store. With Internet Explorer open, choose "Internet Options" from the "Tools" menu. When the Internet Options dialog opens, select the "Content" tab as below:
Choose the "Certificates" button in the middle of the dialog and you will be presented with the "Certificates" dialog. Choose the "Trusted Root Certification Authorities" tab and scroll down and select your certificate from the certificate store:
Now choose the "Export" button as you will need to create a certificate file that can be imported into the Glassfish certificate store. The "Certificate Export Wizard" will now be presented and you should choose the "Next" button, making sure to select the "DER encoded binary X.509 (.CER)" option:
Finish off the wizard by selecting a destination in which to store the certificate file.
Importing the certificate into the Glassfish certificate store
To import the certificate into the Glassfish certificate store, open a command line prompt and change directories to the directory in which Glassfish is installed. I installed it at C:\Apps\Glassfishv3. Once in that directory, issue the following command (I am assuming that the Java/bin root directory is in your path):
cd glassfish\domains\domain1\config keytool -importcert -v -trustcacerts -keystore cacerts.jks -file c:\<pathtocertificate>\<certificatefile>.cer
You will be prompted for a password. If you have never changed the password for the certificate store, the password defaults to "changeit". Import the certificate into the store, and you should be almost ready to start using Glassfish to communicate with the Exchange Web Service.
The next step to making this code function is to change the permissions on the EWS folder on the Microsoft Exchange Client Access Server to which you will be connecting. This requires administrative privileges on the server.
Warning: I do not recommend that you do this on your production Exchange Client Access Server, especially if it is an internet-facing server. Making this change significantly changes the security level of your Exchange server and could make it vulnerable to attack. I have a test Exchange server specifically set up for this.
Run the "Internet Information Services (IIS) Manager" tool (also accessible from Server Manager as shown below. Assuming your server is named EXCHANGESERVER, expand the EXCHANGESERVER node. Under it you will find a "Sites" node. Expand that and the "Default Web Sites" node under it. Under that you will find an "EWS" folder. Select that folder.
In the "/EWS Home" pane that now opens, there is an icon for "Authentication" in the "IIS" group of icons (In the above screenshot, it is the third icon from the bottom on the left of the pane). Double-click this icon and the pane will change to look like this:
In the Authentication pane (the new pane) there is one item that you need to change. Click on the line that says "Basic authentication" and then right-click on it. This line should currently have the word "Disabled" in the "Status" column. In the popup menu that now displays, select "Enable".
That should do it. The configuration changes you have now made should work for you.
As I mentioned earlier in this post, you are going to need soapUI to be able to do any testing, so if you have not done so, now would be a good time to download and install soapUI. Once you have done that, the other thing you will need is a zip file that you can download here that contains a sample Web Service to test the communication with Exchange Web Server.
Once you have the zip file downloaded, start Eclipse EE. In the "Project Exporer" pane at left, right-click and from the context menu select "Import -> Import…" and the "Import" dialog below will appear. Expand the "General" folder and select "Existing Projects into Workspace" and choose the "Next >" button.
On the next page of the Import wizard, choose the "Select archive file" radio-set and browse to the zip file that you just downloaded. In the "Projects:" selection list, make sure that EWSTest is checked and choose the Finish button.
If all is good, there will be no little red and white "x" on the EWSTest project. If there is, it's probably because the JDK version that you have installed is different from the one I am using. To fix that, right-click on the EWSTest project and select "Properties" from the context menu. In the Properties window, select the "Java Build Path" property set and choose the "Libraries" tab. Select the "JRE System Library" and then choose the Remove button. Now choose the "Add Library…" button, select "JRE System Library" in the "Add Library" wizard page and choose next. Make sure the "Workspace default JRE" is selected and choose the "Finish" button. Choose OK on the Properties page and the little red and white "x" should disappear.
Now that you have a properly compiled version of EWSTest project, you need to start your Glassfish server if it is not already running. Drag the EWSTest project from the Project Explorer pane to the "GlassFish v3 Java EE 6 at localhost" entry in the Server pane. If you expand the Glassfish node in the Server pane, you should now see "EWSTest [Synchronized]" under the GlassFish node as follows:
Now comes time to test it all out. Make sure you leave Eclipse running – we need that Application Server. Now go and start soapUI, and right-click on the "Projects" node in the Navigator. From the context menus choose "New soapUI Project".
In the "Initial WSDL/WADL:" prompt, type the following:
Choose the OK button and soapUI will create a project for you called EWSTestService. Expand the CreateAppointment node and under it there is a Request 1 node. Double-click the Request 1 node and fill in the contents of the XML pane on the left.
The node in the XML document need to be completed as follows:
- ExchangeServer – The fully qualified domain name of your Exchange Client Access Server that is running your Exchange Web Service;
- DomainUser – Your test recipient account qualified with a domain name – so DOMAIN\user;
- DomainPassword – Your test recipient account's password;
- Description – A description to appear at the top of the appointment;
- Location – A location where the meeting should take place;
- StartDateTime – A date and time at which the appointment should start in the format yyyy-mm-ddThh:mm:ss (the T is required);
- EndDateTime – A date and time at which the appointment should end in the same format as the StartDateTime. Note that if this date and time is less than the start, you will get a "Bad post… 500" error.
Once you have filled all of these fields out, choose the green arrow button – tooltip: "Submit request to specified endpoint URL" – and the call will execute. If it is successful, you will get a SOAP document in the right-hand pane with a "CreateAppointmentResponse" node that includes a "return" node with a CDATA node inside it. The return node is fairly long and includes an "Item" node with "ID" and "ChangeKey" attributes.
Of course, your ultimate test is to login to the test user's account and start Outlook for him. You can celebrate when you see the appointment created:
If you double-click the appointment, you will note that the details have been filled in exactly as you would expect:
Caution: The test code that I included here could cause you some trouble if you try and create appointments in different users' calendars without restarting the Glassfish server in-between. It won't do that and we'll get into why in one of the next posts. Just be careful not to use this to mess up real calendars inadvertently.
At this point you have a working Exchange Web Services call happening from Java. This is the first step. In the next part to this series, we will walk through the code that actually creates the appointment to understand what it is doing. That code will be commented to help explain what it does.
Please feel free to leave any comments you may have and please let me know if you run into problems with the instructions that I have given here.