The Web Service

One key aspect of the Web service is that it should be dynamic. Reports can be very different depending on various parameters of different type. The system must be able to handle every report type that can be produced from the data that is available at the different servers.

This section will describe the different parts of the Web service and how they work together.

Report Type

In the system a report that can be generated is described by a report type. A report type contains all the information that is necessary for the front end to present the report to the user and provide the possibility to enter values for the input parameters and send a generate report request to the service.

Parameters

Each report type can consist of zero or more input parameters. The parameters will determine on what data the report generation will be based, for example an organization number or a time interval.

Eight types of different parameter types were identified during the requirement gath-ering phase:

1. String type

A string type will represent all parameters that can be described by a simple string.

Examples can be names and addresses. Several restrictions can be set for a string type by the report creator. A maximal and minimal number of characters can be specified together with a regular expression that the string must match.

2. Integer type

Integer parameters such as organization numbers can be restricted by an upper and lower bound on its value.

3. Float type

A float type parameter can also be restricted by an upper and lower bound.

4. Date type

In order to represent dates as input parameters in a report, a date type has been defined. The report type creator can specify the earliest and latest date that the user can select.

5. List type

A list type can be restricted by the number of items that can be selected and submitted to the service. Two kinds of lists can exist in the system; a simple list and a dependent list. A simple list will be populated when the report description is requested, which is done by calling the SQL statement associated with the list type in the database. A dependent list can be populated dependent on the values of other parameters. This will be useful when the amount of data is too much for a single list.

If the data can be categorized the selections can be made in several steps. For example, if the goal is to choose a city, it would be unfeasible to list all cities that are available in the database. The list can be divided into one simple list and one dependent list where the simple list will contain the country names. Depending on what country is selected the dependent list will be populated with all cities in the selected country. A dependent list can be dependent on any number of parameters of any type.

6. Integer interval type

The integer interval type contains two integer types with upper and lower bounds on the interval length as additional restrictions.

7. Float interval type

The float interval type contains two float types and contain the same restrictions regarding the interval as the integer interval type.

8. Date interval type

The last parameter type is a date interval type which is used when a period of time is to be specified. The upper and lower bound on the interval length is specified in number of days.

In addition to the restriction of each parameter type described above, default values and help texts can be set which will help the user to enter the input parameter values.

Report request

When all required input parameters have been filled out by the user a report request object can be sent to the service. The report request contains all information that the service needs in order to generate the report file.

Access and administration

It is very important that users can not access report types that they are not allowed to access. The administration of access rights is done at the vendor level. Each report type contains information about which vendor offices are allowed to access the report type. All vendor offices have an administrator that can administrate the access rights to the reports at user level.

In addition to administration of report types a restriction on the data that the reports are generated from also exists. Portfolio links and data IDs are associated with the data that exists in the databases. A vendor link contains information about what data a vendor office has access to while data IDs can restrict the data at the user level. When these two restrictions are combined it is possible to determine what data a user has access to.

The interface

The interface is very important in SOA since it will describe the system and define what operations the service will supply. When a web service is designed and implemented two approaches can be considered. A top-down approach starts with a WSDL file and generate the stubs from that description. The bottom-up approach starts with the stubs and the WSDL will be generated from the stubs. We choose the top-down approach since we think that the Web service description is an integrated part of the design of the system.

The operations that are supported by the Web service are:

– getAvailableReportTypes

The purpose of the system is that users should be able to request reports without the need to contact any person at GE. In order to do so all reports that are available to the user must be listed at some point. This operation supplies that functionality. The request must contain an office ID together with a language code. The office ID will determine what report types should be included in the response and the language code will determine the language of the report types.

– getDataID

In order to supply the functionality to administrate data IDs this operation has been included. Based on the portfolio links and the vendor office ID it is possible to gather the available data IDs and return them to the requester.

– getDependentListData

This operation will populate a dependent list depending on the parameters sup-plied in the request. The populated list will be returned in the response.

– requestReport

The requestReport operation is used when one or several report files should be generated. A thorough explanation of how this process works is explained in the next section.

Figure 5.2: An overview of the elements in the request process.

– getReportRequestStatus

The generation of report files is an asynchronous process where the generation time can take from milliseconds up to several minutes. This operation will therefore return information about the report requests that have been issued earlier. The response will contain information about the status of the requests, time when the requests were performed and an estimate of when the generation will be finished.

– getReportFiles

When the report files have been generated by the service, invoking this operation will return the actual files that the generated report consists of.

– deleteReportRequest

A report request will automatically be deleted after three month or any other period of time that the administrator of the system chooses. This operation will delete the report immediately.

The request process

The system is developed to support multiple Web services working in collaboration in order to supply different kind of report types to the front end. A Web service endpoint is obtained from the UDDI registry and is invoked using the necessary credentials. The available report types are listed and all required parameters of the desired report type are filled in.

When a request to generate a report file is to be performed, a number of steps have to be executed. These steps are illustrated in figure 5.2 on page 62 and described bellow:

1. The client sends a request message to the service by invoking the requestReport operation described in the previous section. The request contains all parameters that the service needs in order to fulfill the request.

2. The message is put in a queue allowing the service to process the request when resources are available. Since the operation is asynchronous the client is not forced to wait for the operation to complete.

3. When a thread in the service is available it will wait until a message is available in the queue. The message will then be fetched from the queue for further processing.

4. A validation process will validate the report request against the report type stored in the database. The request must contain all required parameters and the values of each parameter must satisfy the conditions specified by the administrator when the report type was created.

5. If the validation process was successful the request will be inserted in the database.

When the information has been inserted, the stored procedure responsible for generating the report files will be invoked.

6. When the generation process is done an email, informing the user that the gen-eration has completed, will be sent to the client, given that an email address was provided in the request. An email will also be sent if the process fails at any step.

The client can request status about the progress of the request process before, during, and after the report files have been generated. The report files will be available for transfer when the generation is successfully finished. The files are transferred as MIME content in the SOAP response message.

The database

The database design is important since it plays a vital role in the system. The informa-tion about report types and requests is stored in the database together with a number of stored procedures that the system will use in the communication with the database.

Stored procedures are the only way the system can send and receive data to and from the database. This will eliminate the need to write long SQL-queries in the code and thereby achieve a better structure and code that is easier to maintain.

The database contains tables for every parameter type that was described previously.

The report types will be stored together with information about which offices have access to it. When a report request arrives to the service, it will be stored in the database in order to provide status information about the request. The stored procedures use that information in order to complete the generation of the report files. When the report is generated information about where the files are found in the file system is stored in the database.

Configuration

The system contains several configuration files where the administrator can set attributes that will affect the behavior of the system. The configurable settings describe for ex-ample how emails are handled, the amount of threads for handling report requests and connections to the database, and security configuration.

Security configuration The security is configured in several files. An input and output handler is defined for the Web service and these are configured according to the security that the administrator of the system chooses. In order to invoke the system the client and service alias and passwords are specified according to the generated key-store. The service is by default configured to use password digest, encryption and digital signatures on messages received.