Hello World Robot Template

The Hello World template details how to create a robotic process that will open a text editor, type some text, and then close the text editor. This template introduces some of the methods referenced in the basic template; however, in this template, you will also learn how to have your robotic process interact with the keyboard.

When you use a template to create your robotic process, you are provided with a zip file containing your source code and a pre-built workflow in the robotic process configuration page. This page explains the contents of the workflow and the source code generated by the template.

Workflow

hello-world-workflow.png

The Hello World template's workflow contains six actions: Start, Open notepad, Process item, More items?, Close notepad, and End. Similar to an Appian process model, each workflow has a start and end action.

The rest of the actions are related to processing items. An item is a single element to be evaluated by the robotic process. Depending on the nature of your robotic processes, an item could be a person, an ID, a bank account, an invoice, a job identifier, etc. In this template, the item is sample text and the robotic process will process the item by typing the sample text in a text editor.

It's common for a robotic process to iterate over many items. For example, processing several employees, IDs, or bank accounts. To ensure each item has been processed, the workflow includes a loop. Loops utilize conditional actions to determine when all available items have been processed.

If you click the list icon 951644.png on any action, you'll see it is associated with a method. These methods are in the source code generated from the template. Within the source code, Appian has provided an outline of how you can configure each method.

Source code

The source code contains a class named MyRobot that implements the IRobot interface and is annotated with @Robot. Every Appian RPA robotic process must have the IRobot interface and @Robot annotation to allow the Appian RPA API to identify the class as a robot.

MyRobot includes several methods and attributes. These methods are directly associated with the workflow actions:

Method Description Associated Action
start() Provides initial information to the process. Start
openNotepad() Opens the Notepad application. Open notepad
processItem() Processes and sets the result status of each item. Process item
moreItems() Implements the workflow-guided loop. More items?
closeNotepad() Closes the Notepad application. Close notepad
end() Provides any final information to the process. End

The following sections explain how to work with each of the methods and attributes provided in the template.

Attributes

The first few lines in the template's source code reference the attributes and a constant related to the robotic process:

  • PAUSE (line 22) is a constant that indicates the process should pause for 2,000 milliseconds, the equivalent of 2 seconds. Since the working speed of a robotic process on an application is fast and continuous, and applications are designed for human use, the robotic process must adapt to the working speed of a human to avoid errors.
  • IJidokaServer (line 27) is responsible for communicating with the Appian RPA Server. The server is what communicates information to the console. This object notifies the server about the number of items to be processed and which item is currently being processed.
  • IWindows (line 32) represents a Windows operating system. This is what enables your robotic process to interact with the windows on your Windows machine.
  • currentItem (line 37) stores an index to control how many items have been processed. The server must receive this value as a 1-based index. For the first item, use 1.
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
	/**
	 * Pause between actions like persons do
	 */
	private static final int PAUSE = 2000;
	
	/**
	 * Server
	 */
	private IJidokaServer< ? > server;
	
	/**
	 * Windows module
	 */
	private IWindows windows;
	
	/**
	 * Current item index, base-1
	 */
	private int currentItem = 1;

start() method

The start() method is used to define the initial actions of the workflow. This is where you should initialize the objects that will be used by the robotic process and define how many items need to be processed.

  • server = (IJidokaServer< ? >) JidokaFactory.getServer(); (line 46) initializes IJidokaServer.
  • windows = IJidokaRobot.getInstance(this); (line 48) initializes IWindows, where this refers to the class that implements the IRobot interface. From this template, this would be the class MyRobot.
  • windows.typingPause(PAUSE); (line 51) indicates that the robotic process will pause after typing. Since it is using the PAUSE constant, there will be a 2,000 millisecond pause.
  • windows.mousePause(PAUSE); (line 52) indicates that the robotic process will pause after using the mouse. Since it is using the PAUSE constant, there will be a 2,000 millisecond pause.
  • server.getWorkflowParameters() (line 55) allows you to access parameterized robotic process variables. In this template, you will not need to access parameters. This code snippet is only an example of how to call the parameters if you need them.
  • server.setNumberOfItems(1); (line 66) indicates the number of items to process.

