Variable: UserInput

Tag: UserInput

The UserInput variable lets users input a complex dialog box in their automation scripts.

Interrupts automation with a dialog pop-up. The input fields in the dialog are constructed from the Variable sub-actions content. Upon clicking Cancel, automation stops. Upon clicking OK on the dialog, the script resumes with one SetVar action for each Variable definition sub-action.

Variable names are generated from the "Name" tag value in each Variable sub-action and values are taken from the corresponding input fields in the dialog.

Tag Attributes

Attributes	Attribute Values	Value Description	Comment
Title	N/A	[Input dialog title]	N/A
ButtonTextOK	OK	Text to set on OK button (defaults to OK)	N/A
ButtonTextCancel	Cancel	Text to set on Cancel button (defaults to cancel).	N/A

Detailed Description

Sub-actions

Attributes	Attribute Values	Value Description	Comment
Name	N/A	Variable name - Mandatory Used in the SetVar action Duplicate names are not allowed All other naming restrictions from SetVar apply	N/A
Value	N/A	Default value to put in dialog input field.	N/A
Type	N/A	One of: Text, Bool, BoolToggle, List, CheckList, RadioList,MultiList, Date, DateInPast, Category - Defaults to TEXT The Type value is used to display a type of UI field an process some validations. All variables end up as text in the script. NB: Category does not define a variable, it creates a UI component in the dialog to visually group fields together List creates a combo box and demands a set of ListItem sub actions RadioList creates a list of Radio Buttons and demands a set of ListItem sub actions CheckList & MultiList create a list of items to check/select and demand a set of ListItem sub actions	Not mandatory
Label	N/A	Text to display in front of the input field or for Category title	N/A
Tooltip	N/A	Generates a tooltip widget in the dialog, next to the label	N/A
ReadOnly	True/False	To prevent a field from being edited - Defaults to false	N/A
Mandatory	True/False	To make editing of a field mandatory - Defaults to false	N/A
Expand	True/False	For Category type only - Defaults to true. If set to False, the category appears collapsed and the user must click it to see the input fields.	N/A
ListName	N/A	Only applies to CheckList and MultiList - name of the list created from the selected (checked) items	N/A
Color	N/A	Only applies to Label - Hexadecimal RGB with a leading pound (eg. #FFE8E5).	N/A
Icon	N/A	Only applies to Label - Font Awesome icon name	N/A

Label
To display a plain text item, use a variable of type Label.

<UserInput Title="Funeral Mist>
	<Variable name="Muh Label" Type="Label" label="MAYONNAISE UND SAUERKRAUT" Color="#FFE8E5" Icon="blargh icon" />
</UserInput>

XML

ListItem
When a Variable is defined as List, at least one ListItem is expected.

Attributes	Attribute Values	Value Description	Comment
Label	N/A	Display value of list item - Set to its Value if omitted.	N/A
Value	N/A	Value of list item.	Mandatory
ListName	N/A	Only applies to MultiList, CheckList. It populates the combo or checklist with the content of an existing script List. Label and Value must then reference attributes from the script list.	N/A
Select	True/False	Only applies to CheckList and MultiList - Defaults to False. Preselects the item in the list.	N/A

List items are sorted alphabetically by label in the dialog.

<ytriaAutomation Application="sapio365">
	<UserInput Title="Bernie ist mein Freund">
			<Variable name="You have 4 seconds to answer" Type="Category"/>
				<Variable name="Taxation" value="theft" Label="Taxation is" Tooltip="BUT WE NEED ROADS!" Type="Text" readonly="true" />
				<Variable name="Government" value="democide" Label="The State specializes in" Tooltip="Morbid Tales" />
				<Variable name="Carcass" value="true" Label="In 1988, Carcass released Reek Of Putrefaction" Tooltip="Test Bool" Type="Bool" />
				<Variable name="Venom" value="false" Label="In 1981, Venom released Black Metal" Tooltip="Test BoolToggle" Type="BoolToggle" />
				<Variable name="Saxon" value="1980" Label="When did Saxon release Strong Arm Of The Law" Tooltip="Test Date" Type="Date" />
				<Variable name="Salem" value="666" Label="How many albums did Sodom release" Tooltip="Test Number" Type="Number" />
				<Variable name="Khanate" Label="Weight" Tooltip="Test Number" Type="Number" mandatory="true" />
				<Variable name="Bad Brains" value="Quickness" Label="The best Bad Brains albums is" Tooltip="Test List" Type="List">
				<ListItem value="Attitude"/>
				<ListItem value="Live At CBGB 1982"/>
				<ListItem value="Rock For Light"/>
				<ListItem value="I Against I"/>
				<ListItem label="The short live record" value="Spirit Electricity"/>
				<ListItem value="The Youth Are Getting Restless"/>
				<ListItem value="Quickness"/>
				<ListItem value="Rise"/>
				<ListItem value="God Of Love"/>
				<ListItem label="The bad record" value="Build A Nation"/>
				<ListItem value="Into The Future"/>
			</Variable>
	</UserInput>
	<echo value="Taxation is {%Taxation%}"/>
	<echo value="Government is {%Government%}"/>
	<echo value="Carcass is {%Carcass%}"/>
	<echo value="Venom is {%Venom%}"/>
	<echo value="Saxon is {%Saxon%}"/>
	<echo value="Sodom is {%Sodom%}"/>
	<echo value="Khanate weighs {%Khanate%} tons"/>
	<echo value="Bad Brains is {%Bad Brains%}"/>
</ytriaAutomation>

XML

NOTE	Bool fields sometimes return 0/1 and sometimes true/false, to be debugged Date values cannot return times The Mandatory tag on a Variable seems to do nothing, to be debugged

Example using an explicit List and a List from SetVarListFromGridSelection to populate a list combo box:

<ytriaAutomation Application="sapio365">

	<!-- to be launched from a groups view with a selection of rows -->

	<!--
	Generate a List of SetVar from the current selection in the grid:
	- Set list name and target grid (target is not needed in sapio365 or main grids in Notes products)
	- Add variable names connected to grid column unique IDs (GCVD penultimate column) to store grid values into
	In this example "displayName", "groupType", "createdDateTime", "mailEnabled" are column unique IDs from the sapio365 Groups grid:
	-->

	<SetVarListFromGridSelection ListName="GroupList" GroupName="displayName" Type="groupType" Kreator="createdDateTime" Mail="mailEnabled"/>

	<list name="TheComboList" Action="SetVar" ListItemLabel="bonjour" ListItemValue="yo"/>
	<list name="TheComboList" Action="SetVar" ListItemLabel="mugre" ListItemValue="chaise"/>
	<list name="TheComboList" Action="SetVar" ListItemLabel="taxation" ListItemValue="theft"/>
	<list name="TheComboList" Action="SetVar" ListItemLabel="Pearly Gates" ListItemValue="TnA"/>

	<!-- now use these two lists in an input dialog -->

	<UserInput Title="Bernie ist mein Freund">
		<Variable name="Groups" Label="Group stuff" Tooltip="Test combo items from SetVarListFromGridSelection" Type="List">
			<ListItem ListName="GroupList" label="GroupName" value="Kreator"/>
		</Variable>
		<Variable name="List Combo" Label="List stuff" Tooltip="Test combo items from List" Type="List">
			<ListItem ListName="TheComboList" label="ListItemLabel" value="ListItemValue"/>
		</Variable>
	</UserInput>

	<echo value="Groups selection is {%Groups%}"/>
	<echo value="List Combo selection is {%List Combo%}"/>

</ytriaAutomation>

XML

Working with CheckList and MultiList:
These components allow users to select multiple values:

CheckList
Displays values to be selected via checkboxes
Ytria homemade. <--- What does this mean?

MultiList:
Displays values to be selected by a combination of clicks:

Click makes a single selection
CTRL+ click adds to selection
SHIFT + click adds range to selection

This component is standard HTML. It's recommended for large lists because the check list doesn't provide any means to quickly select all or none.

After OK is clicked, the selected items in each component will be stored in an automation LIST that must be used in a LOOP (even if the selection contains a single item), and whose action is SetVar. Each entry in the check list has a value and a label which can be identical.

The list named after the value set for the ListName parameter in the Variable, contains the list of selected item values (not labels).

In the example below, UserList is first created from the grid selection (with SetVarListFromGridSelection ), then used as

input in the variable varFromGridSelection. The entries later selected in the dialog are put into a new list named USERcheckList.

When USERcheckList is iterated in a loop, each ExecuteListAction sets the variable varFromGridSelection to the current value from USERcheckList.

If the user selection contains no item, the list doesn't exist and using it in a LOOP will result in an error. Make the Variable MANDATORY to force at least one selection.

<ytriaAutomation>

	<Select Lines="all"/>
	<SetVarListFromGridSelection ListName="UserList" Username="displayName" Email="userPrincipalName"/><!-- create list from grid selection (all rows) with values from the displayName 
	and userPrincipalName columns-->

	<!-- hard-coded list -->
	<list name="ListForCheckList" Action="SetVar" CheckListItemLabel="Le coq nu" CheckListItemValue="Show me your hats"/>
	<list name="ListForCheckList" Action="SetVar" CheckListItemLabel="mugre" CheckListItemValue="chaise"/>
	<list name="ListForCheckList" Action="SetVar" CheckListItemLabel="taxation" CheckListItemValue="theft"/>
	<list name="ListForCheckList" Action="SetVar" CheckListItemLabel="Le cormoran" CheckListItemValue="xHamster"/>

	<userinput Title="GWAR">
		<Variable name="varFromGridSelection" ListName="USERcheckList" Type="CheckList" Label="Select User:" Tooltip="Grid list selector"><!-- check list from grid selection -->
			<ListItem ListName="UserList" value="Email" label="Username" Select="true"/><!-- Select="true": all items selected by default -->
		</Variable>
		<Variable name="varFromScriptList" ListName="ScriptListCheckList" Type="CheckList" Label="Select zer:" Tooltip="Script list selector" mandatory="true"><!-- check list from 
		script list -->
			<ListItem ListName="ListForCheckList" value="CheckListItemValue" label="CheckListItemLabel"/>
		</Variable>
		<Variable name="varFromDlg" ListName="MyCheckList" Type="MultiList" Label="Select underwear:" Tooltip="Hand selector"><!-- check list hand-job -->
			<ListItem value="Caligula" select="true"/>
			<ListItem label="Vlad" value="The Impaler"/>
			<ListItem label="Joseph" value="The Vampire"/>
			<ListItem label="Winston Churchill" value="The cannibal" select="true"/>
			<ListItem label="Donald Obama" value="The serial droner"/>
		</Variable>
	</userinput>

	<Loop list="USERcheckList">
		<ExecuteListAction/>
		<echo value="Selected user: {%varFromGridSelection%}"/>
	</Loop>
	<Loop list="ScriptListCheckList">
		<ExecuteListAction/>
		<echo value="Selected zer: {%varFromScriptList%}"/>
	</Loop>
	<Loop list="MyCheckList">
		<ExecuteListAction/>
		<echo value="Selected underwear: {%varFromDlg%}"/>
	</Loop>
</ytriaAutomation>

XML

Echoes from the LOOP actions:

Click Cancel on the input dialog:

Adding Events
In order to control components (show/hide or enable/disable) in the dialog according to the state of a BoolToggle or a Bool, add an Event action inside the UserInput action:

Attributes	Attribute Value	Value Desceription	Comment
Target	N/A	Name of component to control	N/A
Mode	N/A	One of: Hide if equal: hideifeq Hide if not equal: hideifnoteq Disable if equal: disableifeq Disable if not equal: disableifnoteq Only these exact strings are permitted	N/A
Source	N/A	Name of component value that triggers the state change	N/A
Value	N/A	BoolToggle: True / False Bool: 1 or 0 Other field types cannot be used as state triggers	N/A

Example Script

<ytriaAutomation Application="sapio365">
	<UserInput Title="Bernie ist mein Freund">
		<Variable name="You-have-4- seconds-to-answer" Type="Category"/>
		<Variable name="Taxation" value="theft" Label="Taxation is" Tooltip="BUT WE NEED ROADS!" Type="Text" readonly="true" />
		<Variable name="Government" value="democide" Label="The State specializes in" Tooltip="Morbid Tales" />
		<Variable name="Carcass" value="true" Label="In 1988, Carcass released Reek Of Putrefaction" Tooltip="Test Bool" Type="Bool" />
		<Variable name="Venom" value="false" Label="In 1981, Venom released Black Metal" Tooltip="Test BoolToggle" Type="BoolToggle" />
		<Variable name="Khanate" Label="Weight" Tooltip="Test Number" Type="Number" mandatory="true" />
		<Event target="Khanate" mode="hideifeq" source="Venom" value="false"/>
		<Event target="Taxation" mode="disableifnoteq" source="Venom" value="false"/>
		<Event target="Government" mode="hideifnoteq" source="Carcass" value="1"/>
		<EventGlobal source="Carcass"/>
	</UserInput>
</ytriaAutomation>

XML