Looking at the new Integration Activity approach - Part 1

NetIQ Identity Manager has several components that work together to accomplish the needs of an enterprise.

Initially IDM (when it started as DirXML 1.0) was focused on synchronizing objects from one directory service like thing to another. (eDirectory, Active Directory, Lotus Notes are very directory like. But things like JDBC databases, are less directory like).

This is where the core policy stuff that is my favorite part of IDM resides. You can read all sorts of stuff I have written on the subject, or just go look at my book on the topic: Definitive Guide to NetIQ IDM Tokens

As the product matured the need for manual and automated intervention for audit and compliance reasons became clear and the Roles Based Provisioning Module was developed.

I tried explaining the basics of where the various bits and pieces go in the User Application in this series:
Introduction to Workflows and PRDs in Identity Manager – Part 1
Introduction to Workflows and PRDs in Identity Manager – Part 2

The need for the above articles was due to the sometimes convoluted interface, where there is so much to control and set that the interface can be very confusing. The User Application is a surprisingly powerful way to develop web forms for approvals. The downside is that while not that hard to use, the learning curve to get started can be intimidating.

One of the neat things within the User Application workflows is the ability to do something, once a decision has been reached. You can use an Entity Activity to write data back to eDirectory. You can assign an Entitlement directly (Deprecated in later versions), assign a Role, assign a Resource, or do an Integration Activity.

Integration Activities are pretty powerful as they let you make a SOAP call to an outside web service.

I tried offering some examples, of how you could make a Stop Workflow action from DirXML Script policy, using a Start Workflow token to start a Workflow that calls an Integration Activity (or two) against the User Application Web Service, to get the ID of the workflow, and then stop it. This was pretty neat, since from Policy this would be very hard to otherwise. You can read about this here:
Using SOAP to terminate a running workflow – Part 1
Using SOAP to terminate a running workflow – Part 2

I like to collect examples of errors and write about them, since it is a great feeling, when troubleshooting a problem, pasting the error message into Google, and then finding an actual discussion of the error, and hopefully an explanation and solution. I would love if more people would consider doing articles like these as well.

I kept track of a bunch of Integration Activity specific errors in this article:
User App, SOAP Integration activity interesting error

Having said all that, what exactly is an Integration Activity? As I said before, it lets you make a call to a SOAP based web service. That means, you build an XML document, that matches the standard the web service takes, submit it over HTTP (or HTTPS) and get a response.

The standard that the web service uses to define themselves is known as a WSDL, Web Services Description Language.

The parsing of this WSDL is theoretically simple, but in the real world, nothing ever is simple. Thus in one of the updates for Designer 4.01 they changed from the 'old' method of parsing the WSDL and using it, to a new version that basically uses the SOAP UI libraries to do the work. SOAP UI (www.soapui.org) is the gold standard for dealing with SOAP calls. In fact, I pretty much always start, opening the WSDL in SOAP UI, figure out how to get it working, then do what is needed based on what I learned.

The consequence is that the interface, which was already complicated changed again. I figured at this point, it was worth reviewing the old and new versions to compare and contrast the approaches, since they are somewhat subtle, and will actually teach you a fair bit of how the stuff works. That is, if you understand why they had to change the different parts, you will understand how it works. This is probably the hardest kind of documentation, and possibly the most useful. I love documentation at this level, and it is so rare to find it. Which I get, since it is quite hard to get written. Those who can, do. Those who can't teach gym, so let me try and do.

Here is an image of a sample Workflow I am using for my example. I highlighted a couple of interesting points in the image. First off, the workflow has two integration activities, named Old Version and New Version. On the right, I circled the last item in the Activities section of the palette, which is the Integration Activity. What is interesting is the tool tip says Create Rest Activity not SOAP. As you will see in a bit, you can do a SOAP specific action or a more generic XML action.


I also highlighted that if you select one of the Integration Activities, and then the Properties tab on the bottom left, there is an entry for the WSDL Resource. Here you specify a file system path to the file.

Once you enter it, you cannot change it, without creating a new activity, and it stores the path in a native file system way. I.e. On Windows it would be c:\data\MySOAPService.wsdl or on Linux it might be more like /home/geoffc/soap/MySOAPService.wsdl

It turns out the info is stored embedded in the Workflow, which is good since if you share the project in SVN with your colleagues it is likely the path does not exist on their computer, especially if you differ in your choice of operating systems.

The first step to define your IA (Integration Activity) is to pick a WSDL file to work with. Once you do, you have some choices to make.


First up, is the highlighted option "User new WSDL Generation type" which is ultimately the point of this series. Everything hinges on the choice you make here.

