I find it easier to get to grips with products when I use them, tool tips and “tip of the day” splash screens bug me, I actually prefer meaningful error messages when I mess things up. With that in mind I’m not going to go through each and every facet of what you can see in the design tool you just fired up I’m just going to walk through a simple example… which will educate as well as stimulate some questions…..
Having said that, it is helpful to know which end of the proverbial oar to use before starting to paddle so here is the express tour of the main Policy Studio design window.
The main policy studio window has two sections – the section on the left is for configuration navigation and is split into 5 separate viewing perspectives
- Services – For configuring inbound channels e.g. http listeners, jms and pop3 consumers
- Policies – Viewing and managing policies – we will explore this in more detail later
- External Connections – external databases and repositories, AuthN and AuthZ / IdM Provider integration, SMTP, JMS etc…
- Users – A built in user repository that can be used to apply AuthN and AuthZ without requiring a 3rd Party User Repository or IdM product
- Certificates – self explanatory – contains functionality for managing certificates and keys
Selecting the different sections on the bottom left hand container changes the explorer tree node view.
left clicking on any of the node items changes the contents of the tabbed central panel to a context sensitive display
If you are anything like me then you’ll probably have tried clicking, double clicking and right clicking on just about everything that looks clickable by now (I’m every IT trainers worst nightmare). Hopefully you managed to cancel out out of everything you weren’t sure of and tried deleting anything you thought you understood to get back to ground zero…. if you didn’t then don’t worry about it simply close the top level gateway configuration tab, choose to discard your changes and then click “edit active configuration again” and phew…you’re back!…
First things first check you have the gateway running on port 8080 (this can be changed no problem but will be covered in a separate post) **TODO** link to changing ports post
Next fire up your browser and navigate to http://localhost:8080/healthcheck – you should get a little message back saying “OK” – depending on your browser it may or may not be rendered as XML
Use your browsers view source facility to take a look at what is actually sent back by the gateway
the gateway URIs are case sensative http://localhost:8080/HealthCheck will give you a totally different result (again this can be overridden but is out of the scope of this post)
If you haven’t already fired it up and had a look around already then check out the traffic monitor and real time monitoring tools at http://localhost:8090/
the traffic monitor is a really useful tool for development and diagnostics…. and shows policy execution, trace and payload information, we will take a look as part of the first policy exercise.
So now we have the basics in place, and we can navigate the different configuration sections we can go right ahead and develop our first policy.
The gateway is often used in the context of a reverse proxy for web, xml and ReST services, in the case of Web Services we can use an import wizard to load up a WSDL and auto-generate a policy framework that virtualises the service. Ironically this makes more sense when you know more about how the gateway actually works. So instead of plumping for the standard StockQuote Service (which I promise to cover in a later post) I’m going to take a step back and work through setting up an “echo” style service on the gateway – no SOAP, no WSDL, no XSD just an http request and response.
Start by creating a new Policy Container under the Policies node in the node tree on the left hand configuration explorer pane
You can also add a sub container if you like, containers are essentially just folders that help you keep your policies organised – this is particularly important for separation of concerns and for re-usable “utility policies”.
Once you have the containers configured as you want them then add a policy to the appropriate container.
Policies appear in alpha numeric order (so as a tip – start with at least one leading zero – you can rename them later if you need to.
When you click ‘OK’ the blank design canvas will load up into the central tabbed panel along with the filter pallet on the right hand side
Remember to use the text lookup box at the top to help you find the filter components you need to build the policy – You can also customize the pallet to show and hide individual filters and categories
Under the “Conversion” section you will see the “Set Message” filter – we are going to use it to build our “Hello World” message that will be sent to the calling client.
The “Conversion” category contains a whole bunch of filters that are used to manipulate messages; XML, SOAP, Attachments, text, binary, pretty much anything.
The “Set Message” filter can be used to create a template message of a particular mime-type which can then be populated with information drawn from other sources – SAML Assertions, LDAP repositories, Databases, message headers or protocol information.
Learning what each of the filters does, and how to combine them is the essence of good policy design – if you are resorting to using the scripting and extensibility features of the design environment then the chances are you haven’t thoroughly explored what’s available or not thought through what exactly is involved in achieving the desired result; as with all “development” there is no real substitute for a good design document and a few flow / sequence diagrams to help you get it right.
I would start by adding the “set message” filter to my favourites though.
Left click on the filter in the categories list and DRAG it onto the design canvas for your hello world policy – then let go. You will be prompted with a dialogue to configure the set message filter …. do something like this…
Notice that the content-type has been set to text/plain – this means we don’t have to go writing html or xml and the message will render ok in a browser without issue – if you want to put some XML or HTML then feel free to give it a go, just be sure to use the appropriate content type (text/xml or text/html as appropriate)
Notice the “Next” button at the bottom – pretty much every configuration dialogue has one of these and it opens up the logging options for each filter – again feel free to take a look, but I’ll cover this off in a different post.
Now you have a “greyed” out set message filter on your canvas.
Every policy must have at least ONE filter and ONE START; A Policy MAY have just ONE filter that IS the START
As it is our policy doesn’t have a start point, we just dragged on a filter and configured it. To set our set message filter to be the start filter we need to
Right click on the filter on the design canvas and chose “set as start”.
The filter now shows as both Start and End
So far so good…. but we need to “bounce” or “reflect” this back to the calling client – for http/https requests we use the “reflect” filter from the utilities section to do this.
type reflect in the pallet lookup text box and expand the “Utility” Section
You will see that the reflect message filter is not joined to the set message filter which is our starting filter – and so at the moment it is inactive to make it part of the policy we need to connect it with one of the connectors.
Policies are constructed by building logical trees (Binary decision trees) of filter execution – so in “pseudo-speak”… when the message has been set successfully we want to reflect the result.
Left click *and release* on the set message filter – then left click on the Reflect filter
Note: success and failure paths are not dragged from the pallet.
The reflect message filter SHOULD turn RED this is to warn us that the filter may not have enough information to execute properly – to see what the problem is hover over the filter
To execute properly the reflect filter needs http headers (i.e. it needs to be part of an http request response pair – the http headers will be provided by an incoming request to the gateway that invokes our hello world policy – So all that is left for us to do is wire the policy up to a suitable URI to expose our hello world service.
Right clicking on the Defualt Services node gives us an option to add a “relative path” – or you can do this by selecting the “Default Services” node and using the link in the design panel
Chose a meaningful path – /blog/tutorial01/helloworld
and then select the hello world policy as the “Path Specific Policy”
Again, the audit settings aren’t what this post is about, but feel free to have a look around –
The reflect message filter now has the required http.headers attribute (that will be populated by the http request) so there are no “red” warnings.
Now we can test our policy using the browser –
The default http listener that we added our relative path to was on port 8080 – so to test our policy we combine the protocol (http) the host name (localhost) the port number (8080) and the relative path (/blog/turorial01/helloworld) to give us our uri.
What you should have learnt ….
- How to start up the gateway and connect policy studio
- How to navigate the primary sections of policy studio
- How to create containers to organise your policies
- How to use the filter lookup text box to search for the filters you need
- How to create a basic policy using the drag and drop filter components
- How to link filters with the success connector
- How to add a relative path to a service node and map it to a policy
- How to deploy your configuration to your gateway
- How to detect when a filter doesn’t have enough information available to execute