Announcing the Open-Source WSDL2Apex Generator

I am back with another open-source project. By popular demand, the WSDL2Apex generator is now available for you to improve and repair.

I am back with another open-source project. By popular demand, the WSDL2Apex generator is now available for you to improve and repair.

One of the ways in which the Force.com platform is awesome is that you can integrate your logic with other systems. Apex offers nice ways to expose your logic as web services, and it offers nice ways to make callouts using REST. It also offers a “nice” way to make callouts using SOAP, known as WSDL2Apex.

Prior to being product manager for Apex, I was writing Apex in my day-to-day job.  I have used this “nice” way to make callouts, which begins with the WSDL2Apex generator.  I know what that feature does, and I know many of the things you are forced to do in order for it to do what it does.  I have shredded a WSDL down to the bare minimum in Notepad in order to get any class output at all. I have then un-shredded the things it turned out I needed for the callouts to actually go to the right place, and retrieve the right data. I have furrowed my brow and scratched my head trying to figure out how to call the generated methods. I know some of you have done other unspeakable things to make it easier to ingest existing WSDLs and use them in your Apex code.

That nonsense stops now. The WSDL2Apex generator is now open-source. From now on, you, dear reader, are going to be able to work with us, and everyone else reading this, to make this feature complete.

Fish, or Cut Bait

The WSDL2Apex generator has lived behind a button on the old setup UI pages for longer than I can remember. It has remained in the same state, functionality-wise, for that same period of time. Dictatorships have been toppled, and the governments that replaced them have subsequently been toppled, all since the last improvement to the capabilities of that WSDL2Apex feature was made.

What happened? Did we forget about this feature? Were we perhaps afraid to challenge the shadowy w3.org and its schema? Were we too busy keeping up on world events?

Truth be told, this feature fell between teams. One team built it, another helped, but, in the end, nobody officially owned it. As Otto von Bismark said back in 1865, “software, like sausage, ceases to inspire respect when you know how it is made.”  (Note: I can’t back that quote attribution up, but I can quickly update Wikipedia to back it up.)

On the one hand, your first demand of us is stability. And, on that front, we have delivered! The WSDL2Apex feature has been quite stable! On the other hand, you want multiple port-type bindings, and don’t care how hard it is to maintain Apex. We have spent much of our time focused on the stability of Apex in general, and thus have not been able to add any of the very legitimate enhancement requests that have come in for the WSDL2Apex feature.

This is where you come in to the picture.

Another Open-Source Feature!

The Apex generation logic behind that old setup UI button is now available as open-source. You now share ownership of this feature with us. Welcome to the team!

There is a brand new open-source project which contains the WSDL parsing and code generation logic. This is all helpfully contained in an eclipse wizard flow, which can be conveniently built into a JAR, which can be conveniently included in the open-source Force.com IDE. (Yes! The star of my previous blog post is back for the sequel! More on that later.)

You will find the repository at: https://github.com/forcedotcom/WSDL2Apex

The exiting WSDL2Apex generator has been split into two main steps: parsing the WSDL file, and spitting out Apex code based on the parsed input. You can dig into each of these steps, modifying them as you see fit for your project needs.  In addition, you can add logic prior to each of these steps to make the whole process easier.

The Eclipse wizard has nice stopping points for you to add any user interaction you wish to add. You could ask if the user really wanted all 15,000 methods, or would they instead like to select the parts they need. You could offer a new & improved variable naming option, for which the user could provide input prior to code generation.

The code generation itself could use some new features. We don’t auto-generate tests, even though we do count the code against you for test coverage.  Perhaps some automated test coverage would be useful! (We had talked about ignoring generated classes in the calculation, but, now that we are no longer in charge of the code generation, it is going to remain included.) Something I have always done to my generated classes is to add human-readable method stubs that call the generated methods; do with that idea as you will.

I want to point out that the code we are releasing is pretty much the unaltered code that has been there since Qaddafi and Mubarak’s last meeting. We didn’t change it. We just encapsulated it in a way that we thought would (a) make it easy to modify and (b) get it to you as soon as possible.

Putting It Together

As mentioned, this project will compile into a JAR that can be included in the Eclipse plug-in.  As a part of this open-source effort, we added a menu item to the plug-in for generating a new class from a WSDL. That hook gives you all you need to start generating your classes in the plug-in.

Eclipse will be the vehicle for advancements in the code generator.  But, Josh, what about that button in the setup UI, the one that predates the existence of South Sudan? It will not get any benefit from any advancements, whether you code them or we do. It may remain; it may vanish. If it remains, it will remain unchanged in terms of capability.

The governance for the WSDL2Apex generator project will be the same as that of the Eclipse plug-in.  This has been discussed at length in other places (including my recent blog post), so I won’t cover it here.  I’ll summarize by saying we will maintain a “supported’ branch of the code, and we will accept pull requests from you as they arrive and are deemed fit for inclusion.

If your changes are not generic enough that we want to support them, you’ll still be able to use your changes to generate Apex classes for your org.  You will be able to build a plug-in from the supported code line, but include your JAR for WSDL-based class generation.  Alternatively, you could just use the parsing and code-gen code as a standalone widget, and copy/paste the output into the IDE of your choice.

I Want This Now!

The latest beta of the Eclipse plug-in has New-Class-From-WSDL feature in it. If you build the latest version, you will have this.  Our next official release of the plug-in will have the feature, for anyone who prefers to wait.

For now, the new plug-in feature has the same limitations as the button you are familiar with, since, as mentioned, we did not change the features in creating the open-source library. As changes are made by the community, and adopted in to the master branch, these limitations will fade away, and new capabilities will appear. Which brings me to…

The $100 Hackathon

Unfortunately, I cannot sponsor a million-dollar hackathon. However, I can sponsor a $100 hackathon!

The challenge I lay down here is this: make the best change to the WSDL2Apex generator, before Dreamforce.  $100 Amazon gift card to the winner.

I will personally look at all the pull requests, and will choose which one is the best. “Best” will probably include basic things like “it works” and “it is generally useful to everyone”. Salesforce employees are eligible, too – the internal technical architect community has been asking for access to this for a long time, so I want to challenge them for submissions as well.   I’m not going to make any fine print rules – I’m just going to choose, and I’ll let you know why I chose, and that will be that.

If you’re going to participate, which I am certain that you are, please create an “issue” in the git repository, and comment that you will have it done by Dreamforce. Check to see if anyone else is doing the idea already; I’d rather not get five people building the same feature! Do two features, if you want. But try to finish a bit early, so you can go win the million-dollar hackathon starting on October 10.

$100 Amazon gift card to the winner. You might say, “meh.” I say, “$100 is better than a kick in the pants!” Second place, third place, and all other places receive undying gratitude from the community (and a shout-out in my next blog post). You and many others will actually be able to use the fruits of your labors immediately…this is a collaborative hackathon!

Let’s see what we can do.

Published
September 26, 2014

Leave your comments...

Announcing the Open-Source WSDL2Apex Generator