When configuring your robotic process, it's important to send logs to the server. Log information will appear in your robotic process's Execution log. This is where you can track where the robotic process is in the workflow and quickly see if your process has encountered any errors. This template references some of the methods that allow you to send log information to the server:

  • server.debug (line 56) sends a log message of type debug to the server.
  • server.warn (line 60) sends a log message of type warn to the server.
  • server.error (line 61) sends a log message of type error to the server.

For a list of log methods, see the Client module.

39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
    /**
     * Action "start"
     * @return
     * @throws Exception
     */
    public void start() throws Exception {
        
        server = (IJidokaServer< ? >) JidokaFactory.getServer();
        
        windows = IJidokaRobot.getInstance(this);
        
        // we set standard pause after writing or managing mouse
        windows.typingPause(PAUSE);
        windows.mousePause(PAUSE);
        
        // log parameters example
        server.getWorkflowParameters().entrySet().forEach((e) -> {
            server.debug(String.format("ParĂ¡metro [%s] = [%s]", e.getKey(), e.getValue()));
        });

        // other log types availables
        server.warn("Warn example");
        server.error("And error example");

        // we set number of items
        // on an actual robot, this number can be got from an application,
        // an Excel datasheet, etc.
        server.setNumberOfItems(1);
    }

openNotepad() method