The WSDL can define many 'Ports' which my example of the User App Provisioning WSDL only contains a single port, Provisioning. But there are many operations supported, and you can see them to select which you intend to use.


In this screen shot you can set the drop down and the sorts of options you have. They are identified by the name of the action (addComment), and the input document name (I=addCommentRequest) followed by the output document name (O=addCommentResponse).

Next is the Endpoint Expression, which is the URL of the web service. Sometimes the WSDL includes the proper URL, sometimes it is generated and only has a generic value which you will need to change. Once nice thing is you should notice the 'E' button for ECMAScript which means you can use variables, or even GCV's via the GCV.get('name.of.gcv') function. Do note that if you want a literal string as a URL, remember to enclose it in quotations. If you specify a variable, when you go the next screen, in the new WSDL approach, you will see that the WSDL includes, on the <soapenv:Envelope> node an XML attribute of the name of the variable. So if you replaced the URL with an ECMA variable like _serverUrl_ then the node will look like: <soapenv:Envelope _serverUrl_="">

Then you can right click on the IA, select Show Data Item the Pre Activity mapping, and now you can get at the value via XPATH.

The same is true, if you select the SOAP Services requires Basic Authentication you can specify variables for the username and password you will get XML attributes available in the Pre activity mapping.

You can see this in this screen shot:


At the top you see the Pre Activity mapping, where the source expression is where the data is coming from. You could copy it from flowdata, perhaps from a form, perhaps from a GCV, or wherever. Then the Web Service Input field is the XPATH of where the data should be copied. If you click the Mapping button, you see all the XML nodes available, and you can strip out any unneeded nodes that you do not need to copy data into.

The Post Activity mapping switches the columns, where now the source is the Web Service Output Field and the second column is the target, which is ECMA that lets you write it to flowdata or the like for later use. Thus you could use a web service to query for some info, in the Post Activity copy the element of the result into a flowdata variable to use in the next action in your workflow. Maybe use an Entity Activity to update the user object in eDirectory, or maybe use it as the next step as input to the next web services call.

Here is where the first major difference between two comes in. Take a look at how the same WSDL was parsed. You can see it in the following screen shot (old method), and the next screen shot (new method) in terms of the XPATH needed to get at the data in the Data Item Mappings, Pre Activity mapping.



In these screen shots, I used the Mapping button and expanded what the XML data tree looks like, which is instructive since it shows the structure of documents as parsed by each method.

You can see that for my silly addComment example (add a comment to a running workflow) the old way, sees the root of the document as: addComment followed by an addCommentRequest node.

The new method starts higher up, with the top being the soapenv:Envelope node. (Of course this display ignores namespaces)
But you can also see that the path is Envelope/Body/addCommentRequest.

Thus in the old way, the Envelope/Body levels were replaced by the name of the call, addComment.

Not a big deal, but the beginnings of differences that may start to add up as we look deeper.

You will note that both have the _serverUrl_ and the like XML attributes available to send in User, password, and URL.

The Post-Activity Mapping for copying data out of the response basically shows the same pattern. The old one is addCommentOutput/addCommentResponse vs the new approaches Envelope/Body/addCommentResponse.

Now if you get an error, it comes as a FaultInfo node, which is the same in both cases. Now I wonder if that is a bug in the newer approach or if it is just because the XML looks the same in both cases?

Now the next set of interesting bits open up a large can of leeches (We fish with leeches where I grew up, not worms! Thus the cliche is a little different. Besides leeches are way more slippery than worms!). Thus I think I will start on some observations and save the rest for the next article.

There actually seems to be further changes since my earlier articles on the Stop Workflow approach. Back then you were expected to Edit the Integration Activity (From the workflow view, right click on your IA. You will also get an extra 5th tab as well at the bottom, labeled Integration)

The WS Interchange action, in the Action Model, right click Edit Action, has a Connection tab where you would have normally set the User name and password for authentication. The first tab is where you would set the URL, and is now simply replaced with the _serverUrl_ variable. But the authentication is now changed to be set via adding a Header, with the username:password base 64 encoded, and following the string "Basic ".

In the past, this was 'your issue' to remember to set the credentials. Now the IA sets you up 'out of the box' for easier success. Of course, in the Username field they could have just set the ECMAScript value to _userId_ to use the variable and be done with it.

I am not sure why they changed this little bit, in this way, but it is easy to understand either way.

I have lots more to say on the Action model and the differences between the two approaches so stay tuned for the next article in this series.


How To-Best Practice
New Release-Feature
Comment List