How to develop and test TEWS applications

Document ID : KB000044019
Last Modified Date : 14/02/2018
Show Technical Document Details

Introduction:

 

This document explains the need for a methodical and structured approach for TEWS development.

 

Background:

 

TEWS is an Identity Manager web service that's running inside the hosting application server and is able to execute Identity Manager's tasks. TEWS is intended to allow a customer to execute Identity Manager's tasks from client applications. There are a number of key parameters that influence TEWS successful execution. If not addressed individually and tested in that way it may mean that with errors , one will not know how to 'start troubleshooting'. See the Instructions section below about these parameters and how to approach TEWS development and testing in a way that will advance you layer after layer so you are more confident in your execution and more importantly, you are better able to more quickly find root cause of problems when they occur.

 

Environment:

 

Any Identity Manager version.

 

Instructions: 

TEWS is a Task Execution Web Service based on WSDL xml requests. Essentially TEWS is a servlet inside Identity Manager that reads the WSDL xml requests, analyzes them and then executing the task with the context given in that request. This context includes: the name of the task, the arguments for the task and the credentials of the user who is to execute the task.  

 

You are always able to execute TEWS by submitting properly constructed XML requests. There are additional ways though. These are by developing either a Java client or a .NET client application. To do that you will need to generate stubs in these technologies , embed in your application and compile with your client code.

 

You can see that the process of using the APIs is an added layer to the XML request and therefore, it will always be best if you use SOAP UI which is a freeware application that allows you to generate the wsdl and create XML intrinsic requests so you can test it first, only then go about developing your Java or .NET program.

 

Another parameter that has a major impact on TEWS execution is whether or not your Identity Manager application is connected with Site Minder. If so, it necessarily mandates that any request to Identity Manager be protected, authenticated and authorized by Site Minder. This includes any TEWS request since it's embedded with Identity Manager and is part of the application.

 

 

Here is a structured approach for your development and test cycles:

1. Identify which tasks you need for your TEWS. These tasks need to be enabled for Web Services (modify admin task -> select your task -> profile page -> check Web Services -> submit). There is no reason to expose more tasks for a number of reasons.

 

2. Ensure you have a proper admin user ID that is allowed by Identity Manager to execute these tasks. The best thing will be to create a specific Admin Role for a TEWS_Admin_Role and allow these tasks for that role. Then, associate this role for your admin_id that you need to execute your TEWS requests. If later you need more tasks to work via TEWS you can enable them for web services and add to this admin role which already is assigned to your admin ID.

 

3. At this point , if Identity Manager is connected with Site Minder then disable this connection so that you can eliminate Site Minder be an added factor or complication to testing these tasks under that ID you created.

 

4. Log into Identity Manager user interface as that admin ID that carries the TEWS admin role and confirm you have the access to these Identity Manager tasks, that you can execute them all well. In these tests also test your errors and invalid inputs so that you learn of the robustness of your tasks. This phase basically tests that your tasks work (not as TEWS) and that the admin ID has the proper access as far as Identity Manager is concerned to execute them.

 

5. At that point test the TEWS itself. Enable Identity Manager for TEWS and enable the wsdl generation. Use SOAP UI and target it to the application server directly. Generate your wsdl, confirm all your tasks have been generated with requests, then use SOAP UI to construct all the XML requests of all your tasks as you did in step 4 and test them all. This will now ensure the Identity Manager indeed will run these tasks from TEWS by its intrinsic basic XML layer - not with the Java or .NET APIs yet.

 

6. At that point, connect your Identity Manager back with Site Minder , restart the application server and use SOAP UI to test the same tests as in step 5 but this time point to your Site Minder and make sure all requests go through its protection mechanism, go to the web server and work via the web agent and policy server. If you need to troubleshoot the Site Minder protection mechanism then it will be now that you should do that by examining its logs and possible trace files. You need to make sure you have a realm for your TEWS requests and a proper Site Minder side authorization policy so that Site Minder can allow your requests.

 

7. At this point you basically should be at a point that your TEWS requests work via SOAP UI by constructing the direct XML requests using the fronting Site Minder mechanism (if you have it). At this time you can develop your client application. You should follow the directions to generate the stub files in Java or .NET , then compile with your application.

 

Again, at this time, you will be better off to disable Site Minder connection from Identity Manager and restart Identity Manager so that you can test your Java/.NET application by connecting directly with Identity Manager (as you did in step 5). 

 

8. At this point you shall bring back the Identity Manager and Site Minder connection, restart the application server, change your client code to direct to Site Minder and test your application calling TEWS by pointing at the Site Minder front.

 

 

The point of this structured approach is to build your confidence with your solution, to ensure all layers properly work and perhaps most importantly to build your understanding of the need for all these layers that come into play with TEWS execution. 

 

 

Additional Information:

None.