Online documentation - WebsydianExpress v3.5

Understanding the Service Structure

Overview
The elements
Example
More Information

Overview

This document describes the service structure in the administration interface.

The service structure shows a representation of currently published services. Based on this structure, you can always find out what services you are providing and how it is possible to access these services.

However, to be able to find this information in the service structure, it is important to have a basic understanding of what the different elements in the structure represent and what the information provided for each element represents. It is the aim of this document to provide this understanding.

The elements

Root

[icon]

The root element is just a placeholder that represents the site itself. The root element contains no data and can't be updated.

URL

[icon]

The URL elements show that the site can provide services on the specified URL extension.

The text shown in the tree is the URL extension that has been specified for the URL element.

Based on the entry URL for the site, the service extension specified on the site settings, and the URL extension specified for the URL element, you can find out the URL the customer should access in the following manner:

If the entry URL for the site is:

http://www.myserver.com/site/mysite

And the service extension specified on the "Site configuration→Site settings" page is:

/service

And the URL extension specified for the URL element is:

soap

Then the full URL that targets this URL is:

http://www.myserver.com/site/mysite/service/soap

This means that all requests that target URLs that start with this value will be handled according to the rules that are specified for the URL element.

Apart from the URL extension, the most important information that is specified for the URL element is the service processor that will handle the request.

To see the service processor select the URL element in the tree and press "Update". You can see the currently selected service processor in the drop down box.

In most cases you will specify that the URL element is Active (again, this is changed on the Update page). But you do have the option of specifying the URL element as being inactive. Doing so means that the runtime will disregard all the definitions scoped by the URL element when trying to find a service handler to call.

If you have set the URL element to inactive, a small red x mark will be shown on the URL icon in the tree: [icon].

More information about service processors.

Selection criteria

[icon]

The next level in the service structure shows the criteria that will be used to evaluate the requests that target the URL element that scopes the criteria element.

Each URL element can scope several criteria elements. The criteria will be evaluated in the order they are shown in the tree (top-most first).

The selection criteria are used to identify the service handler to call for a specific request. Each selection criteria can be understood as an instruction to the runtime about what information it should extract from the request to determine the service handler to call.

The text shown for the criteria elements consist of the name of the criterion, optionally followed by a colon followed by a specification of the criteria.

An example of the case, where the text shown is in two parts could be "http-header:MyHeader". This instructs the runtime to us an http-header to identify the service handler. As each request will contain several http-headers, it also determines that it is the http-header "MyHeader" that should be used.

An example of the case where only the name of the criterion is shown is "Top-element name". This instructs the runtime to use the name of the top element of an XML document to identify the service handler. As each request can only contain one top-element of an XML document, no further qualification of the criterion is shown.

More information about selection criteria.

Service handler

[icon]

The bottom level of the structure shows the services that are offered for a specific value of the selection criterion the service is scoped by.

The service handler element determines the program that will be called for processing a request.

The text shown for the service handler elements contains two parts:

The name of the service handler - followed by a " :Value: " followed by the criterion value that means the service handler will be called.

When you add a service handler to the URL, you specify which service handler program that must handle the request. If you press "Update" for a service handler element in the structure, you will note that you can't change the values for the service handler (e.g. the implementation name of the program).

This is because the same handler can be placed several places in the service structure. As this is the case, changing the values for one service handler in the structure would mean that the changes would also be applied to other services in the tree.

The possible side effects are serious enough that the changes have been prohibited.

If you want to change an existing service handler, it is possible to do so. Use the "Handlers" button to access the general maintenance of the service handlers.

You have the option of declaring a service handler as Inactive. As this also will be true for all instances of the service handler in the service structure, this is also done in the service handler maintenance. The service handler will be marked with a little red x when the service handler is inactive: [icon]

When the service handler is inactive, the runtime will act as if there is no service handler specified for the criterion value.

You can use this if you temporarily want to make a service unavailable due to errors in the program - for instance if a version of the service handler containing an error has been deployed.

More information about service handlers.

Example

The screen-shot shows a service structure where two different service URLs can be used.

In the following description of the structure, the service URL "http://www.myserver.com/site/mysite/service/" will be used (See above).

The structure shows that a case where two separate URL extensions "file" and "soap" is specified.

The idea is that if you are calling a SOAP-based web service, you should use the URL:

http://www.myserver.com/site/mysite/service/soap

And if you calling a file-based service, you should use the URL:

http://www.myserver.com/site/mysite/service/file

The soap URL element uses SOAPAction criterion to identify the service handler to call.

If the SOAPAction header is "http://www.websydian.com/actions/CreateOrder", the Create Order service handler will be called.
If the SOAPAction header is "http://www.websydian.com/actions/GetCustomer", the Get Customer service handler will be called.

The file URL element first retrieves the http-header "WSCONTROL" and tries to identify a service handler based on this value.

If the http header WSCONTROL has the value "ALL", the "Import All Base Data" service handler is called
If the http header WSCONTROL has the value "CUSTOMER", the "Import Customers" service handler is called

If no handlers can be identified based on the WSCONTROL header, the URL criterion will be used to identify a service handler.

If the URL is http://www.myserver.com/site/mysite/service/all, the "Import All Base Data" service handler is called
If the URL is http://www.myserver.com/site/mysite/service/customers, the "Import Customers" service handler is called