• First Steps
  • Basic Data Operations
  • Creating Action Handlers using Action API
  • Developing a Connector
  • Incident handling via the Domain Object Api
  • Working with Automation Tasks


When HIRO™ receives a task to automate, it will try to complete the task with its existing knowledge base. In this tutorial, we will learn how to submit automation tasks to HIRO™ and what happens in HIRO™ after the tasks has been submitted. If you are not familiar yet with how HIRO™ works, we recommend reading the HIRO™ System Overview first.


Please follow the steps described in the tutorial First Steps with HIRO to authenticate before proceeding to use HIRO’s Graph API.

What we will do in this tutorial

  1. Send a new automation task to HIRO

  2. Observe how HIRO™ processes automation tasks without Todo Variable

  3. Add a Todo Variable to our automation task

  4. Understand what happens if automation tasks cannot be resolved

  5. Teach knowledge to HIRO™ to process our task

  6. Re-submit our automation issue and check if it gets resolved

HIRO™ works in a task-centric mode. An Automation Task (a.k.a automation issue) is the central data object that triggers the automated execution of knowledge to perform this task. We will learn how we can create new automation tasks via the HIRO API. The diagram below shows the issue lifecycle; issues typically move from NEW via PROCESSING to RESOLVED.

In a situation when HIRO™ receives an automation task that is new and the knowledge base does not contain sufficient knowledge in order to complete it, the automation task will be set to STOPPED state and presented to a Subject Matter Expert (SME) to teach HIRO™ the steps to solve the Issue. With the help of an AI Expert (AIE), this Teaching Session is translated into executable knowledge, which is called Knowledge Items. HIRO™ will then use this new knowledge the next time the same task is submitted.

In this tutorial, we will first push an automation task to HIRO™, which HIRO™ cannot complete with the existing knowledge base. After adding a simple Knowledge Item to the knowledge base, we will then see that the automation task lifecycle is completed and automation tasks finally get resolved. For the sake of brevity of this tutorial, we will only enter a Knowledge Item that will directly resolve the automation task. You will find more realistic teaching session examples in the HIRO™ User Guides.

Task State Diagram
Figure 1. Task State Diagram

Create an Automation Task

We want to create automation tasks frequently. Therefore, we define a convenience function to create automation tasks in HIRO. Since an automation task is a vertex, this function will call the create_vertex() function, which we have already previously defined in another tutorial (as mentioned in the prerequisites). Then we will create an Automation Task by calling this function.

An Automation Task corresponds to the entity type ogit/Automation/AutomationIssue. We define now the function create_task(), which creates a vertex representing the Automation Task in HIRO:

