Overview

Robots is a tool for the Kinetic Platform that allows you to schedule the initiation of a workflow process at a defined time. The Robot UI handles creating and maintaining the schedule as well as listing executions of the schedule. A Task routine actually schedules the executions of task trees using the data defined in the Robot UI.

Examples of what can be done with Robots:

• Polling external systems every x minutes / hours to look for new activity which may need some sort of action
• Perform a test (e.g., ping, transaction) to test a systems availability
• Initiate routine audit activities (system password changes, compliance reviews)
• Initiate routine surveys / questionnaires (every 30 days, query a set of users)
• Perform / initiate routine data summarizations on the last day of the day / week / month / quarter / year
• Performing routine data sync operations at scheduled intervals

Quick Start

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

• Task Trees should be attached to the standard Kinetic Robot source, and the Robots group.
• 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 Execution entry.
  • Action Type = Complete
  • Deferral Token = <%=JSON.parse(@source['Data'])['Kinetic Robot Deferral Token']%>
  • Message = <leave blank>
  • 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>

2. Access Robots from Home | Settings in the UI.
3. Create a Robot entry, including the Task Tree name defined in step 1 (do not include the source or group in the name), and include schedule details.

Robots User Interface

Robot Definitions

Robot definitions are created and stored as a Datastore submission. (Once a definition is saved or updated, a webhook will trigger a Task Tree. The Task Tree handles all execution of events.) The UI to define the robot is part of the standard bundle deployment.

Access Robots by clicking the ‘Robots’ link from the left navigation on the Home page.

The Robot table shows any existing Robot definitions, including the next execution time.

Click ‘Create Robot’ to enter a new Robot definition, or click the Robot name next to an existing Robot entry to edit its definition.

General Info

• Robot Name: The display name for this robot. Required.

• Description: Any text that describes the robot.

• Category: Category is a free-form text that can be used to group / order robots. Used only for display purposes.

• Status: Select Active or Inactive. Active Robots will attempt to execute within their defined schedule, Inactive Robots will not. Required.

• Task Tree Name: The name of the Kinetic Robot task tree to execute. The tree must be defined before the Robot’s status is ‘Active’ or the Kinetic Task engine will generate errors when trying to execute. Required.

• Runtime Inputs: If the Task Tree being executed 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. There is basic JSON format checking when saving the Robot.

Execution Notification

• Notify Upon Each Run Completion: Set to ‘Yes’ is the Robot should send a notification upon each Execution of the Robot. This will prompt two further inputs: Recipients and Notification Message Template name. Required.
  • Recipients is a comma separated list of Groups, Usernames, and/or SMTP email addresses. Groups are teams defined within the Kinetic Platform (an email will be sent to each member of the team who has a defined email address). Username refers to user defined within Kinetic Platform (emails will be sent if the user has a defined email address). Any combination and any number of email addresses can also be included.
  • Notification Message Template must be a value that matches an entry in the Platform’s Notifications component. One out of the box notification is included, ‘Robot Execution’, however any valid template may be used.
    

Recurrence Information

Templates can recur minutely, hourly, daily, weekly, monthly, or yearly. Use the ‘Every’ field and the dropdown to select interval frequency. Based on the selections, other inputs will appear.

• Minutely: Minutely recurrence only require how many minutes to wait between each execution. Examples include: Every 10 minutes, every 30 minutes
• Hourly: Hourly recurrence options require how many hours to wait between each execution and the execution minute. Examples include: Every 3 hours at 15 minutes past the hour. Note: All execution hours / minutes must be entered in UTC time. The blue box provides some reference information.
• Daily: Daily recurrence options require how many days to wait between each execution and the execution hour and minute. Examples include: Every 1 day at 1:30 AM UTC, every 3 days at midnight. Note: All execution hours / minutes must be entered in UTC time. The blue box provides some reference information.
• Weekly: Weekly recurrent options require how many weeks to wait between each execution, which days of the week, the starting hour and minute. In the example below, the Robot will run every week on Monday, Thursday, and Saturday at 1:00 AM UTC. Note: All execution hours / minutes must be entered in UTC time. The blue box provides some reference information.
• 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, the starting hour and minute.

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 at 2:30 PM UTC. Note: All execution hours / minutes must be entered in UTC time. The blue box provides some reference information.

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 at 2:30 PM UTC. Note: All execution hours / minutes must be entered in UTC time. The blue box provides some reference information.

• Yearly: Yearly schedules require the number of years between schedules, 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. Both options require the number of months between executions, the starting hour and minute.

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 at 10:45 AM UTC. Note: All execution hours / minutes must be entered in UTC time. The blue box provides some reference information.

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 at 10:45 AM. Note: All execution hours / minutes must be entered in UTC time. The blue box provides some reference information.

Execution Period

• Start Date: 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. Required. Note: This data is entered in the user’s local time.
• End Date: If there is no End Date defined, the schedule 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 3 full years. Note: This data is entered in the user’s local time.

Schedule Completion Notification

• Notify Upon Schedule Completion: This is presented if the schedule has an end date. Set to ‘Yes’ is the Robot should send a notification after the last scheduled execution of the Robot. This will prompt two further inputs: Recipients and Notification Message Template name.
  • Recipients is a comma separated list of Groups, Usernames, and/or SMTP email addresses. Groups are teams defined within the Kinetic Platform (an email will be sent to each member of the team who has a defined email address). Username refers to user defined within Kinetic Platform (emails will be sent if the user has a defined email address). Any combination and any number of email addresses can also be included.
  • Notification Message Template must be a value that matches an entry in the Platform’s Notifications component. One out of the box notification is included, ‘Robot Completion’, however any valid template may be used.