The openNotepad() method opens the Notepad application. Although there are several ways to open the application, the Hello World template uses the Windows+R keyboard shortcut to open the Run dialog box on your Windows machine. From this dialog, the process will type the name of the application to open.

  • windows.pause(PAUSE); (line 76) tells the process to wait 2,000 milliseconds before moving to the next action.
  • windows.getKeyboard().windows("r").pause(PAUSE); (line 79) creates an instance of the IKeyboard interface. This interface solves the most common keyboard needs: typing text, using the Shift, Alt, and Control keys, keyboard arrows, etc. This interface provides the following methods:
    • windows("r") sends a command to press the Windows key and the letter r on the keyboard. This opens the Run dialog box on your Windows machine.
    • pause(PAUSE) tells the process to wait 2,000 milliseconds before using any other keyboard commands.
  • windows.typeText("notepad"); (line 82) mimics a human typing the word "notepad" in the Run dialog box.
  • windows.typeText(windows.getKeyboardSequence().typeReturn()); (line 85) mimics a human typing on the keyboard using a sequence. This behavior is only achievable using the IKeyboardSequence interface.
    • windows.getKeyboardSequence() creates an instance of the IKeyboardSequence interface. This interface simulates the press and release of keys. Using this interface, typeReturn will simulate a press and release of the Return key.
  • windows.showWindow(windows.getWindow() (line 87) interacts with the Notepad window to make it full screen.
  • windows.pause(PAUSE); (line 90) tells the process to wait 2,000 milliseconds before moving to the next action.
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
	/**
	 * Action "openNotepad"
	 * @return
	 * @throws Exception
	 */
	public void openNotepad() throws Exception {
		
		windows.pause(PAUSE);

		// Win+R
		windows.getKeyboard().windows("r").pause(PAUSE);
		
		// we write "notepad"
		windows.typeText("notepad");
		
		// press return key using IKeyboardSequence
		windows.typeText(windows.getKeyboardSequence().typeReturn());
		
		windows.showWindow(windows.getWindow(".*([Nn]otepad|[Bb]loc).*").gethWnd(), EShowWindowState.SW_MAXIMIZE);

		// we do an explicit pause
		windows.pause(PAUSE);
	}

processItem() method

The processItem() method is responsible for processing items. In this template, the item is the sample text that needs to be written in Notepad. Once the sample text is written, the current item result will be set to OK and a screenshot of the resource will be sent to the server.

  • String item = "this is a test"; (line 100) defines the item as a string with sample text.
  • server.setCurrentItem(currentItem, item); (line 103) tells the server which item is currently being processed. This requires two parameters:
    • currentItem is the 1-based item index of the total number of items to process.
    • item is the identification of the item. In this template, it is the sample text defined on line 100.
  • windows.typeText(item); (line 106) mimics a human typing the words "this is a test".
  • windows.keyboard().enter(); (line 109) mimics a human pressing the Return key.
  • server.setCurrentItemResultToOK(); (line 112) sets the current item result to OK. This accepts a string parameter where you can add a description of the processing result.
  • server.sendScreen(String.format("Snapshot over %s", item)); (line 115) sends a screenshot of the current resource with a description.
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
	/**
	 * Action "processItem"
	 * @return
	 * @throws Exception
	 */
	public void processItem() throws Exception {

		String item = "this is a test";

		// we inform that we are beginning the processing of an item
		server.setCurrentItem(currentItem, item);
		
		// we write the text into notepad
		windows.typeText(item);
		
		// press return key, we use IKeyboard instead of IKeyboardSequence
		windows.keyboard().enter();

		// we inform the item processing result
		server.setCurrentItemResultToOK();
		
		// we save the screenshot, it can be viewed in robot execution trace page on the console
		server.sendScreen(String.format("Snapshot over %s", item));
	}

moreItems() method

The moreItems() method determines if the robotic process should evaluate another item or move to the next step in the workflow. This method implements the workflow-guided loop and is associated with a conditional action.

Unlike generic actions, conditional actions always return a string or boolean value because the value must match with one of the output labels on your conditional workflow action. For example, if the moreItems() method returned a boolean value, there would only be two possible outputs for the condition and the output labels would be true and false.

In this case, the More items? action returns two outputs with the labels yes and no, so the method needs to return a string value to match the workflow outputs. When creating your own robotic process, you can have a conditional method return a string so you can have two or more outputs. Regardless of how many outputs you have, they must match the output labels in the workflow.

helloworld loop

This template does not continue the loop and only returns the string value no, so the robotic process will continue to the next action in the workflow.

118
119
120
121
122
123
124
125
    /**
     * Action "moreData"
     * @return
     * @throws Exception
     */
    public String moreData() throws Exception {
        return "no";
    }

closeNotepad() method

The closeNotepad() method is responsible for closing the application. Although there are a few ways to close an application, the Hello World template uses the Alt+F4 keyboard shortcut to close the open application.

  • windows.typeText(windows.getKeyboardSequence().typeAltF(4).pause().type("n")); (line 135) mimics a human typing on the keyboard using a sequence. This behavior is only achievable using the IKeyboardSequence interface.
    • windows.getKeyboardSequence() creates an instance of the IKeyboardSequence interface. This interface simulates the press and release of keys. Using this interface, a series of keyboard clicks occur: press the Alt key and the number 4 on the keyboard, release the keys and then wait. Finally, type the letter n when a dialog appears asking if you want to save the document.

Alternatively, you could use windows.keyboard().altF(4).pause().type("n"); (line 138) to close Notepad. This code performs the same actions, but it uses the IKeyboard interface instead.

127
128
129
130
131
132
133
134
135
136
137
138
139
  /**
     * Action "closeNotepad"
     * @return
     * @throws Exception
     */
    public void closeNotepad() throws Exception {
        
        // press alt+F4 + pause + "n"
        windows.typeText(windows.getKeyboardSequence().typeAltF(4).pause().type("n"));
        
        // another form
        //windows.keyboard().altF(4).pause().type("n");
    }

end() method

The end() method is used to define the final actions of the workflow and is associated with the End action. In your own robotic process, this is a good place to add final log messages that indicate the process has completed.

141
142
143
144
145
146
147
	/**
	 * Action "end"
	 * @return
	 * @throws Exception
	 */
	public void end() throws Exception {
	}

This version of the Appian RPA documentation was written for Appian 21.4, and does not represent the interfaces or functionality of other Appian versions.
Open in Github Built: Fri, Dec 03, 2021 (02:38:50 PM)

On This Page

FEEDBACK