Skip to main content
Kinetic Community

Robots

Kinetic Robot is a component of the Admin Kapp that allows you to schedule the initiation of a task process at defined times. The Robot UI handles creating and maintaining the schedule as well as listing executions of the schedule. Workflow within Task actually schedules the executions of task trees using the data from the schedule UI.

Quick Start

  1. Build a Task Tree that will be executed according to a schedule.

    1. Task Trees should be attached to the standard Kinetic Task source.

    2. A return node needs to be added at the end of the Task process.  A “Kinetic Robot Deferral Token” item will be added as a data input to tree execution data.  This is the Deferral token that needs to be passed back in the return node.  Results follow the normal XML results strategy.  Any results passed back will be displayed in the Robot Schedule’s activity listing.

      1. Action Type = Complete

      2. Deferral Token = <%=JSON.parse(@source['Data'])['Kinetic Robot Deferral Token']%>

      3. Results = Create a JSON string for whatever data you want recorded for each execution.  Put it where the red text is below.  This could be a simple I'm done statement, like below, or a number of other details.
        <results>
             <result name="output"><%={"message" => "return from test robot"}.to_json%></result>
        </results>

      4. Message = <leave blank>

  2. Access Robots from the Admin Console in Request.
  3. Create a Robot Definition including the Task Tree name defined in step 1.

  4. Define an execution schedule.

 

Components

UI / Robot Creation

Click the ‘Robots’ card from the Admin console to access the Robot screen.

 

Schedules are created and stored within Kinetic Request.  (Once a schedule is saved or updated, a webhook will trigger a Task tree.  The Task tree handles all execution and rescheduled of evets.)  The UI to define a schedule is part of the Admin Kapp, exposed through the following supporting forms.

Robots

  • The console that shows the defined Robots

Robot Definitions

  • The form used to define a Robot. The key field is the Task Tree Name, which needs to match an existing task tree.

Robot Schedules

  • Once a Robot is defied, schedules can be defined against it.  A robot can have an unlimited number of schedules attached to it. Each schedule will operate independently from the others.

     

Robot Executions

  • Each time a robot executes, an entry is written in the Robot Execution table.  Executions know which robot they operate against as well as what schedule.  Overall executions can be viewed from the Robot definition, executions for a specific schedule can be viewed from the schedule definition page.  Each execution records that executions Task tree inputs (if any), as well as the outputs (if the task tree that executes is designed to return any).  The Execution includes the start time, end time and calculates the duration.

 

Robot Schedules

The Robot schedule defines the inputs to the task tree (if any are necessary), the Recurrence, when the schedule begins and ends, as well as notification preferences.  Once a schedule is defined, it really is used to indicate that it exists and a way to display executions.  All of the actual scheduling of Robot (Task) executions is handled by Task trees.

Task Tree Inputs

