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.

In this document:

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.