def create_task (issueType, subject, originNode, attributes={}):

    vertex_data = {'ogit/Automation/issueType': issueType,
                   'ogit/Automation/originNode': originNode,
                   'ogit/status': 'NEW'
    task_id = create_vertex(hiro_session, 'ogit/Automation/AutomationIssue', vertex_data)
    return task_id

The code above creates an automation task vertex (entity type ogit/Automation/AutomationIssue) in the HIRO™ Graph with the provided attributes:

  • issueType : Type of task to be submitted, written to ogit/Automation/issueType attribute

  • subject : Task subject, which will be shown in user interfaces, written to ogit/subject attribute

  • originNode : vertex ID of the entity the task is initially associated with, written to ogit/Automation/originNode attribute

  • attributes : further attributes, i.e. Todo Variables and Information Variables.

The following attributes are mandatory attributes for automation tasks and need to be always provided upon creation: ogit/Automation/issueType, ogit/subject, ogit/Automation/originNode.

Attributes of an automation task are also called Variables when you work with them in Knowledge Items. Information Variables provide additional information to HIRO™ about the specific task to perform. If your automation task would be purchasing office material, then the products to buy and the quantities might be relevant parameters that could be provided as information variables. Todo Variables represent sub-tasks or objectives that need to be satisfied. You need to specify at least one Todo Variable upon issue creation. Note: You may add arbitrary attributes to an automation task – either any already defined attributes from the OGIT schema, or free attributes with a trailing “/”. Be aware that such free attributes need to be registered as Variables in HIRO™ to be referenced in Knowledge Items. This is done in the Knowledge Acquisition Tool.

Next, we will proceed to create our first Automation Task. As an example, we will create a task for rescheduling meetings in our calendar. In this example, HIRO™ will attempt to reschedule a meeting when it finds that the meeting date is conflicting with a vacation period. As a design decision, we set ogit/Automation/originNode to the ID of the calendar vertex in the graph, so that the ogit/Schedule/Calendar represents the context in which the rescheduling of meetings should be processed. We find out this vertex id by a query for the external google calendar id (xid query). We proceed to create the task with the following function call, by passing the parameters needed (issueType, subject, and originNode):

google_calendar_id = '7hfea2godbmajrspfp30l23q1o@group.calendar.google.com' #replace with the id of your calendar!
calendar_node =  read_vertex_by_xid ('CAL-' + google_calendar_id)['ogit/_id']
task_id = create_task('RescheduleMeeting', 'Reschedule Meeting to After Vacation', calendar_node, {})

After the automation task with the above parameters is created, HIRO™ will immediately update the task status to RESOLVED, due to the fact that no Todo Variable has been provided in the parameters. For any Automation Task that is submitted without a Todo Variable, HIRO™ will automatically consider it RESOLVED, without any actual processing being done. We can read the Automation Task from the Graph and see that the status is RESOLVED.

task_status = read_vertex(task_id)['ogit/status']
print ('Task status: ' + task_status)

The result is:

Task status: RESOLVED

When an automation task is submitted (task state: NEW), it must be submitted with at least one Todo Variable for HIRO™ to work on. The task will then be processed by HIRO™ (task state: PROCESSING).Provided that HIRO™ has enough Knowledge to act on it, the objective of each Todo Variable will be achieved, and the Todo Variable will be removed. When all the Todo Variables are removed, the state of the task will be set to RESOLVED.

Add a Todo Variable

In order to have the automation task being processed by HIRO™, we add the generic Todo Variable ProcessIssue:

task_id = create_task('RescheduleMeetings', 'Reschedule meetings during my absence', calendar_node, {'/ProcessIssue':''})

Now we get a different result:

task_status = hiro.read_vertex(task_id)['ogit/status']
print ('Task status: ' + task_status)
Task status: PROCESSING

After a few minutes, HIRO™ will stop working on this issue, because there is no suitable Knowledge in the Knowledge Base:

task_status = hiro.read_vertex(task_id)['ogit/status']
print ('Task status: ' + task_status)
Task status: STOPPED

If there is not sufficient Knowledge in the Knowledge Base to automatically solve all objectives of the submitted Automation Task, HIRO™will change the status of the automation task to STOPPED, which means that the task needs to be completed externally by a Subject Matter Expert (SME). By default, the transition to STOPPED state is performed after 15 minutes of idle time have elapsed.

You can view the details of the task, the execution history and the associated node context in the Task Viewer tool(IV icon in HIRO Frontend). This is a helpful developer tool for troubleshooting if you encounter problems.

Stopped task in Task Viewer
Figure 2. Stopped Task in Task Viewer (IV)

Teaching HIRO™ to Solve the Task

Now that our task has been submitted to HIRO™ with a Todo Variable, it ends up in STOPPED state, because there is no available knowledge to apply by the HIRO™ Engine. The automation task shows up in the Automation Teaching Queue (ATQ) in the HIRO™ user interface. We login to HIRO™ as SME user and start a Teaching Session. Afterwards we translate the Teaching Session into a Knowledge Item. For the sake of brevity of this tutorial, we will only write a simple Knowledge Item that removes the ProcessIssue Todo variable, so that automation tasks will be resolved.

Stopped task in task automation queue
Figure 3. Stopped Task in Teaching Queue
Teaching session to enter knowledge
Figure 4. Teaching session in HIRO

The contents of our sample Knowledge Item looks like this:

  name: "I decide that nothing should be done."
  description: "I decide that nothing should be done, and finish the task."
  ogit/_type == "ogit/Schedule/Calendar"
  ogit/Automation/issueType == "RescheduleMeetings"
  NumberOfMeetingsRescheduled = 0

The next time the same task is sent to HIRO™, it will be handled by HIRO™ with the new Knowledge Item. To demonstrate this, we create another automation task with the same content as before. Then we check the task status in the Task Viewer (IV) in the HIRO™ user interface. The new task should be listed as RESOLVED. Finally, we use the API to check the task status and retrieve the number of rescheduled meetings (which is 0) from the Information Variable NumberOfMeetingsRescheduled:

task_id = create_task('RescheduleMeetings', 'Reschedule meetings during my absence', calendar_node, {'/ProcessIssue':''})

And after waiting until the task has been completed:

task = hiro.read_vertex(task_id)
print ('Task status: ' + task['ogit/status'])
print ('Number of rescheduled meetings: ' + task['/NumberOfMeetingsRescheduled'])
Task status: RESOLVED
'Number of rescheduled meetings: 0


To recap, we have learned how to submit an Automation Task to HIRO™ for processing. An Automation Task is represented in HIRO™ as a vertex of entity type ogit/Automation/AutomationIssue. There are a few mandatory attributes that we need to specify for each task, i.e. task type, subject, and origin node. Attributes of an Automation Task are also called Variables, when used in Knowledge Items. There are two types of variables: Todo Variables and Information Variables. As a developer you can use Information Variables to provide additional parameters for the task when sending it to HIRO™, and to read out relevant results after the task has been processed. A submitted Automation Task will only be processed by HIRO™, if we provide at least one Todo Variable (as an additional attribute) or else, HIRO™ will mark it as RESOLVED without any actual action being performed. After entering a new task for the first time, there is typically no suitable knowledge in the knowledge base, so that a SME and an AI Expert will conduct a Teaching Session in the HIRO™ Frontend, to teach HIRO™ the required knowledge. The next time we submit a task with the same contents, HIRO™ will be able to solve it automatically.

Now you are ready to build your own connector to send new tasks to HIRO™ for intelligent automation.