If the Task tree being executed by the Robot expects inputs, the Runtime Inputs field should be populated in JSON format:  {"key 1":"value 1", 'key 2":"value 2", … }.  These inputs will be passed to the executing Task tree.

Execution Notification

If a notification should be sent upon each Execution of the Robot, choose ‘Yes’ to the ‘Notify Upon Each Run Completion” question.  This will prompt two further inputs: Recipients and Notification Message Template name.

Recipients is a comma separated list of of Groups, Usernames, and/or SMTP email addresses. Groups are teams defined within Kinetic Request (an email will be sent to each member of team who has a defined email address).  Username refers to user defined within Kinetic Request.  Emails will be sent if the user has a defined email address.  Any combination and any number of entries can be include as email recipients.

The Notification Message Template name is a value that matches an entry in the Notification Templates section of the Admin Console.

Recurrence

Templates can recur minutely, hourly, daily, weekly, monthly, or yearly.  Select the value from the list and then choose a frequency and other details.

Minutely / Hourly / Daily

Minutely / Hourly / Daily recurrence options will only ask for much time between each execution (1-999 allowed).  Examples include:  Every 10 minutes, every 36 hours, or every 12 days

Weekly

Weekly will ask for how many weeks between each execution (1-99 allowed), and then which days of the week.  In the example below, the Robot will run every week on Monday, Thursday, and Saturday.

Monthly

Monthly schedules can run on certain days of the week or on specific dates in a month.  Both require the number of months between executions (1-99 allowed).

Certain days of the week allows the user to select which days of the week the schedule should be executed.  In the example below, the Robot will execute on the First Monday and the Last Friday of every other month.

For the specific dates of the month option the dates 1 - 31 are selectable. Note that if a date is selected that doesn’t exist for a particular month, the execution will not run (e.g., A run that operates every month on the 30 will not run in February; use ‘Last’ to indicate the last day of the month.) In the example below, the Robot will execute on the 15th and Last day of every third month.

 

Yearly

Yearly schedules require the number of years between schedules (1-99 allowed), as well as selecting which months the schedule will be triggered.  Similar to monthly schedules, you can choose certain days of the week or certain dates in a month.

Certain days of the week allows the user to select which days of the week the schedule should be executed.  In the example below, the Robot will execute each year on every Monday in January, April, July, and October.

For the specific dates of the month option the dates 1 - 31 are selectable. Note that if a date is selected that doesn’t exist for a particular month, the execution will not run (e.g., A run that operates every month on the 30 will not run in February; use ‘Last’ to indicate the last day of the month.) In the example below, the Robot will fire on the last day of March, June, September, and December each year.

Start and End Dates

The first scheduled event will be evaluated based on the info entered in the Start Date field; the Start Date is not the first execution time.  If there is no End Date defined, the schdule will run indefinitely.  If there is an end date, once the next run execution date exceeds the end date, the schedule will stop executing.  In the example below, the schedule executes for 6 full years.

Schedule Completion Notification

If a notification should be sent when the schedule has completed, choose ‘Yes’ to the ‘Notify Upon Schedule Completion” question.  This will prompt two further inputs: Recipients and Notification Message Template name. Note that the Notify Upon Schedule Completion is only presented if a schedule end date is provided.

Recipients is a comma separated list of of Groups, Usernames, and/or SMTP email addresses. Groups are teams defined within Kinetic Request (an email will be sent to each member of team who has a defined email address).  Username refers to user defined within Kinetic Request.  Emails will be sent if the user has a defined email address.  Any combination and any number of entries can be include as email recipients.

The Notification Message Template name is a value that matches an entry in the Notification Templates section of the Admin Console.

Notification Templates

As part of the Robot installation, two notification templates are imported. One is designed to be for Robot execution notifications (sent each time a Robot run completes) and the other is for Robot Schedule Completion (no further runs will be executed for that schedule).  These templates can be used as is, or they can be modified to suit individual needs.  

Robot Schedule Execution

Subject:

Robot Schedule Execution Notification

Body:

Schedule <Schedule Name> for Robot <Robot Name> has executed.

 

Robot Schedule Completion

Subject:

Robot Schedule Completion Notification

Body:

The Schedule <Schedule Name> for Robot <Robot Name> has completed, which means no further executions for this schedule will occur. Click the link below to review / edit the schedule if necessary.

<Review Schedule Button>

Webhooks

There are four webhooks that are installed in the Admin Kapp to support Robots.

Robots - Created / Robots - Updated

These webhooks include a filter that limites execution to only the form slug of robot-definition. The webhook triggers a task tree that gets installed with Robot deployment: {task source name}/{admin Kapp slug} > robot-definitions/Update Schedules

Robot Schedules - Created / Robot Schedules - Updated

These webhooks include a filter that limites execution to only the form slug of robot-schedules. The webhook triggers a task tree that gets installed with Robot deployment: {task source name}/{admin Kapp slug} > robot-schedules/Saved

 

Included Robot Task Trees and Routines

Standard

There are two task trees and one task routine that are installed as part of the Robot.

The two trees handle initiating and updating schedules.

Update Schedules

The Updated Schedules (Group: admin > robot-definitions: Name: Update Schedules) tree is triggered whenever robot definition is created or modified.  The tree finds all schedules attached to the robot and updates those schedules’ Kinetic Request submission.  This triggers an update webhook to fire for each submission schedule.

Saved

The Saved (Group: admin > robot-schedules: Name: Saved) tree is executed whenever a schedule is created or updated. This tree will execute the routine ‘Robot Execution Routine’.

Robot Execution Routine

The Robot Execution Routine handles the execution of the robot.  As input, it takes the schedule information defined in Kinetic Request and evaluates when the next execution of the Robot’s task tree should be scheduled.  If the schedule data is out of date, or if no further runs should be executed, the run is terminated.  After the scheduled time is reached, the scheduled again evaluates if it is the most recent information.  If it is not the most recent schedule data, the run terminates; if it is, an execution run submission will be entered into Kinetic Request, and the Robot’s Task Tree will be executed.  Once the Robot’s Task Tree returns, the execution run record is updated and the routine calls itself to schedule the next execution.

The Robot Execution Routine also initiates email notifications if those options were include in the Schedule Definition.

Dependencies

Notifications are sent using the KD Notification Send Using Template routine.  This is part of the Admin Kapp, and is a dependency to being able to send notifications using the included routines.

Customization

Customization of any of the routines is possible if necessary for a particular use case.  It is suggested that clones of the existing trees / routines be made, and the clones be updated.  Update the webhooks to call the new trees as necessary.

Test Robot Tree

A Test Robot tree is also included with the Robot implementation.  This Test Robot does not perform any function, but merely returns that it was fired. Use this tree as a sample for how to create the return node for all Robot Task trees that will be called.

 

Creating Robot Task Trees

The Task Trees that are executed by a Robot are the unique part of the Robot implementation.  They can be written to perform any action that Kinetic Task can perform.  Examples include retrieving data from external sources and acting on it, updating tickets in a system, sending routine email notifications, creating password change reminders.

The Task Trees need to be attached to the Kinetic Task source. The Robot Execution Routine hard codes this value.

Including Parameters

If the task tree should require parameters, you can have those passed in during execution.  The Robot Schedules will need to include the JSON structure that defines the parameters.  Upon execution of the schedule, the Robot Execution Routine will pass in parameters retrieved from the Schedule Definition.  Parameters used in a particular run are included with the Robot Execution details.

Return Node

The return node is what tell the Robot Execution Routine that the process is done and to schedule the next execution. The Return node should look like this (see a sample in the Test Robot task tree).

  1. Action Type = Complete
  2. Deferral Token = <%=JSON.parse(@source['Data'])['Kinetic Robot Deferral Token']%>

  3. Results = Create a JSON string for whatever data you want recorded for each execution.  Put it where the red text is below.  This could be a simple I'm done statement, like below, or a number of other details.
    <results>
        <result name="output"><%={"message" => "return from test robot"}.to_json%></result>
    </results>

  4. Message = <leave blank>

 

Installation

Download the installation zip, which contains the following pieces.

Forms

Install the four forms using ‘Import Form’ option in Kinetic Request.

Webhooks

Install the four webhooks individually using the Create Kapp Webhook API.

  1. From Kinetic Request, select Help | Reference Docs in the upper right corner.

  2. Click on REST API from the displayed page.

  3. Navigate to Webhooks on the left navigation panel.

  4. Click on the ‘Create Kapp Webhook’ link.

  5. Provide the Admin kapp slug (typically admin)

  6. Paste the contents of the webhook file into the Request Body

  7. Click Try It.

  8. Repeat steps 6-7 for the remaining three webhook files.

Adjust after installation

The webhooks are imported with the authentication strategy set to none.  Adjust these, if necessary to match your strategy.

Additionally, the webhooks use space parameter values.  Either creating the space attributes (if they don’t already exist), or adjust the webhooks as necessary to meet your needs. They webhook can be hard coded for the environment, or use alternate parameters that exist for your system.

Notification Templates

Install using sample Notifications templates.

  1. From the Admin console, click on Notifications

  2. Click the Import CSV button in the upper right

  3. Select the Notification Templates.csv file

Adjust after installation

The standard templates may include snippets that may not apply to your system.  Review and adjust as necessary.  Notification templates are named ‘Robot Schedule Completion” and “Robot Execution Completion”.

Task Trees

There are three Task Trees to import.  Be sure a source named Kinetic Request CE exists, OR use a text editor to edit line 2 of the kinetic_request_ce.Saved.xml and kinetic_request_ce.Update_Schedules.xml files to provide the actual source name that matches the Kinetic Request source that exists in your system.  The third task tree is tied to the Kinetic Task source, which should exist by default, so no changes are necessary.

Import using Import Task Tree button in the Kinetic Task module.

Routines

Import the routine using Import Task Routine button in the Kinetic Task module.

Handlers

Ensure these handlers are installed and configure on your system.  Most of them probably already exist within your system.  Anything not there can be downloaded from as necessary - they are not included in the installation zip file.

kinetic_determine_next_occurrence_v2

kinetic_task_tree_run_v1

kinetic_request_ce_space_retrieve_v1

kinetic_request_ce_kapp_form_submission_search_v2

kinetic_request_ce_submission_update_v1

kinetic_request_ce_submission_retrieve_v1

kinetic_request_ce_submission_get_answers_v1

kinetic_request_ce_submission_retrieve_by_query_v1

kinetic_request_ce_submission_create_v1