Skip to main content
Kinetic Community

Individual Approvals in Kinetic Request CE

 

Overview

This article outlines how to create an approval that is assigned to a specific individual in Kinetic Request CE. The approval process is made up of a series of smaller functions (handlers) which create an approval record, notify the approver, and return the approvers decision.

This approval process is designed to be called from a Kinetic Request submission, or an external system such as Salesforce or ITSM.  

The following information will be needed before calling the approval process and should be gathered via inputs, or other task handler results.

Key Components

  1. Parent Tree - This is the tree that the approval process is called from (Typically a Kinetic Request Submission)
  2. Approval Routine - This routine creates the approval record, emails the approver an invite, and returns the approvers decision
  3. Approval Form - A form that is used to display content to the approver, and ask for their decision.
  4. Approval Form's Complete Tree - This tree is called when the Approval Form is submitted

By the end of this article you'll be able to use approvals in any of your Kinetic Task trees!

Usage

Step 1: Import required components

The following components are needed in order to create approvals in Kinetic Request CE. 

Task Handlers

The following Task Handlers are needed in order to create an approval in Kinetic Request CE. You can download each handler and import it into your Kinetic Task instance.

You may need to create a Category for Kinetic Request CE in your Task instance so that you can associate the handlers with a category and see them in the Task Builder. For help installing handlers, click here.

Kinetic Request CE User Retrieve

Kinetic Request CE Kapp Retrieve

Kinetic Request CE Submission Create

Kinetic Request CE Submission Update

Kinetic Request CE Submission Get Answers

 

Task Routines

The Approval Create - Individual routine is used within a parent process when an approval is needed. This routine performs a series of functions which ultimately create an approval record, notify the approver, and return the approval decision.

Note: Please unzip the Approval Create - Individual file after download.

This routine is typically categorized as a Kinetic Request CE Routine. 

Approval Create - Individual

Kinetic Request CE Forms

The approval template is a starting point for creating other approval forms in Kinetic Request CE. This template can be cloned and modified to meet the business needs of your organization.

For help importing forms, follow this article

Approval Template

 

Kinetic Request CE Kapp Attributes

The Web Server Url KAPP attribute is used within the approval routine to generate a link to the approval form. This is typically set to the load balanced url for Kinetic Request (e.g. http://request.mycompanyname.com/kinetic)

For help adding KAPP attributes click here

Web Server Url

Step 2: Setup Parent Tree (process that includes an approval) to use the Approval routine

Once all of the components are installed navigate to the process in which you would like to create an approval (Typically a Kinetic Request Submission). 

  1. Drag the Approval Create - Individual routine onto your process where the Approval needs to take place. 
    Step 2







     
  2. Rename the node to something like "Create Approval" and open it up to configure it's inputs as follows:
    Approval Routine Configuration
    • Space Slug - The slug of the space in which the approval form exists and will be created
      • Ex.) <%= @space['Slug']%>
    • KAPP Slug - The slug of the KAPP in which the approval form exists and will be created
      • Ex.) <%= @kapp['Slug']%>
    • Approval Form Slug - The slug of the Approval Form to use (this is commonly derived from a Kinetic Form Attribute)
      • Ex.) approval-template
    • Approver ID - The ID of the Approver that the approval will be assigned to (this ID is the Approvers Kinetic Core User ID)
      • Ex.) (to make the approver yourself) <%= @submission['Created By']%>
    • Summary - A short description of what the approval is for. (this is commonly something like "Jane Doe requested an iPad")
      • Ex.) <%= @submission['Created By']%> submitted a(n) <%= @form['Slug']%> for your approval
    • Details - A detailed description of what is being approved. (this is typically used when the approval form doesn't include a "Review Frame of the original request. 
    • Originating System - The system that the approval is being called by. (Kinetic Core, Salesforce...etc)
      • Ex.) Kinetic Core
    • Originating ID - The ID of the originating request
      • Ex.) <%= @submission['Id']%>
    • Review URL - A link to the originating system
      • Ex.) <%= @kapp_attributes['Web Server Url'] %>/<%= @space['Slug']%>/submissions/<%= @submission['Id']%>?review %>
    • System Input - This is an optional input that is typically used by the Approval Form to pass in system data (typically JSON) that is formatted and presented to the approver.

Step 3: Setup the Approval Forms Complete Tree

When the Approval Form is submitted, this tree is called. Its sole purpose is to trigger the deferral node on the routine to create this approval. 

There is only one node on the Approval Form's complete tree. It is a Create Trigger node.

  • The Action Type should be "Complete" since we're completing the deferral node on the Approval Create - Individual routine
  • The deferral token input data comes from the Approval Forms Deferral Token field (set by the Approval Create - Individual routine)

 

Step 4: Submit a request!

Now, all you need to do is submit a request that calls this process. An approval should get kicked off and assigned to the whoever the Approver ID input was set to. 

Under the Covers

Approval Create - Individual Routine

The Approval Create - Individual routine is where all of the magic happens. 

