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

AttributesAttribute ValuesValue DescriptionComment
TitleN/A[Input dialog title]N/A
ButtonTextOKOKText to set on OK button (defaults to OK)N/A
ButtonTextCancelCancelText to set on Cancel button (defaults to cancel).N/A


Detailed Description

Sub-actions

AttributesAttribute ValuesValue DescriptionComment
NameN/A
  • Variable name - Mandatory
  • Used in the SetVar action
  • Duplicate names are not allowed
  • All other naming restrictions from SetVar apply
N/A
ValueN/ADefault value to put in dialog input field.N/A
TypeN/AOne 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
LabelN/AText to display in front of the input field or for Category titleN/A
TooltipN/AGenerates a tooltip widget in the dialog, next to the labelN/A
ReadOnlyTrue/FalseTo prevent a field from being edited - Defaults to falseN/A
MandatoryTrue/FalseTo make editing of a field mandatory - Defaults to falseN/A
ExpandTrue/FalseFor 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
ListNameN/AOnly applies to CheckList and MultiList - name of the list created from the selected (checked) itemsN/A
ColorN/AOnly applies to Label - Hexadecimal RGB with a leading pound (eg. #FFE8E5).N/A
IconN/AOnly applies to Label - Font Awesome icon nameN/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.

AttributesAttribute ValuesValue DescriptionComment
LabelN/ADisplay value of list item - Set to its Value if omitted.N/A
ValueN/AValue of list item.Mandatory
ListNameN/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
SelectTrue/FalseOnly 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:

AttributesAttribute ValueValue DesceriptionComment
TargetN/AName of component to controlN/A
ModeN/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
SourceN/AName of component value that triggers the state changeN/A
ValueN/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