getRequests

Purpose

This operation reads the information of a request in PPM.

Function

This operation reads the content of a request or a list of requests, identified by request IDs in PPM.

The following content of a request can be retrieved through this operation:

Simple Fields, defined in request header type, request type, or field group if applicable
Field of Table Component
Note
FieldChangeNotes
References, except remote references

All reference types are converted to URL references. See the following list for details:

Attachment

URL name is the attachment name, and the URL hyperlink points to the URL to access the attachment download.
Package Reference

URL name is in the format of "Package <package ID> on localhost," and the URL hyperlink points to the URL to access the package.
Program Reference

URL name is in the format of "Program <program name> on localhost," and the URL hyperlink points to the URL to access the program.
Project Reference

URL name is in the format of "Project <project name> on localhost," and the URL hyperlink points to the URL to access the project.
Task Reference

URL name is in the format of "Task <task name> on localhost," and the URL hyperlink points to the URL to access the task.
Request Reference

URL name is in the format of "Request <request ID> on localhost," and the URL hyperlink points to the URL to access the request.
URL Reference

Limitations

This operation has the following limitations:

Does not read remote references, which can be added to a request when creating the request by using the createRequest operation.
For attachments, this operation does not return the attached document, but rather the URL pointing to the document on the PPM server.
No additional security check. After the user passes authentication, the user can read any request even if the user does not have access to that request.

Related Information

The following data types:

Input

A collection of request IDs

Return

A collection of the Request objects. If the specified request ID does not exist in PPM Center, the operation is ignored and no error is generated.

Java Interface

GetRequestsResponseDocument getRequests(GetRequestsDocument in)

Parameters	Description
GetRequestsDocument	Wrapper of the collection of request identifiers, or Identifier[].
GetRequestsResponseDocument	Wrapper of the collection of request objects, or Request[].

Java Examples

Example: get data for a single request.

ExampleGetRequests01

public class ExampleGetRequests01{
. . .
   private void getRequests(String serviceURL, String
requestId) throws Exception {

       // construct the Identifier array
       Identifier[] ids = new Identifier[1];
       ids[0] = Identifier.Factory.newInstance();
       ids[0].setId(requestId);
       // get Webservice handler
       DemandServiceStub stub = new DemandServiceStub(ctx,
serviceURL);
       // Construct message to send
       GetRequestsDocument inDoc =
GetRequestsDocument.Factory.newInstance();
       GetRequestsDocument.GetRequests getRequests =
inDoc.addNewGetRequests();
       getRequests.setRequestIdsArray(ids);
. . .
}
}

Example: get data for a list of request IDs

. . .
    private void getRequests(String serviceURL, String[]
requestIds) throws Exception {
       // construct the Identifier array
       Identifier[] ids = new Identifier[requestIds.length];
       for (int i = 0; i < requestIds.length; i++) {
           ids[i] = Identifier.Factory.newInstance();
           ids[i].setId(requestIds[i]);
       }
       // get Webservice handle
       DemandServiceStub stub = new DemandServiceStub(ctx,
serviceURL);
       // Construct message to send
       GetRequestsDocument inDoc =
GetRequestsDocument.Factory.newInstance();
       GetRequestsDocument.GetRequests getRequests =
inDoc.addNewGetRequests();
       getRequests.setRequestIdsArray(ids);
. . .
    }
}

Errors and Exceptions

Message Code	Message	Cause(s)	Possible Corrective Action
KNTA-11186	Internal error has occurred while calling PPM Web Service. Contact PPM support with the detail information if the problem persists. (KNTA-11186) Details: Missing required element.	You have not set the request ID.	Provide a request ID for the request.
N/A	An error occurred when reading requests Open API Exception 9: Request with ID 30392 was not found in the system. Import was not performed.	The request ID does not exist on the PPM server.	Provide an existing request ID for the request.
KNTA-11186	Internal error has occurred while calling PPM Web Service. Contact PPM support with the detail information if the problem persists. (KNTA-11186) Details: Non digit data was set for number field. Original exception message: For input string: "30362A".	The request ID value you provide is invalid.	The request ID value has to be a numeric value. Correct the value and try again.