Node Explanation:

  • Retrieve Approver - This node looks up the Approvers Name, and email address. Results from this node are used to populate fields in the Create Approval node as well as the Email Approver node

  • Retrieve KAPP - This node retrieves the KAPP attributes (most importantly "Web Server Url" in order to build a link for the approval notification)

  • Web Server Url - This node is simply an echo node which builds the Web Server Url and makes it easy to reference elsewhere

  • Defer - The Defer node is where we wait for a response from the Approval Form's complete tree. The Defer node generates a token which we pass to the Approval Form as an answer value. When the Approval Forms Complete tree has a trigger which completes this defer node once the approval has been submitted. This is key to completing the approval. 

  • Create Approval - This node creates the actual approval submission. In the Values input for this node, we're setting fields on the approval that link the Approval to it's parent as well as setting who the actual approver is.

  • Email Approver - This node simply generates an email to the approver with a link. This node will likely be replaced by whatever mechanism your organization uses for messaging.
  • Retrieve Approval Answers - This node gathers the answers from the approval record so that we can return comments / denial reason..etc 
  • Close Approval - This node simply sets the Status and Core state of the Approval Record. The Status is set to the Decision the Approver Made
  • Return - This node returns the approval decision and additional information to the parent process.

Approval Form

The Approval Form has a set of questions that are filled out by the Approver, and another set of hidden questions that are used by the system to facilitate the approval process.

Approver Section

  • The Request Details Section is simply used for displaying information about what is being approved to the approver. The approval template displays the Summary and Details fields set by the Approval Create - Individual routine. 

    • In some implementations a requirement may be to display the originating request in read only mode. In that case see the section below.

  • The Approval Section captures the Approvers Decision, Denial Reason and additional comments

Hidden Fields Section

  • The Hidden Fields Section includes a series of system fields used to manage the Approval. 

    •  Assigned Individual Displayed Name - This field is often used within the bundle to build a console of outstanding approvers and display who the Approval is assigned to. 

    • Assigned Individual - This field holds the Kinetic Core User Id of the Assigned Individual. This field is used in the bundle to search for approvals assigned to a user.

    • Assigned Group - This field is used for group approvals

    • Details - This field holds a detailed description of what is being approved. In the example from this article it's contents are being displayed in a text element.

    • Deferral Token - This field holds the deferral token so that when the submission is completed, we know which deferral node to trigger "complete"

    • Originating System - This field is used to hold the Originating System's name. At times it is useful to know which system (if not Kinetic Core) triggered the approval in order to trigger logic on our Approval form or workflow.

    • Review URL - This field holds the URL to the originating request. In the example provided in this article, it is used to build the Review Request Button

    • Parent Instance ID - This field holds the ID of the Parent submission. This can be useful for reporting to see what submission this approval is for

    • Status - This is a "friendly" status field that can be set and exposed in the bundle. 

    • System Input - This is a system field which typically would contain a JSON string to be parsed by the approval template. The data contained in this field could be used to modify the display / workflow for the approval. 

    • Summary - This field holds a short description of what is being approved. In the example from this article it's contents are being displayed in a text element. This field is also used as the submission label for the Approval Form

Example

In the scenario below, the approval is created from an iPad Request and assigned to the user that submitted the original request. This entire scenario is provided for download here.

iPad Request gets Submitted
Approver gets notification
Approver Reviews request and Approves / Denies

 

Additional Configurations

Embedding the original request within the Approval Form

Sometimes, it's helpful to embed a read only view of the original request within the approval form. To do this, complete the following steps.

Step 1: Add an HTML element to your Approval Form and put an empty div inside of it with an id of requestDetails. Example:  Review Request Div
Step 2: Create an On Load event on the page of your approval that you want to load the review request
if( K('field[Originating System]').value() == 'Kinetic Core') {
      var submissionId = K('field[Parent Instance ID]').value();
      K.load({
        path: bundle.spaceLocation() + '/submissions/' + submissionId + '?review',
        container: "#requestDetails"
      })
}
Once the Approval is created, the Javascript event loads the parent submission in review mode. In the example given above, it only does this when the Originating System is set to Kinetic Core. 

 

Related

Topics
How to set up a bridge to Kinetic Core Submissions for one of your Forms
This article includes the details of to set up a bridge to Kinetic Core Submissions to one of your Forms.
Approval Sample Using Common Approval Service Item
Provides sample service items to demonstrate how a Serivce Request can use a different Service Request for approvals.
Infinite Approvals
Not all Approval Processes have defined assignments or a defined amount of approvals.  Some approval processes require the ability to infinitely add additional Approvers or route to another Approver.  In the case where the Approval Process needs flexibility this example shows how to accomplish it.
Approving or Denying via email link
Occassionally, it may be desired to allow an approver to approve (and possibly deny) a request by clicking a link in an email without requiring any additional information/action from that user. Note that it is impossible to ensure the person clicking the link is the person the mail was sent to if the individual is not required to log in. If the individual is required to login, there will be that additional login step after clicking the link if there is no single sign on or existing session. Another important consideration is the use of/requirement for Reason for Denial text. If you allow automatic denial, you are not requiring comments for a reason for denial.
Backup Approver Example
How to setup a Backup Approver in the Task Builder
Reassign an Approval
How to set up a task tree to allow an approver to reassign to someone else.
References