ApprovalEngineClient

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.

Schema

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
      }
    }
  }
}

Custom Operations

OPERATION	VERB	PATH	RETURNS	Description
getActions	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.
approvalHandler	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.

getActions

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.

approvalHandler

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.

Structures

ModuleAction

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
name	String	Required	Not applicable	The name assigned to an action.
entity	ModuleActionEntity	Required	Not applicable	Approvable entity consisting of approvable fields.

ModuleActionEntity

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
fields	Array of TypedProperty	Required	Not applicable	The fields of an approvable entity.

TypedProperty

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
name	String	Required	Not applicable	Internal name of the property that works as an internal ID.
displayName	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.
type	String enum: “number” | “currency” | “percentage” | “string”	Required	Not applicable	The type of the field value to be approved.
isArray	Boolean	Not required	false	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.
isCriteria	Boolean	Not required	true	If true, the field can be used to configure an approval criteria in a workflow step.

ApprovalResponse

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
requestId	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.
status	String enum: “APPROVED” | “REJECTED”	Required	Not applicable	Show if the related initial request is approved or rejected.
reason	String	Not required	“”	Reason of the approval status if any.

← RatedDataSupport

GDPRSupport →