Managing Web Services and Operations
Web Services Management
Manager Contents
Contents

Introduction
Basic Settings
Schema Configuration Settings
Default Schema Categories
Web Service Operations
Generating WSDL and XSD Schema Definitions

Introduction

Web Services are sets of operations that form an API (Application Programming Interface) that may be called across the intranet or Internet.  You may create many Web Services, each optimized for different web service consumers or applications. Use the Add button to add a new Web Service, optionally selecting an existing Web Service to copy initial settings from.

Basic Settings

When adding or editing a Web Service, the following fields are available:

  • Web Service - The name of the Web Service (100 characters max). This name is only used for locating and managing the Web Service within the CATSWeb Web Services Management application.
  • Service Name - The name of the Web Service as specified within the Web Services Definition Language (WSDL) representation of the service.
  • Description - A description of the Web Service (4000 characters max). The description is automatically included in the WSDL for the service.
  • Location - A URL that points to the Web Service.
  • WSDL File Name - The filename to use for WSDL files generated for the service (100 characters max). If you leave this blank, CATSWeb will choose a random name for the file at runtime. Allowing CATSWeb to choose a random name is the best option if many users will be creating WSDL files for the service at the same time.

    Back to Top

Schema Configuration Settings

The Schema Configuration Settings help determine how the WSDL and XML Schema Definitions (XSD) for the Web Service are generated. These settings are default settings for the service, but you may override them on an operation by operation basis. The following settings are available:

  • Element Complexity - XML schema elements may either be formatted as basic ("Simple") XML types (string, integer, etc.), or as complex types ("Typed") derived from the basic types, with application-specific metadata embedded. When a complex type is generated, much of the metadata comes from CATSWeb form designs that you have already created (list values, captions, field descriptions, etc.).

    Although the Typed output provides the most detailed information about the Web Service and its schemas, some software environments that consume Web Services (e.g. Microsoft .NET) may be confused by the rich information provided. The Simple output may instead be used in these cases. The resulting data structures are functionally the same in either case.
  • Enumerate Lists - If a field is bound to a list in CATSWeb, this setting determines whether or not the selection list values are enumerated in the schema, when Element Complexity is set to Typed. If the Element Complexity is set to Simple, this setting is ignored.
  • Verbosity - Specifies the amount of information that is included in the generated WSDL or XSD files. Lower verbosity settings cause less information to be included, while higher values cause more information to be included.
  • Mandatory Fields - Specifies how fields that have been designated as Mandatory in CATSWeb forms are represented in the generated WSDL or XSD files for AddEditDelete or other operations that have request schema derived from form definitions. "Any" is the default setting, as it allows mandatory fields to be represented as they are defined in the underlying form designs and metadata. "Any" should be used for most applications. Note that in WSDL and XSD, Mandatory is designated by a minOccurs value of "1".

    An example of an application in which a different setting might be desirable is an offline data entry scenario in which the offline utility requires the submission to be validated against schema. It may be preferred to bypass client-side mandatory field validation for some or all fields, and instead allow CATSWeb to perform this validation when the data is actually submitted to the Web Service. A setting of "None" would accomplish this. Note that CATSWeb always performs its submission validations, regardless of how the WSDL or XSD is represented.

    The available settings are:
    • None - Fields designated as Mandatory in CATSWeb forms, whether via Mandatory setting in the field definition (controlled by CATSWeb administrators) or the System Mandatory setting in the field definition (controlled by AssurX), are not designated as Mandatory in the WSDL or XSD.
    • User - Fields designated as Mandatory in CATSWeb forms via the Mandatory setting in the field definition (controlled by CATSWeb administrators) are designated as Mandatory in the WSDL or XSD. Fields designated as Mandatory in CATSWeb forms via the System Mandatory setting (controlled by AssurX) are not designated as Mandatory in the WSDL or XSD.
    • System - The converse of the User setting. Fields designated as Mandatory in CATSWeb forms via the System Mandatory setting in the field definition (controlled by AssurX) are designated as Mandatory in the WSDL or XSD. Fields designated as Mandatory in CATSWeb forms via the Mandatory setting (controlled by CATSWeb administrators) are not designated as Mandatory in the WSDL or XSD.
    • Any - The converse of the None setting. Fields designated as Mandatory in CATSWeb forms, whether via the Mandatory or System Mandatory settings, are designated as Mandatory in the WSDL or XSD.
  • Include Authentication Parameters - Specifies whether or not authentication (login) parameters are included in the XSD schema definitions. If the Web Service will exclusively use Windows Authentication (a.k.a. "NT Authentication"), authentication parameters are not required. These are provided automatically by the Windows operating system. Authentication parameters may still be desirable in a Windows Authentication implementation as they allow for impersonation.

    If the Web Service will be accessed without Windows Authentication, authentication parameters are required. They allow login information (employee ID, password) to be passed to the operation, or allow a CATSWeb session ID to be passed instead. One or the other are necessary for the authentication process to succeed.
  • Include Unused Fields - Specifies whether or not unused fields from a CATSWeb form are to be included in XSD schemas. An unused field is one with its order setting (field definitions page) set to zero.
  • Include Special Parameter Fields - If Yes, elements for some special API processing directives (e.g., disabling the normal E-mail notification message) are included in XSD schema definitions. If No, these special processing directives are omitted from the schema.
  • Request Element Ordering - Specifies whether the elements in the XSD schema definitions are ordered in accordance with the ordering specified in form designs, or in a fixed order that ignores form design ordering. CATSWeb Web Service operations will accept elements in any order, so this setting is largely a choice of style or preference for the user of the schema.

    Back to Top

Default Schema Categories

The Default Schema Categories section allows you to choose which CATSWeb form (category) will be used to provide schema information for operations that pertain to that type of record. For example, if you choose "Basic Issue Form" as the Issue Category, the field set, captions, descriptions, list values, etc. from that form will be used in the schema definitions for the AddEditDeleteIssue operation.

Web Service Operations

The Web Service Operations section lists all of the operations that may be included in the Web Service. The WSDL for the Web Service only contains the operations that have been included, and presents the operations in the order specified. Settings for the individual operations may be changed by clicking on the operation name.

The Include or Exclude box provides a variety of ways of including or excluding operations en masse. Operations that return data (Get or Query operations) are implemented in pairs: one operation returns data in the format preferred by Microsoft .NET (DataSets), and the other returns data in the format preferred by J2EE and other consumers (XML String). If all the consumers of the Web Service have the same data format preference, operations using the other data format can be excluded to simplify the Web Service's WSDL. Operations that primarily manipulate data rather than retrieve it (AddEditDelete and similar operations) are platform agnostic, the data format is already optimal for all platforms.

When editing an Operation, many of the settings are similar to those for the Web Service. Unique settings include:

  • Include in Service - Specifies whether or not the Operation is included in the WSDL for the Web Service.
  • Order - The order that the Operation is listed within the WSDL for the Web Service.
  • Schema File Name - Similar to the WSDL File Name, this can be used to specify a particular name for the XSD schema file generated via the Generate Schema for Operation link.
  • API Object - The object in the CATSWeb COM API that the Operation maps to.
  • API Function - The function (method) in the CATSWeb COM API that the Operation maps to.

Back to Top

Generating WSDL and XSD Schema Definitions

WSDL for the Web Service may be generated via the Generate WSDL for Web Service link at the top of the Web Service Edit form. XSD for the request and response messages in a particular Web Service Operation may be generated via the Generate Schema for Operation link at the top of the Web Service Operation Edit form.

Back to Top