Approval Service Operations
This section describes the various operations that the Approval service provides.
getPendingApprovals
This operation returns a list of the approval requests that are awaiting the authenticated user's approval (where the authenticated user is the user who invoked the getPendingApprovals service). You can optionally filter the list by object type and submission date.
Input Message
Parameter Name | Description |
locationCentraSite | (Optional). (String). The address of the CentraSite registry or repository from which you want to retrieve the approval requests. The registry or repository runs at the following URL: http://server:port/CentraSite/CentraSite Where server is the machine on which the CentraSite registry or repository is running and port is the port on which Apache is configured to listen for requests (port 53307 if CentraSite is configured to use the default Apache port number). If you do not specify locationCentraSite, the Approval service uses the following default URL: http://localhost:53307/CentraSite/CentraSite |
objectType | (Optional). (String). (Array). If you want to retrieve approval requests for only certain object types, use this element to specify the types by name. Note: You must specify the type's schema name, not its display name. You can find the schema name on the type's Asset Type Details page in CentraSite Control. |
submittedAfter | (Optional). (DateTime). If you want to retrieve requests after a particular date, specify that date in this element. |
submittedBefore | (Optional). (DateTime). If you want to retrieve requests before a particular date, specify that date in this element. |
locale | (Optional). (String). The locale in which you want the results to be returned. |
scroll | (Optional). (Scroll). If you want to return a particular block of entries from the result set, specify the following values in the scroll element. |
start | (Integer). The first entry that you want to include in the block (where 1 represents the first entry in the entire result set). |
number | (Optional). (Integer). The number of entries to be returned in the block of approval requests. If you specify a start value, but no number value, then the remainder of the result set is returned. |
Output Message
getApprovalRequests
This operation returns the list of requests that the authenticated user has submitted for approval (where the authenticated user is the user who invoked the getApprovalRequests service). You can optionally filter the list by object type, submission date, and approval status.
Input Message
Parameter Name | Description |
locationCentraSite | (Optional). (String). The address of the CentraSite registry or repository from which you want to retrieve the approval requests. The registry or repository runs at the following URL: http://server:port/CentraSite/CentraSite Where server is the machine on which the CentraSite registry or repository is running and port is the port on which Apache is configured to listen for requests (port 53307 if CentraSite is configured to use the default Apache port number). If you do not specify locationCentraSite, the Approval service uses the following default URL: http://localhost:53307/CentraSite/CentraSite |
status | (Optional). (String). If you want to retrieve only requests with a specified approval status, specify one of the following values: |
Specify... | To retrieve... |
In Progress | Approval requests that are pending (awaiting approval). |
Approved | Approval request that have been approved (excluding requests that were auto-approved). |
Rejected | Approval requests that have been rejected. |
No Action | Approval requests that were auto-approved. |
objectType | (Optional). (String). (Array). If you want to retrieve approval requests for only certain object types, specify the types by name in this element. Note: You must specify the type's schema name, not its display name. You can find the schema name on the type's Asset Type Details page in CentraSite Control. |
submittedAfter | (Optional). (DateTime). If you want to retrieve requests after a particular date, specify that date in this element. |
submittedBefore | (Optional). (DateTime). If you want to retrieve requests before a particular date, specify that date in this element. |
locale | (Optional). (String). The locale in which you want the results returned. |
scroll | (Optional). (Scroll). If you want to return a particular block of entries from the result set, specify the following values in the scroll element: |
start | (Integer). The first entry that you want to include in the returned block of approval requests (where 1 represents the first entry in the entire result set). |
number | (Optional). (Integer). The number of entries to be returned in the block of approval requests. If you specify a start value, but no number value, then the remainder of the result set is returned. |
Output Message
getApprovalActions
This operation returns detailed information about specified approval requests.
Input Message
Parameter Name | Description |
locationCentraSite | (Optional). (String). The address of the CentraSite registry or repository from which you want to retrieve the approval requests. The registry or repository runs at the following URL: http://server:port/CentraSite/CentraSite Where server is the machine on which the CentraSite registry or repository is running and port is the port on which Apache is configured to listen for requests (port 53307 if CentraSite is configured to use the default Apache port number). If you do not specify locationCentraSite, the Approval service uses the following default URL: http://localhost:53307/CentraSite/CentraSite |
approvalRequestKeys | (String). (Array). he keys for the approval requests whose details you want to retrieve. |
locale | (Optional). (String). The locale in which you want the results returned. |
Output Message
approve
This operation approves specified approval requests.
Input Message
Parameter Name | Description |
locationCentraSite | (Optional). (String). The address of the CentraSite registry or repository on which the approval requests reside. The registry or repository runs at the following URL: http://server:port/CentraSite/CentraSite Where server is the machine on which the CentraSite registry or repository is running and port is the port on which Apache is configured to listen for requests (port 53307 if CentraSite is configured to use the default Apache port number). If you do not specify locationCentraSite, the Approval service uses the following default URL: http://localhost:53307/CentraSite/CentraSite |
approvalRequestKeys | (String). (Array). The keys for the requests that are to be approved. |
comment | (Optional). (String). A comment from the approver. |
locale | (Optional). (String). The locale in which you want the results returned. |
Output Message
ApprovalRequestList (contains the requests that were approved)
reject
This operation rejects the specified approval requests.
Input Message
Parameter Name | Description |
locationCentraSite | (Optional). (String). The address of the CentraSite registry or repository on which the approval requests reside. The registry or repository runs at the following URL: http://server:port/CentraSite/CentraSite Where server is the machine on which the CentraSite registry or repository is running and port is the port on which Apache is configured to listen for requests (port 53307 if CentraSite is configured to use the default Apache port number). If you do not specify locationCentraSite, the Approval service uses the following default URL: http://localhost:53307/CentraSite/CentraSite |
approvalRequestKeys | (String). (Array). The keys for the requests that are to be rejected. |
comment | (Optional). (String). A comment from the approver. |
locale | (Optional). (String). The locale in which you want the requests returned. |
Output Message
ApprovalRequestList (contains the requests that were rejected)
getApprovalHistory
This operation returns entries from the approval history log based on specified search criteria. If the user belongs to the CentraSite Administrator role, he or she receives all entries in the log. If the user belongs to the Organization Administrator role, he or she receives all log entries for his or her organization. Otherwise, the user receives only those approval requests that he or she has submitted.
Input Message
Parameter Name | Description |
locationCentraSite | (Optional). (String). The address of the CentraSite registry or repository on which the approval history log resides. The registry or repository runs at the following URL: http://server:port/CentraSite/CentraSite Where server is the machine on which the CentraSite registry or repository is running and port is the port on which Apache is configured to listen for requests (port 53307 if CentraSite is configured to use the default Apache port number). If you do not specify locationCentraSite, the Approval service uses the following default URL: http://localhost:53307/CentraSite/CentraSite |
status | (Optional). (String). If you want to retrieve only requests with a specified approval status, specify one of the values shown here: |
Specify... | To retrieve... |
In Progress | Approval requests that are pending (that is, awaiting approval). |
Approved | Approval requests that have been approved (excluding requests that were auto-approved). |
Rejected | Approval request that have been rejected. |
No Action | Approval requests that were auto-approved. |
objectType | (Optional). (String). (Array). If you want to retrieve approval requests for only certain object types, specify the types by name in this element. Note: You must specify the type's schema name, not its display name. You can find the schema name on the type's Asset Type Details page in CentraSite Control. |
submittedAfter | (Optional). (DateTime). If you want to retrieve requests after a particular date, specify that date in this element. |
submittedBefore | (Optional). (DateTime). If you want to retrieve requests before a particular date, specify that date in this element. |
locale | (Optional). (String). The locale in which you want the results returned. |
scroll | (Optional). (Scroll). If you want to return a specified block of entries from the result set, specify the following values in the scroll element. |
start | (Integer). The first entry that you want to include in the block (where 1 represents the first entry in the entire result set). |
number | (Optional). (Integer). The number of entries to be returned in the block. If you specify a start value, but no number value, the remainder of the result set is returned. |
Output Message
revertPendingStateChange
This operation removes an object that is pending approval from the approval system, and returns the object to its prior lifecycle state. Only users that belong to the CentraSite Administrator role can execute this operation.
Input Message
Parameter Name | Description |
locationCentraSite | (Optional). (String). The address of the CentraSite registry or repository on which the object resides. The registry or repository runs at the following URL: http://server:port/CentraSite/CentraSite Where server is the machine on which the CentraSite registry or repository is running and port is the port on which Apache is configured to listen for requests (port 53307 if CentraSite is configured to use the default Apache port number). If you do not specify locationCentraSite, the Approval service uses the following default URL: http://localhost:53307/CentraSite/CentraSite |
key | (String). The key of the object whose state you want to revert. |
Output Message
revertPendingStateChangeResponse
Parameter Name | Description |
revertedState | (String). The lifecycle state to which the object was reverted by the revertPendingStateChange operation. For example, if you executed this operation on an object whose state was pending a change from state A to state B, the operation would return state A in the revertedState parameter. |
ApprovalRequestList
This data structure holds a list of approval requests.
Parameter Name | Description |
ApprovalRequest[] | An array of ApprovalRequest elements. Each ApprovalRequest entry in the array represents one approval request and has the following structure: |
name | (Optional). (String). The name of the approval request (as specified by the Approval Flow Name parameter in the approval policy action). |
requestor | (String). The key that identifies the user who submitted the approval request. |
| registryObject | (String). The key of the registry object on which the user is requesting approval. |
| requestType | (String). The type of event that triggered the approval request (for example, Pre-State Change). |
| reasonForRequest | (Optional). (String). The remark (if any) that was assigned to the request by the approval policy action. |
| key | (String). The approval request's key. |
| status | (String). The state of the approval request. The value of this element will be one of the following: |
| Value | Description |
| In Progress | The approval request is pending (that is, awaiting approval). |
| | Approved | The approval request has been approved. |
| | Rejected | The approval request has been rejected. |
| | No Action | The approval request was auto-approved. |
| submittedDate | (DateTime). The date on which the request was submitted for approval. |
scroll | (Optional). (String). The scroll values, if any, that were submitted when the operation that produced this ApprovalRequestList was invoked. |
start | (Integer). The start value that was specified in the input message when the operation was invoked. |
number | (Integer). (Optional). The number value that was specified in the input message when the operation was invoked. |
count | (Number). The number of approval requests in the entire result set. |
ApprovalActionResult
This data structure holds the details for a specified set of approval requests.
Parameter Name and Description |
ApprovalActionList[] | |
An array of ApprovalActionList elements. Each ApprovalActionList entry in the array holds the details for one approval request and has the following structure: |
ApprovalAction[]
ApprovalRequestKey
| (String). The key to the approval request. An array of ApprovalAction elements. Each ApprovalAction element in the array holds the approval details for one approver. This array contains one entry for each approver in the approver group. Each ApprovalAction element has the following structure: |
| approver | (String). The key that identifies the user who is the approver. |
| status comment | (Optional). (String). A remark from the approver (typically indicating why he or she approved or rejected the request). |
| | (String). The approver's decision on the request. Possible values are shown below:  Pending The approver has not taken action on the request. Approved The approver approved the request. Rejected The approver rejected the request. No Action The request has been approved or rejected, however, this approver did not make the approval decision on the request. This can also indicate that the request was auto-approved. |