This APS type must be implemented by those APS applications (platform services or custom applications) that require approval for commercial operations. This implementation allows an application to interact as a client with the ApprovalManagement service (additional service optionally installed on the platform). That service discovers all its clients connected to the platform and requires every client to expose two custom operations as described in this document.
An action (ModuleAction) to be approved, for example, “Create new order”, contains an approvable entity (ModuleActionEntity) that, in turn, consists of one or more approvable fields (TypedProperty), for example, “Discount for setup fee”, “Discount for recurring fee”, and so on.
In this document:
The considered APS type (download
) looks as follows:
{
"apsVersion": "2.0",
"name": "ApprovalEngineClient",
"id": "http://odin.com/oa/types/approval-engine/client/1.0",
"implements": [ ],
"structures": {
"ModuleAction": {
"type": "object",
"properties": {
"name": {
"type": "string",
"required": true
},
"entity": {
"type": "ModuleActionEntity",
"required": true
}
}
},
"ModuleActionEntity": {
"type": "object",
"properties": {
"fields": {
"type": "array",
"items": {
"type": "TypedProperty"
},
"required": true
}
}
},
"TypedProperty": {
"type": "object",
"properties": {
"name": {
"type": "string",
"required": true
},
"displayName": {
"type": "string",
"required": true
},
"type": {
"type": "string",
"enum": ["number", "currency", "percentage", "string"],
"required": true
},
"isArray": {
"type": "boolean",
"default": false
},
"isCriteria": {
"type": "boolean",
"default": true
}
}
},
"ApprovalResponse": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"required": true,
"description": "Approval Request Identifier"
},
"status": {
"type": "string",
"required": true,
"enum": ["APPROVED", "REJECTED"],
"description": "Approval Request Result"
},
"reason": {
"type":"string",
"description": "Reason of approval decline id any"
}
}
}
},
"operations" : {
"getActions" : {
"path" : "/actions",
"verb" : "GET",
"response" : {
"type" : "array",
"items" : {
"type" : "ModuleAction"
}
},
"errorResponse" : {
"type" : "object"
},
"access" : {
"owner" : false,
"referrer" : true,
"global" : false
}
},
"approvalHandler" : {
"path" : "/approvalResponse",
"verb" : "POST",
"parameters": {
"result": {
"kind" : "body",
"type": "ApprovalResponse",
"required" : true
}
},
"errorResponse" : {
"type" : "object"
},
"access" : {
"owner" : false,
"referrer" : true,
"global" : false
}
}
}
}
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
GET |
/actions |
Array of ModuleAction |
By request from the approval engine, return an array of the actions that the client can potentially send for approval. |
|
POST |
/approvalResponse |
HTTP response code |
This is the client’s callback handler to process a response ApprovalResponse the approval engine sends in reply to the requests for approval from the client. |
HTTP Request
GET /aps/2/resources/{aps-id}/actions
Description
The operation is called by the approval engine to request its client for an array of actions that the client can send for approval.
To enable the approval engine to process requests from a client, the provider must configure a workflow for every action that might require an approval. That is why, when the provider starts configuring the approval engine to process requests from a client, the approval engine calls the considered operation to get a set of those actions. For every possible client action, the provider configures a separate approval workflow.
Returns
An array of ModuleAction.
HTTP Request
POST /aps/2/resources/{aps-id}/approvalResponse
Description
This is the callback handler that the approval engine calls after processing a request for approval from its client.
A client can call the submitForApproval custom operation at the approval engine with a request to approve an action. After the request is processed, the approval engine calls the considered handler to return the results of the approval processing in the form of ApprovalResponse. This allows the client to determine whether the requested action was approved.
Returns
HTTP response code.
This is the structure of an approvable action that is an element of an array returned by the getActions operation. The provider can configure an approval workflow for every such action.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
|
String |
Required |
Not applicable |
The name assigned to an action. |
|
Required |
Not applicable |
Approvable entity consisting of approvable fields. |
The structure combines several TypedProperty fields in a response returned by the getActions operation. It presents an approvable entity inside an approvable action.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
|
Array of TypedProperty |
Required |
Not applicable |
The fields of an approvable entity. |
This is the structure of an approvable field inside an action entity.
If its isCriteria
property is true, the field can be used to configure an approval criteria
in a workflow step.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
|
String |
Required |
Not applicable |
Internal name of the property that works as an internal ID. |
|
String |
Required |
Not applicable |
Localized name displayed in the control panel when configuring a step in a workflow of the approval engine or processing a request for approval. |
|
String enum: “number” | “currency” | “percentage” | “string” |
Required |
Not applicable |
The type of the field value to be approved. |
|
Boolean |
Not required |
|
If true, the client can send several fields with the same name and value type for approval when calling the submitForApproval operation of the approval engine. |
|
Boolean |
Not required |
|
If |
This is the structure of data that the approval engine sends to the callback approvalHandler after processing a request for approval.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
|
String |
Required |
Not applicable |
Approval request identifier is the ID of the initial request for approval returned immediately by the submitForApproval operation of the approval engine. |
|
String enum: “APPROVED” | “REJECTED” |
Required |
Not applicable |
Show if the related initial request is approved or rejected. |
|
String |
Not required |
“” |
Reason of the approval status if any. |