This document contains the following topics:
The Approval service provides a set of operations that enables you to programmatically interact with CentraSite's approval system. Using the Approval service, you can develop client applications that let users view requests that they have submitted for approval and let approvers accept or reject these requests.
The WSDL for the Approval service is located here:
http://server:port/wsstack/services/ApprovalService?wsdl
Where server is the machine on which the Software AG Runtime is running and port is the port on which Software AG Runtime is listening (port 53307 if CentraSite is configured to use the default Software AG Runtime port number).
getPendingApprovals
getApprovalRequests
getApprovalActions
approve
reject
getApprovalHistory
revertPendingStateChange
This section describes how to use the Approval service to perform common approval-related tasks.
The following sections provide general information about using the operations in the Approval service.
The Approval service returns results that are specific to the authenticated user (i.e., the user who invokes the operation). For example, when a client application invokes the getPendingApprovals operation, the operation returns the set of approval requests that require the authenticated user's approval.
The authenticated user is identified by the basic http authentication credentials that the client application provides when it invokes an operation in the Approval service. The supplied credentials must identify an active user account on the instance of CentraSite to which the client application is connecting. If the client application submits invalid credentials, the Approval service will return a SOAP fault.
All of the operations provided by the Approval service have an input
parameter called locationCentraSite. This parameter
identifies the address of the CentraSite registry/repository whose approval
log is to be queried. A client application must specify the
locationCentraSite parameter if the registry/repository
is running anywhere other than its default location (i.e., port 53307 on the
machine where the Approval service is running).
If the registry/repository is running at its default location, a
client is not required to specify the locationCentraSite
parameter.
You use the getApprovalRequests operation to
retrieve the list of approval requests that the authenticated user has
submitted to CentraSite. By default, this operation returns all of
the approval requests that a user has submitted. However, you can optionally
set the objectType,
submittedAfter, submittedBefore,
and/or status parameters to filter the list by the
following criteria:
The type of object on which the request was submitted
The time period during which the request was submitted
The status of the request (e.g., retrieve only those requests that have not yet been approved)
You would use this operation, for example, to show users a list of their requests that are pending approval.
Tip:
This operation provides functionality like that of the
Approval Requests list in CentraSite Control. See the
topic Reviewing Requests that You Have Submitted for
Approval in the section Using Approval Policies of
the document Working with Design/Change-Time Policies for
details.
The getApprovalRequests operation (and
other operations provided by the Approval service) returns an
ApprovalRequestList
message. This message contains an array of
ApprovalRequest elements. Each ApprovalRequest element
in the array represents a single approval request and contains the following
information:
The key of the approval request object (this key is required to perform operations that act directly on a specific approval request)
The key of the user who submitted the approval request
The date on which the approval request was submitted
The key of registry object for which the approval request was submitted
The type of object for which the approval request was submitted
The status of the request
Remarks, if any, that were submitted with the approval request
The approval requests in the array are not sorted.
The ApprovalRequestList message also
returns an attribute called count, which indicates the
total number of approval requests in the result set. If the operation did not
find any approval requests that satisfied the operation's criteria, there will
be no elements returned in ApprovalRequest[] and the
count value will be zero.
If you want to receive the result set a few entries at a time instead
of all at once, you can use the scroll parameter in the
request message to specify which block of entries you want the operation to
return. For more information about using the scroll
parameter, see Scrolling through the List of
Returned Approval Requests.
Once you have an ApprovalRequestList, you can use the getApprovalActions operation to obtain detailed information about the approvers associated with any request in the list.
The getApprovalActions operation takes an approval request key as input (which you can get from the ApprovalRequestList) and returns the set of approvers associated with the specified request. (You can specify multiple keys if you want to get the details for multiple approval requests.)
The getApprovalActions operation returns
an ApprovalActionResult
message. The ApprovalAction[] array in this message
identifies the set of approvers associated with a particular approval request.
Each ApprovalAction element in this array contains the
following information:
The key for the approver (i.e., the key to the User object that represents the approver)
The status of the approver's action on this request, as follows
If the request has not yet been processed to completion (i.e., it has not yet been approved or rejected) and the approver has not taken any action on the request, the status will be "Pending".
If the approver has approved the request, the status will be "Approved".
If the approver has rejected the request, the status will be "Rejected".
If the request has been processed to completion (i.e., it has been approved or rejected), approvers who did not make the approval decision will have the status "No Action". (If the approval request was auto-approved, all of the approvers will have the status "No Action".)
Tip:
This operation provides functionality like that of the
Approval Requests list when you use CentraSite Control to
display the details for an approval request. See the topic Reviewing
Requests that You Have Submitted for Approval in the section
Using Approval Policies of the document Working
with Design/Change-Time Policies for details.
To enable a user to approve or reject a request, do the following:
Use the getPendingApprovals operation to obtain the list of requests that require the user's approval.
Apply the approve or reject operation to the requests in the list according to the approval decisions that the user makes.
When you invoke the approve or reject operation, you must specify the key of the approval request on which the operation is to act. You can obtain this key from the ApprovalRequestList message that was returned by the getPendingApprovals operation.
Note:
You can apply the approve or reject operation to a single approval
request or to multiple requests.
The approve and reject operations return an ApprovalRequestList message. This message will contain the approval requests that were approved or rejected by the operation.
For more information about working with the contents of the ApprovalRequestList, see The ApprovalRequestList Message.
Tip:
This operation provides functionality like that of the
Pending Approvals list in CentraSite Control. See the
topic Reviewing Requests that You Have Submitted for
Approval in the section Using Approval Policies of
the document Working with Design/Change-Time Policies for
details.
The getPendingApprovals,
getApprovalRequests and
getApprovalHistory
operations each return an array of approval requests (i.e., their result set)
in an ApprovalRequestList
message. In certain cases, the result set can be quite large (e.g., if you were
to retrieve the entire Approval History log). Instead of receiving the entire
result set in a single message, you can use the scroll
parameter to retrieve the results in blocks of a specified size (e.g., 15
entries at a time). You might use this feature, for example, to display
approval requests a page at a time in your client application.
To receive a specified block of results, set the following elements in
the scroll parameter when you invoke the
getPendingApprovals,
getApprovalRequests or
getApprovalHistory
operation.
| In this element... | Specify... |
|---|---|
| start | The first element in the block that you want to retrieve (where 1 represents the first element in the entire set of results). |
| number | The total number of elements that you want to retrieve in that block (i.e., the size of the block). |
For example, let's say you are using the getApprovalHistory operation, and you want to retrieve the contents of the log 20 entries at a time. To do this you would...
| Invoke getApprovalHistory | set scroll.start =
1
|
set scroll.number =
20
|
| Invoke getApprovalHistory again | set scroll.start =
21
|
set scroll.number =
20
|
| Invoke getApprovalHistory again | set scroll.start =
41
|
set scroll.number =
20
|
...and so forth until you reach the end of the result set.
To determine when you have reached the end of the result set, you can
check the value in the count parameter in the
ApprovalRequestList. This
parameter reports the total number of entries in the entire result set.
Note:
If the last block in the set contains fewer entries than what you
specify in scroll.number, the operation simply returns
the remaining entries in that last block. If the element that you specify in
scroll.start does not exist in the result set, the
operation returns an empty list.
There might be times when you need to retract a pending request from the approval system. For example, if a request that is awaiting approval requires the approval of a user who has left the company, the request can become stuck in "pending" mode. To resolve this condition, you must back that request out of the approval system and resubmit it (after updating the approver group, of course).
When you have an approval request that is stuck in the "pending" mode, you can use the revertPendingStateChange operation to remove the request from the approval system. This operation also reverts the object that was pending approval to its previous state so that a user can submit the object for approval again.
Note that when you invoke this operation, you must specify the key of the registry object whose state you want to revert. You can obtain this key from the approval request that is stuck in "pending" mode. (You would need to retrieve that request, and the object's key, using one of the operations that returns an ApprovalRequestList.)
This operation returns a
revertPendingStateChangeResponse message. The value of
the revertedState parameter in this message reports the
lifecycle state of the object on which the
revertPendingStateChange
operation was executed. For example, if you execute this operation on an object
whose lifecycle state is pending a change from state A to state B, the
operation will revert the object to state A and return state A in the
revertedState parameter.
Note:
Only users in the CentraSite Administrator role are permitted to
execute the revertPendingStateChange
operation. If the authenticated user is not a member of this role, the
operation returns a SOAP fault.
This section contains descriptions for the following operations and data structures:
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/or submission date.
For additional information about using this operation, see Approving or Rejecting Approval Requests.
| Parameter Name | Description | |
|---|---|---|
locationCentraSite |
String Optional. The address
of the CentraSite registry/repository from which you want to retrieve the
approval requests. The registry/repository runs at the following URL:
Where server is the machine on which the CentraSite registry/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
|
|
objectType |
String Array Optional. If
you want to retrieve approval requests for only certain object types, use this
element to specify the types by name.
Note: |
|
submittedAfter |
DateTime Optional . If you want to retrieve requests after a particular date, specify that date in this element. | |
submittedBefore |
DateTime Optional. If you want to retrieve requests before a particular date, specify that date in this element. | |
locale |
String Optional. The locale in which you want the results returned. | |
scroll |
Scroll Optional. If you want
to return a particular block of entries from the result set, specify the
following values in the scroll element. For information
about using the scroll element, see
Scrolling through the
List of Returned Approval Requests.
|
|
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 |
Integer Optional. The number of entries
to be returned in the block of approval requests.
If you specify a |
|
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/or approval status.
For additional information about using this operation, see Retrieving the List of Approval Requests that a User has Submitted.
| Parameter Name | Description | |
|---|---|---|
locationCentraSite |
String Optional. The address
of the CentraSite registry/repository from which you want to retrieve the
approval requests. The registry/repository runs at the following URL:
Where server is the machine on which the CentraSite registry/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
|
|
status |
String Optional. If you want to retrieve only requests with a specified approval status, specify one of the following values shown here: | |
|
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 |
String Array Optional. If
you want to retrieve approval requests for only certain object types, specify
the types by name in this element.
Note: |
|
submittedAfter |
DateTime Optional . If you want to retrieve requests after a particular date, specify that date in this element. | |
submittedBefore |
DateTime Optional. If you want to retrieve requests before a particular date, specify that date in this element. | |
locale |
String Optional. The locale in which you want the results returned. | |
scroll |
Scroll Optional. If you want
to return a particular block of entries from the result set, specify the
following values in the scroll element. For information
about using the scroll element, see
Scrolling through the
List of Returned Approval Requests.
|
|
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 |
Integer Optional. The number of entries
to be returned in the block of approval requests.
If you specify a |
|
This operation returns detailed information about specified approval requests.
For additional information about using this operation, see Getting Additional Details about an Approval Request.
| Parameter Name | Description |
|---|---|
locationCentraSite |
String Optional. The address of the
CentraSite registry/repository from which you want to retrieve the approval
requests. The registry/repository runs at the following URL:
Where server is the machine on which the CentraSite registry/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
|
approvalRequestKeys |
String Array The keys for the approval requests whose details you want to retrieve. |
locale |
String Optional. The locale in which you want the results returned. |
This operation approves specified approval requests.
For additional information about using this operation, see Approving or Rejecting Approval Requests.
| Parameter Name | Description |
|---|---|
locationCentraSite |
String Optional. The address of the CentraSite
registry/repository on which the approval requests reside. The
registry/repository runs at the following URL:
Where server is the machine on which the CentraSite registry/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
|
approvalRequestKeys |
String Array The keys for the requests that are to be approved. |
comment |
String Optional. A comment from the approver. |
locale |
String Optional. The locale in which you want the results returned. |
ApprovalRequestList (will contain the requests that were approved)
This operation rejects the specified approval requests.
For additional information about using this operation, see Approving or Rejecting Approval Requests.
| Parameter Name | Description |
|---|---|
locationCentraSite |
String Optional. The address of the CentraSite
registry/repository on which the approval requests reside. The
registry/repository runs at the following URL:
Where server is the machine on which the CentraSite registry/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
|
approvalRequestKeys |
String Array The keys for the requests that are to be rejected. |
comment |
String Optional. A comment from the approver. |
locale |
String Optional. The locale in which you want the requests returned. |
ApprovalRequestList (will contain the requests that were rejected)
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 will receive all entries in the log. If the user belongs to the Organization Administrator role, he or she will receive all log entries for his or her organization. Otherwise, the user receives only those approval requests that he or she has submitted.
| Parameter Name | Description | |
|---|---|---|
locationCentraSite |
String Optional. The address
of the CentraSite registry/repository on which the approval history log
resides. The registry/repository runs at the following URL:
Where server is the machine on which the CentraSite registry/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
|
|
status |
String Optional. 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 (i.e., 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 |
String Array Optional. If
you want to retrieve approval requests for only certain object types, specify
the types by name in this element.
Note: |
|
submittedAfter |
DateTime Optional. If you want to retrieve requests after a particular date, specify that date in this element. | |
submittedBefore |
DateTime Optional. If you want to retrieve requests before a particular date, specify that date in this element. | |
locale |
String Optional. The locale in which you want the results returned. | |
scroll |
Scroll Optional. If you want
to return a specified block of entries from the result set, specify the
following values in the scroll element. For information
about using the scroll element, see
Scrolling through the
List of Returned Approval Requests.
|
|
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 |
Integer Optional. The number of entries
to be returned in the block.
If you specify a |
|
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.
For additional information about using this operation, see Reverting a Pending Approval Request.
| Parameter Name | Description |
|---|---|
locationCentraSite |
String Optional. The address of the CentraSite
registry/repository on which the object resides. The registry/repository runs
at the following URL:
Where server is the machine on which the CentraSite registry/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
|
key |
String The key of the object whose state you want to revert. |
| 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.
|
This data structure holds a list of approval requests.
For additional information about working with this structure, see The ApprovalRequestList Message.
| 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
|
String Optional. 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 (e.g., "Pre-State Change"). | ||
reasonForRequest |
String Optional. 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 (i.e., 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 |
Scroll Optional. 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. | ||
This data structure holds the details for a specified set of approval requests.
For additional information about working with this structure, see Getting Additional Details about an Approval Request.
| Parameter Name | 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 will contain 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 |
String Optional. 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: | ||||
|
Value
|
Description
|
|||
| 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. Can also indicate that the request was auto-approved. | |||
