Understanding Query Access Service

This chapter discusses:

Click to jump to parent topicQuery 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:

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

Click to jump to top of pageClick to jump to parent topicQuery Creation Services

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

Service Operation Name

Description

QAS_RECORDS_OPER

Returns the list of records, along with descriptions, that are accessible to the user.

QAS_HIERARCHY_RECORDS_OPER

Returns the list of hierarchy records, if any, along with their descriptions.

QAS_RELATED_RECORDS_OPER

Returns the list of related records of all the fields in the record.

QAS_RECORD_DEFN_OPER

Returns the definition of a given record, including field descriptions and key information.

QAS_TREES_OPER

Returns the list of PeopleSoft trees that are accessible to the user.

QAS_TREE_DETAILS_OPER

Returns the tree details, including setID, effective date, and the list of all the nodes.

QAS_FIELDS_OPER

Returns the fields from all records that are accessible to the user.

QAS_FIELD_PROPS_OPER

Returns the properties of a given field.

QAS_QUERY_DETAILS_OPER

Returns the complete details of an existing query in XML format.

QAS_SAVE_QUERY_OPER

Validates and verifies XML-format query and saves the query in the PeopleSoft database.

QAS_QUERY_DELETE_OPER

Deletes the query from the PeopleSoft database.

Click to jump to top of pageClick to jump to parent topicQuery Security Services

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

Service Operation Name

Description

QAS_AUTHTOKEN_OPER

Returns the user ID based on the PS Token passed in.

QAS_LISTROLE_OPER

Returns the list of roles, along with descriptions.

QAS_LISTUSER_OPER

Returns the list of users, along with descriptions.

QAS_LISTROLEUSERS_OPER

Returns the list of users for a given role, along with descriptions.

QAS_LISTUSERROLES_OPER

Returns the list of roles for a given user, along with descriptions.

QAS_LOGIN_OPER

Enables the client application to sign on to the PeopleSoft database.

Click to jump to top of pageClick to jump to parent topicQuery Metadata Services

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

Service Operation Name

Description

QAS_LISTQUERY_OPER

Returns the list of queries, along with the query descriptions, and owner type.

QAS_LISTQUERYPROMPTS_OPER

Returns a list of prompts used in a specific query.

QAS_LISTQUERYFIELDS_OPER

Returns a list of fields for a given query.

QAS_GETXLAT_OPER

Returns the translate value for a given field.

QAS_GETPROMPTTABLEVALUES_OPER

Returns a list of field values for a given prompt.

Click to jump to top of pageClick to jump to parent topicQuery 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:

Service Operation Name

Description

QAS_CANCELQUERY_OPER

Returns the status of query cancellation.

QAS_QUERYSTATUS_OPER

Returns query execution status.

QAS_EXECUTEQRYSYNC_OPER

Returns query result.

QAS_EXECUTEQRYASYNC_OPER

Returns query result.

QAS_EXECUTEQRYSYNCPOLL_OPER

Runs the query through process scheduler and returns the query instance ID. The service operation QAS_GETQUERYRESULTS_OPER is used to retrieve the results.

QAS_GETQUERYRESULTS_OPER

Used to return the query results when the query is executed on the PeopleSoft database using QAS_EXECUTEQRYSYNCPOLL_OPER.

Click to jump to parent topicQAS Web Service

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

Click to jump to top of pageClick to jump to parent topicUnderstanding 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 Using the Service Configuration Page to Set 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 Using the Service Configuration Page to Set Service Configuration Properties.

Click to jump to top of pageClick to jump to parent topicWSDL 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.

Click to jump to top of pageClick to jump to parent topicMessage 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.

Click to jump to top of pageClick to jump to parent topicSOAP 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.

Click to jump to parent topicUse Cases

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

Click to jump to top of pageClick to jump to parent topicCreating 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.

Click to jump to top of pageClick to jump to parent topicExecuting 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.