Understanding Query Access Service

This chapter discusses:

• Query Access Service (QAS) operations

• QAS Web Service

• Use cases

Query Access Service Operations

To enable external applications to access PeopleSoft Query, a number of service operations are available. Depending on the application, the external application will need to use several service operations in combination. The service operations for QAS are part of the service QAS_QRY_SERVICE.

QAS service operations are grouped into the following categories to help describe the service operations:

• Query Creation Services (QCS)

• Query Security Services (QSS)

• Query Metadata Services (QMS)

• Query Execution Services (QES)

Note. No processing or security is dependent on the categories; they are simply groupings for describing the service operations.

Query Creation Services

Query creation services are used by client applications to create and save a new query. This table lists the Query Creation Services:

Query Security Services

Query security services are used to identify users and roles. This table lists the Query Security Services:

Query Metadata Services

Query metadata services are used to extract application data from the PeopleSoft database. This table lists the Query Metadata Services:

Query Execution Services

Query Execution Services are used to run the query from a third-party application. This table lists service operations used to execute a query:

QAS Web Service

This section provides an overview of the QAS web service named QAS_QRY_SERVICE and discusses:

• WSDL (Web Services Description Language) document

• Message schema

• SOAP template

Understanding QAS_QRY_SERVICE

Services are used to logically group a set of service operations. The service QAS_QRY_SERVICE contains all of the service operations for QAS. When you publish a web service, a WSDL document is created containing all of the selected service operations as well as the endpoints based on the service configuration.

QAS_QRY_SERVICE is delivered as a restricted service. Only a user with the Peoplesoft Administrator role can make changes to the restricted state.

See Setting Service Configuration Properties.

See Restricting and Enabling Write Access to Service Definitions.

This diagram illustrates how a client application consumes the web service:

Providing a web service

The published web service is stored in the WSDL Repository. Client applications consume the WSDL by accessing the WSDL URL from the repository. The WSDL for QAS_QRY_SERVICE is delivered and updated with the appropriate WSDL Repository location whenever the target location is updated on the Service Configuration page (Select PeopleTools, Integration Broker, Configuration, Service Configuration).

See Setting Service Configuration Properties.

WSDL Document

To view the generated WSDL Repository for the QAS_QRY_SERVICE, click the View WSDL link on the service page (select PeopleTools, Integration Broker, Integration Setup, Services).

All of the service operations contained in the WSDL are listed in the Exported Service Operations section. Use the View WSDL link to view the WSDL document.

Message Schema

The WSDL document is created using the request and response message schemas for each service operation. To view the message schema, select PeopleTools, Integration Broker, Integration Setup, Messages and select the message to view. Select the Schema tab to view the schema.

SOAP Template

For each service operation, you can use the Generate SOAP Template utility to generate SOAP message templates for request messages, response messages, and fault messages found in the WSDL document. The generated SOAP template will include WS-Security SOAP Header tags. You can then use the templates to test SOAP messages in your third-party application.

Note. WS-Security should be used with all QAS service operations.

See Implementing Web Services Security.

Use Cases

This section discusses the two most common use cases for QAS::

• Create a Query

• Execute a Query

Creating a Query

QAS provides several service operations that can be used by an external application to access the PeopleSoft application database to select records and fields to create a valid PeopleSoft Query. Creating a query involves several steps, some of which do not require access to the PeopleSoft records, fields, and trees and therefore do not have associated service operations. This diagram illustrates the steps and corresponding service operation that can be used to access the PeopleSoft database information:

Steps to create a query

You can use QAS_RECORDS_OPER, QAS_RECORD_DEFN_OPER, QAS_RELATED_RECORDS_OPER, and QAS_HIERARCHY_RECORDS_OPER to select records.

QAS_FIELDS_OPER and QAS_FIELD_PROPS_OPER can be used to help select the fields and prompts to add to the query content.

QAS_TREE_OPER and QAS_TREE_DETAILS_OPER can be used when your selection criteria uses trees.

The QAS_SAVE_QUERY_OPER is used to save a query definition to the PeopleSoft database.

Executing a Query

To execute an existing query in the PeopleSoft database, the external application will use Query Metadata Services, Query Execution Services, and possibly the Query Result Service. This diagram illustrates the steps and corresponding service operations that can be used to execute a PeopleSoft query and retrieve the results:

Steps to execute a query

To execute a query, you will need to know the query name. QAS_LISTQUERY_OPER, QAS_LISTQUERYFIELDS_OPER, and QAS_QUERY_DETAILS_OPER can be used to help select the query name.

For queries containing prompts, use QAS_GETPROMPTTABLEVALUES_OPER, QAS_GETXLAT_OPER, and QAS_LISTQUERYPROMPTS_OPER to identify the prompts and obtain a list of values.

You can also filter fields to be retuned in the query results using QAS_LISTQUERYFIELDS_OPER.

You can select how you want to execute the query and use the appropriate service operation.

For synchronous poll execution, you will use QAS_GETQUERYRESULTS_OPER to retrieve the results.

You can invoke QAS_CANCELQUERY_OPER after obtaining the query result to clean up the PSQASRUN and IB tables.

You can check the query status using QAS_QUERYSTATUS_OPER.