Robot Executions

Each time a robot executes, an entry is written in the Robot Execution table. Each execution records the execution’s 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.

Access the list of executions by opening an existing Robot and clicking ‘Executions’ at the top. Click the ‘View’ link on any individual execution to see its details.

Components

Datastore Forms

-Robot Definitions: Stores the definition of the robot

• Robot Executions: Each execution of a robot is recorded in this form
• Robot Next Execution: Stores the next scheduled run of a Robot.

Notification Templates and Snippets

As part of the Robot installation, two notification templates and two snippets are imported.

Templates

One notification template 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 or cloned to suit individual needs.

Robot Execution
Subject:
Robot ">robot name<" has executed
Body:
Robot Execution Notification

Robot >robot name< has executed.

View Execution Details:
>Link to Robot Execution Details<

Robot Completion
Subject:
Robot ">robot name<" has completed its last scheduled execution
Body:
Robot Completion Notification

The Robot >robot name< has completed, which means no further executions for this robot will occur. Click the link below to review / edit the Robot's configuration if necessary.

Review Schedule:
>Link to robot definition<

Snippets

Link - Robot Configuration
Creates a link to a Robot’s definition.

Link - Robot Execution
Creates a link to a particular Robot execution.

Webhooks

There are two Space webhooks that are installed to support Robots:

• Robot - Created
• Robot - Updated

Both of these webhooks have the same filter and trigger the same Task tree. They just operate on different form actions (create vs. update). These webhooks include a filter that limits execution to only the form slug of robot-definition. The webhook triggers a task tree that gets installed with Robot deployment: {task source name}/Datastore Submissions > robot-definitions/Saved

Included Robot Task Trees and Routines

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.

• Saved: The Saved (Group: Datastore Submissions > robot-definitions Name: Saved) tree is executed whenever a robot definition is created or updated. This tree will execute the routine ‘Robot Execution Routine V2’.
• Robot Execution Routine V2: The Robot Execution Routine handles the execution of the robot. It retrieves the Robot information defined in Kinetic Request and evaluates when the next execution of the Robot’s task tree should be scheduled. After the scheduled time is reached, 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.

Additional logic ensures that any updates to the robot data are handled. (Since each update will trigger a new run of the routine, anytime there is an update any existing routines terminate themselves.

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

Dependencies

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

The Robot Execution Routine V2 uses standard task routines and handlers that are part of a standard deployment. Upon installation or upgrade of Robot, Task may report missing routines / handlers if these standard routines and handlers are not already installed. For proper operation, any missing items need to be installed.

Customization

If necessary, any of the Task data can be customized if necessary for a particular use case. It is suggested that existing trees / routines be cloned, and the cloned data be updated. Update the webhooks to call the new trees as necessary.

Creating Robot Workflow

The Workflow/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.

Robot Workflows need to be attached to the Kinetic Robot source, and the Robots group. The Robot Execution Routine hard codes these values.

Including Parameters

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

Return Node

The return node is what tells 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 three forms using ‘Import Form’ option in the Space. The import files are located in the “Datastore Forms” directory.
• Webhooks: Install the two webhooks individually using the Create Space Webhook API. The import data is located in the “Space Webhooks” directory.
  • From Kinetic Request, select Help | Reference Docs in the upper right corner.
  • Click on REST API from the displayed page.
  • Navigate to Webhooks on the left navigation panel.
  • Click on link to ‘Create Space Webhook’.
  • Paste the contents of the webhook file into the Request Body
  • Click Try It.
    Repeat the last two steps for the second webhook files.

Adjust Webhooks 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. If these space attributes don’t exist in the system, either create them, or adjust the webhooks as necessary. Webhooks can be hard coded for the environment, or use alternate parameters that exist for your system.

• Notification Templates: Install the four Notification Template records individually using the Create Datastore Submission API. These files are located in the “Datastore Data/Notification Data” directory.
  • From Kinetic Request, select Help | Reference Docs in the upper right corner.
  • Click on REST API from the displayed page.
  • Navigate to Datastore Submissions on the left navigation panel.
  • Click on link to ‘Create/Submit new Datastore Submission’.
  • Enter ‘notification-data’ in the formSlug input field
  • Paste the contents of the notification file into the Request Body
  • Click Try It.

Repeat the last two steps for the remaining Notification Template files.

Note: If you receive a message indicating a duplicate exists (i.e., a violation of a unique index), manually delete the notification or rename it and then import. The notifications have changed from previous versions.

• Task Trees: Use Task’s import tree function to import the file Kinetic_Request_CE.Datastore_Submissions-robotdefinitions.Saved.>timestamp<.xml. The file is located in the “Trees” directory.
• Dependencies : 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 files to provide the actual source name that matches the Kinetic Request source that exists in your system.
• Routines: Use Task’s import routine function to import the file Robot_Execution_Routine_V2.>timestamp<.xml. This file is located in the “Routines” directory.
• Handlers: Import this handler into the Task Engine. Choose overwrite if the handler already exists (be sure to stop and start the Task Engine if prompted after an overwrite operation).
  • kineticˍdetermineˍnextˍoccurrence_v2