Hello World

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.

ps_Services

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.

 

ps_Services

left clicking on any of the node items changes the contents of the tabbed central panel to a context sensitive display

ps_users

ps_policies

ps_certs

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

image

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)

image

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.

image

image

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

image

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.

image

image

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

image

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.

image

 

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 image 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…

image

 

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.

Click finish

image

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”.

image

image

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

image

Click and drag the image filter onto the canvas and click Finish

image

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.

image

Almost every filter in the pallet has two possible outcomes SUCCESS image and obviously image 

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.

image

To link our Set Message filter to the newly added reflect filter click on the image in the pallet on the right hand side – this puts the mouse into “success connector mode”

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.

imageimage

To exit “Connector” mode either hit the escape key or click on the image component in 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

image

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.

Select the services category image on the left hand configuration explorer panel and expand the nodes down to the “default services” node.

image

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

image

Chose a meaningful path -  /blog/tutorial01/helloworld

image

and then select the hello world policy as the “Path Specific Policy”

image

image

Again, the audit settings aren’t what this post is about, but feel free to have a look around -

click Ok and navigate back to your hello world policy (use the tab at the top of the central pane or the image “browser back” button from the toolbar menu at the top left.

image

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.

To deploy your configuration (as we haven’t actually made any changes to our gateway yet) hit the F6 (function key) or click the Deploy icon image in the toolbar menu at the top.

** Notice the status bar at the bottom **    image

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.

http://localhost:8080/blog/tutorial01/helloworld

image

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

Fundamentals

A policy must have at least one filter, and at least one of the filters must be set as the start point for the policy.

A policy that has only one filter which is set as the start filter can be valid

Any filter not linked directly or indirectly downstream of the start filter will be inactive – inactive filters are shown greyed out

Up Next

Hello Joe – the hello world policy gets a little more personal as we explore some basic authentication, failure paths and using “attributes”.

About these ads
This entry was posted in How To, Vordel, XML Gateway and tagged , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s