setRequestRemoteReferenceStatus

Purpose

This operation updates the status of a remote reference in a request in PPM Center, as illustrated in the following example:

Function

This operation provides the following functions.

Update the status of the specified remote reference (the Source), in a PPM request (the Receiver). Remote reference is identified by the reference ID and server URL.
Execute the workflow transition, if the given value of 'Status' exactly matches the transition name as appeared on the action buttons (case sensitive). This function is supported for backward compatibility. If the status does not match any of the transition names, no workflow transition will be performed. If you only want to perform workflow transition, use the executeWFTransitions operation.
Update the simple fields of the request. This function is provided for backward compatibility. It is recommended to use the setRequestFields operation to update simple fields.

Limitations

This operation has the following limitations:

Only updates the status field of the remote reference. There is no operation to update the other remote reference fields.
No security check on workflow transition. Even though the user cannot perform the transition from PPM Center standard interfaces, the transition will be performed with this Web service call, as long as the status value matches the transition name.
Even when there is no simple field change, a simple field collection is still required when you call this operation.

Note: For more information, see:

setRequestFields - set the value for simple fields in the request.
executeWFTransitions - execute work flow transition for the request.

Related Information

The following data types:

Input

The following inputs are required for this operation:

Receiver ID, which is the Identifier for the request in PPM Center.
Source ID, which is to identify the remote reference. ServerURL is required.
Status
Simple field array. Even if there is no update on simple fields, it is still required.

Return

Upon success, the operation returns the ID of the request.

Java Interface

SetRequestRemoteReferenceStatusResponseDocument setRequestRemoteReferenceStatu(SetRequestRemoteReferenceStatusDocument in)

Parameters	Description
SetRequestRemoteReferenceStatusDocument	Wrapper of the request ID, source ID, status, and the SimpleField[].
SetRequestRemoteReferenceStatusResponseDocument	Wrapper of the return code of this operation.

Java Examples

Example: update a remote reference of an existing request.

public class ExampleSetRequestFields {
. . .
    private void setRequestFields(String serviceURL, String
requestId) throws Exception {
. . .
        // create the array of changed fields
        SimpleField[] fields = new SimpleField[2];

        // Set field 'Description'
        SimpleField field_A = SimpleField.Factory.newInstance();
        field_A.setToken("REQ.DESCRIPTION");
        field_A.setStringValue1Array(new String[] { "WebService
Test (Update)" });
        fields[0] = field_A;

        // Set field 'Department'
        SimpleField field_B = SimpleField.Factory.newInstance();
        field_B.setToken("REQ.DEPARTMENT_NAME");
        field_B.setStringValue1Array(new String[] { "IS" });
        fields[1] = field_B;

        // Get web service
        DemandServiceStub stub = new DemandServiceStub(ctx,
serviceURL);
        // Construct message to send
        SetRequestFieldsDocument inDoc =
SetRequestFieldsDocument.Factory.newInstance();
        SetRequestFieldsDocument.SetRequestFields
setRequestFields = inDoc
                .addNewSetRequestFields();
        setRequestFields.setRequestId(reqId);
        setRequestFields.setFieldsArray(fields);
. . .
}
}

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 {http://mercury.com/ppm/dm/service/1.0}fields	Missing simple fields.	Although this operation is not designed to update the request simple fields, a simple field array is required when calling this operation. Refer to the example provided in this section for how to add an empty simple field array.
N/A	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 "{http://mercury.com/ppm/common/1.0}token"(line -1, col -1, in SOAP-message)	Missing token.	For a simple field, the token cannot be NULL. If for any reason we have to leave the token empty (for example, in case we have to supply an empty simple field array), we should set the token to an empty string.
N/A	An error occurred when updating remote reference status -java.lang.Exception: Error 3: Error applying remote reference: cannot apply a remote reference with NULL server URL	Missing ServerURL.	For identifying a remote reference, the ServerURL field of the Identifier of the remote reference is required.
KNTA-11186	//mercury.com/ppm/dm/1.0}id" start tag, found "{http://mercury.com/ppm/dm/1.0}serverURL" start tag (line -1, col -1, in SOAP-message).	You have not provided the request ID.	Provide the request ID.
N/A	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 {http://mercury.com/ppm/dm/service/1.0}receiver	You have not set the receiver ID.	Provide the request ID for the receiver.
N/A	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 {http://mercury.com/ppm/dm/service/1.0}source	You have not set the Source.	Provide the Identifier with ID and server URL.
N/A	//mercury.com/ppm/dm/1.0}id" start tag, found "{http://mercury.com/ppm/dm/1.0}serverURL" start tag (line -1, col -1, in SOAP-message).	You have not provide the request ID.	Provide the reference request ID.
N/A	An error occurred when updating remote reference status -java.lang.Exception: Error 3: Error applying remote reference: cannot apply a remote reference with NULL server URL	You have not set the Server URL.	Provide the server URL for the identifier.
N/A	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 {http://mercury.com/ppm/dm/service/1.0}status	You have not set the Status.	Provide the status for the remote reference.