{"componentChunkName":"component---src-templates-default-template-tsx","path":"/documentation/integration/Approval/introduction/","result":{"data":{"asciidoc":{"id":"d1ae1142-d3e7-5a77-b480-f38374b2b383","html":"
\n
Table of Contents
\n\n
\n
\n

Introduction

\n
\n
\n

The AskApprove capability allows decisions to be made by an \"Approver\" on whether a Task should be completed or not, and allows them to provide extra information into the Task based on a pre-defined template in the KI.

\n
\n
\n
\n
\n

Prerequisits

\n
\n
\n

The Approval Action Handler requires use of an Approval UI Application in HIRO Desktop. For users to gain access to this application they must be part of the Task Approver Team, haasXXXXX_task_approver, for the given instance. Membership of the Team can be provided in Arago ID by an Organizational Admin.\nThe Approval Action Handler uses the SendEmail capabilities.

\n
\n
\n
\n
\n

Example usage

\n
\n
\n
\n
ki\n  name: \"Approve Sample\"\n  description: \"KI will ask approval\"\n  version: \"1\"\non\n  ogit/_id\nwhen\n  ProcessIssue==\"true\"\n  ogit/_id\ndo\n  LOCAL::model = '{\n      \"action\":\"approve\",\n      \"task\":\"The task needs to be approved (Title)\",\n      \"template\":\"Abhi test approval (Body)\",\n      \"controls\":[\n          {\n              \"approve\":{\"/approve\":\"true\"},\n              \"reject\":{\"/approve\":\"false\"}\n          }\n      ]\n  }'\n  exec: LOCAL::RESULT,\n  stdout: LOCAL::OUTPUT,\n  stderr: LOCAL::ERROR,\n  exit: LOCAL::SYSTEMRC = action(\n      capability: \"AskApprove\",\n      user_email: \"consult@org.com\",\n      issue_id: ISSUE::ogit/_id,\n      question_model: model\n      )\n  log.info(LOCAL::RESULT)\n  log.info(LOCAL::OUTPUT)\n  log.error(LOCAL::ERROR)\n  log.info(LOCAL::SYSTEMRC)\n\n  delete(ProcessIssue)\n  eject_issue(message: \"Wait for approve\", issue_id: ISSUE::ogit/_id)
\n
\n
\n
\n
    \n
  • \n

    The capability should be set to AskApprove

    \n
    • \n
  • \n

    The user_email is the recipient email address

    \n
    • \n
  • \n

    The questions structure is defined in LOCAL::model (see below)

    \n
    • \n
  • \n

    Before the Approval Email is sent, the KI should eject_issue. This puts the Task into a WAITING state. The Approval UI will then return the KI to PROCESSING. If the Task is not put into WAITING, the UI will not show the Task.

    \n
    • \n
\n
\n
\n
\n
\n

The Question Structure (JSON obejct):

\n
\n
\n
\n
{\n  \"action\": \"<ACTION>\",\n  \"task\": \"<TASK>\",\n  \"template\": \"<TEMPLATE>\",\n  \"controls\": [ <CONTROL>, <CONTROL>, ...]\n}
\n
\n
\n
\n
    \n
  • \n

    \"action\": \"<ACTION>\" The user friendly name of the action the user will perform, ie \"Approve\".

    \n
    • \n
  • \n

    \"task\": \"<TASK>\" The user friendly name of the task the user will perform the action on, ie \"Add User to Security Group\".

    \n
    • \n
  • \n

    \"template\": \"<TEMPLATE>\" The user friendly description of the task.

    \n
    • \n
  • \n

    \"controls\": [ <CONTROL>, <CONTROL>, …​] The array of questions / inputs the user needs to provide. The controls array can contain one or more <CONTROL> objects.

    \n
    • \n
  • \n

    The <CONTROL> object is a single, or block of input questions for the user. These can be: \"Approve or Reject\", Text Inputs, or Dropdown Options.

    \n
    • \n
  • \n

    The \"Approve or Reject\" object the only required object, and all other inputs will be available only if the user selects \"Approve\".

    \n
    • \n
\n
\n
\n
\n\"Title\"\n
\n
\n
\n

Control Objects

\n
\n

Each Control Object specifies which format to ask the question, and what data to save to the AutomationIssue Node.

\n
\n
\n

For \"Approve or Reject\" or Dropdown Options, the data is defined as a DataObject which will be saved directly into the AutomationIssue if the option is selected by the user. The DataObject’s key is the Attribute Name, and the value is the value to be saved in the graph. The DataObject can be empty, or have one or more Attribute Mappings.

\n
\n
\n

For Text options, the value is the Attribute Name, the user’s input will be saved to.

\n
\n
\n

The Control Object can be used for either the Approval or Rejection flow. By default they are for the Approval flow, but a key for can be specified to allow the Control Object to used in the Rejection flow.

\n
\n
\n
\n
{\n  ..., //Control Object Parameters\n  \"for\": \"reject\"\n}
\n
\n
\n
\n

The Control Object can also be either required or optional. By default they are required, but a key required can be specified to allow this to be configurable.

\n
\n
\n
\n
{\n  ..., //Control Object Parameters\n  \"required\": false\n}
\n
\n
\n
\n

Approve / Reject Option

\n
\n
\n
{\n  \"approve\": { \"/attribute\": \"value1\" },\n  \"reject\": { \"/attribute\": \"value2\" }\n}
\n
\n
\n
\n
    \n
  • \n

    \"approve\": Holds the DataObject to be saved on approval.

    \n
    • \n
  • \n

    \"reject\": Holds the DataObject to be saved on rejection.

    \n
    • \n
\n
\n
\n
\n\"Approve\n
\n
\n
\n
\n

Text Input (single)

\n
\n
\n
{\n  \"text\": \"/attribute\"\n}
\n
\n
\n
\n
    \n
  • \n

    \"text\": Holds the string Attribute Name, the user’s input will be saved to.

    \n
    • \n
\n
\n
\n
\n\"Text\n
\n
\n
\n
\n

Text Input (multiple)

\n
\n
\n
{\n  \"text\": [\n    \"/attribute1\",\n    \"/attribute2\"\n  ]\n}
\n
\n
\n
\n
    \n
  • \n

    \"text\": Holds an array of string Attribute Namea, the user’s inputs will be saved to.

    \n
    • \n
\n
\n
\n
\n\"Text\n
\n
\n
\n
\n

Text Input with Provided Label (single)

\n
\n
\n
{\n  \"text\": { \"Example Label\": \"/attribute\" }\n}
\n
\n
\n
\n
    \n
  • \n

    \"text\": Holds an object, Label to Attribute Name, the user’s input will be saved to.

    \n
    • \n
\n
\n
\n
\n

Text Input with Provided Label (multiple)

\n
\n
\n
{\n  \"text\": {\n    \"Example Label 1\": \"/attribute1\",\n    \"Example Label 2\": \"/attribute2\"\n  }\n}
\n
\n
\n
\n
    \n
  • \n

    \"text\": Holds an object, Label to Attribute Name, the user’s input will be saved to.

    \n
    • \n
\n
\n
\n
\n

Text Input Header and Description

\n
\n
\n
{\n  \"text\": \"/attribute\",\n  \"header\": \"Header Text\",\n  \"desc\": \"Description Text\",\n}
\n
\n
\n
\n
    \n
  • \n

    \"header\": Optional Header text for this section.

    \n
    • \n
  • \n

    \"desc\": Optional Description text for this section.

    \n
    • \n
\n
\n
\n
\n

Dropdown / Select

\n
\n
\n
{\n  \"options\": {\n    \"Option1 Name\": { \"/attribute\": \"option_1_value\" },\n    \"Option2 Name\": { \"/attribute\": \"option_2_value\" }\n  }\n}
\n
\n
\n
\n
    \n
  • \n

    \"options\": Holds an object, which contains Key, Dropdown Option Name, to the DataObject to be saved on selection.

    \n
    • \n
  • \n

    There can be multiple Key, Value options.

    \n
    • \n
\n
\n
\n
\n\"Dropdown\n
\n
\n
\n
\n

Dropdown / Select Header and Description

\n
\n
\n
{\n  \"options\": {\n    \"Option1 Name\": { \"/attribute\": \"option_1_value\" },\n    \"Option2 Name\": { \"/attribute\": \"option_2_value\" }\n  },\n  \"header\": \"Header Text\",\n  \"desc\": \"Description Text\",\n}
\n
\n
\n
\n
    \n
  • \n

    \"header\": Optional Header text for this section.

    \n
    • \n
  • \n

    \"desc\": Optional Description text for this section.

    \n
    • \n
\n
\n
\n
\n
\n
","document":{"main":"Approval Action Handler","title":"Approval Action Handler","subtitle":""},"fields":{"toc":true,"location":["documentation","integration","Approval","introduction"]}},"sidebarYaml":{"id":"6d066bdd-c982-5a69-b909-a31e6fc044e0","showIndex":null}},"pageContext":{"id":"d1ae1142-d3e7-5a77-b480-f38374b2b383","parent":"documentation"}},"staticQueryHashes":["1010459453","1010459453","2356112386","2356112386","2603905930","2603905930","3026652197","3026652197","3167850324","3167850324","63159454","63159454"]}