WAW_dialog_doc.txt

	********************************************************************************
	** DOCUMENTATION OF WAW DIALOG XML FORMAT
	********************************************************************************
	Uses XSD 1.0
	WARNING: Some of the elements must be in the specified order as attribute "maxOccurs" with value "unbounded"
	of elements inside the <xs:all> tag is not allowed for XSD 1.0 (https://www.w3.org/2001/XMLSchema.xsd)
	(It is allowed for XSD 1.1 but there is no validation in Python for XSD 1.1 so we have to use XSD 1.0)
	Instead of <xs:all> tag this schema uses <xs:sequence minOccurs="1" maxOccurs="1"> tag which allows "unbounded"
	value of "maxOccurs" attribute of inside tags.

	Sometimes you want to build more dialogs with very similar structure,
	e.g. one online dialog which will reside on the server, and the local one
	which will be always available but will not contain some functionality.
	For this purpose there is the `scope` attribute which indicates whether
	to include this tag to output dialog or not.
	- following node will be included only if server dialog is built:
	<node scope="type-server"/>
	- following node will be included in all built dialogs:
	<node/>

	**********************************************************************
	** <nodes>
	**********************************************************************
	Elements
		<import>
		<autogenerate>
		<node>
	Attributes
		none
	Example
		<nodes>
			<import>dialog/chitchat.xml</import>
			<autogenerate>...</autogenerate>
			<node>...</node>
			<node>...</node>
			<import>dialog/manual.xml</import>
			<node>...</node>
		</nodes>

	************************************************************
	** <import>
	************************************************************
	This tag contains a path to an imported file beginning from the modelset directory. Use slash as a path delimiter. Target should be a valid xml.
	All <node> from root <nodes> of imported file whose condition differs from conditions of nodes we already have are append to the tree.
	Context of imported nodes with the same condition as already is in the tree is merged into context of corresponding node, not overwriting already present variables.
	Example
		<import>dialog/chitchat.xml</import>

	************************************************************
	** <autogenerate>
	************************************************************
	Elements
		elements depend on type (in fact anything is allowed)
			if type = abort
				<message>
			if type = again
				<message>
			if type = back
				<message>
			if type = repeat
				<attempts> number of attempts before user is returned to the main menu
				<outputs>
			if type = generic
				anything (any valid xml structure)
	Attributes
		type REQUIRED Specifies a type of the autogeneration
			Values
				'abort' Generates node for returning to the main menu
				'again' Generates node for repeating last question
				'back' Generates node for returning to the previous node
				'repeat' generate nodes for asking user for input repeatedly until the user attempts exhausted
				'generic' generate everything to each level of dialog (e.g. if you want to generate structure to call agent from everywhere)
		propagate
			Values
				'true' It automatically repeats this node settings in sublevels
				'false'
			Default: 'true'
		on
			Values
				'true'
				'false' Switch off generating this node.

	************************************************************
	** <node>
	************************************************************
	Elements
		<condition> (only once)
		<context> (only once)
		<output> (only once)
		<goto> (only once)
		<nodes> (only once)
		<handlers> (only once)
		<slots> (only once)
		<responses> (only once)
		<actions> (only once)
		<digress_in> (only once)
		<digress_out> (only once)
		<digress_out_slots> (only once)
		<metadata> (only once)
	Attributes
		name (autogenerated if not specified) Node names can only contain letters, numbers and underscores.
	Example
		<node name="Dummy_node1">
			<condition>#INTENT_DUMMY</condition>
			<context>...</context>
			<output>...</output>
			<goto>...</goto>
			<nodes>...</nodes>
			<handlers>...</handlers>
			<slots>...</slots>
			<responses>...</responses>
			<actions>...</actions>
			<digress_in>returns</digress_in>
		</node>

	**************************************************
	** <outputs>
	**************************************************
	It specifies outputs for repeat nodes. First output is used in first turn, last is used while returning to the main menu.
	If there is not enough outputs for all attempts, the second from the end is repeated.
	Elements
		<output>
	Attributes
		none
	Example
		<outputs>
			<output>...</output>
			<output>...</output>
			<output>...</output>
		</outputs>

	**************************************************
	** <condition>
	**************************************************
	It represents a condition under which this node will be used in the conversation. Any combination of intents, entities, context variables, and special conditions is allowed.
	Expressions can be concatenated by "and" or "or" and even brackets are allowed, although the UI does not show them properly.
	'<' and '>' signs have to be replaced with '&lt;' and '&gt;' respectively.
	See https://www.ibm.com/watson/developercloud/doc/conversation/dialog-conditions.html for more information.
	See https://www.ibm.com/watson/developercloud/doc/conversation/expression-language.html for accessing global variables.
	Default value: 'anything_else' (allows to let the last node as the default node)
	Attributes
		confidenceThreshold (NOT IMPLEMENTED YET!)
	Example
		<condition confidenceThreshold="0.78">@song or @artist</condition>

	**************************************************
	** <context>
	**************************************************
	This tag allows adding custom variables.
	Child elements names are taken as variable names and their inside texts as their values. (e. g. <agentName>Volvord</agentName> creates the variable named "agentName" with the value "Volvord")
	If an attribute "type" with the value "number" is present, the variable is considered as numeric and no '"' are added (e. g. <attempts type="number">5</attempts> creates the numeric variable named "attempts" with the value 5)
    If an attribute "type" with the value "boolean" is present, the variable is considered as boolean and no '"' are added (e. g. <filledIn type="boolean">True</filledIn> creates a boolean value named "filledIn" with the value true)
	To expand variable values inside other variables, glue strings, add numbers, and add items to a list, use expression evaluation in string values of the JSON update structures. https://www.ibm.com/watson/developercloud/doc/conversation/expression-language.html
	'<' and '>' signs have to be replaced with '&lt;' and '&gt;' respectively.
	Default value: null (no context)
	If there are more variables with the same name, both will appear in the output JSON, but service will use only the last of them.
	Elements
		any
	Attributes
		none
	Example
		<context>
			<myStringVariable>Hello world!</myStringVariable>
			<myIntVariable type="number">2</myIntVariable>
		</context>
		This will create variable named "myStringVariable" with the value "Hello world!" and variable named "myIntVariable" with the value 2.

	**************************************************
	** <output>
	**************************************************
	Specifies the response.
	It is possible to add any custom variables as in <context>.
	If tag <text> is present, it is used as text output in conversation.
	For multiple responses feature use <textValues> tag.
	Elements (in this order!)
		<text> (only once)
		or <textValues> (only once)
		any
	Attributes
		none
	Example
		<output>
			<text>How are you?</text>
			<speech>Hello, how are you?</speech>
		</output>
		or
		<output>
			<textValues>
			...
			</textValues>
			<speech>Hello, how are you?</speech>
		</output>

	**************************************************
	** <goto>
	**************************************************
	Represents a jump to another node or to another type of next step.
	Elements (in this order)
		<behavior> (only once)
		<target> REQUIRED (only once)
		<selector> (only once)
	Attributes
		scope
	Example
		<goto>
			<behavior>jump_to</behavior>
			<target>node_to_go<target>
			<selector>user_input<selector>
		</goto>

	**************************************************
	** <handlers>
	**************************************************
	Specifies handlers.
	Elements
		<handler>
	Attributes
		none
	Example
		<handlers>
			<handler>...</handler>
			<handler>...</handler>
			<handler>...</handler>
		</handlers>

	**************************************************
	** <slots>
	**************************************************
	Specifies slots.
	Elements
		<slot>
	Attributes
		none
	Example
		<slots>
			<slot>...</slot>
			<slot>...</slot>
			<slot>...</slot>
		</slots>

	**************************************************
	** <responses>
	**************************************************
	Specifies responses.
	Elements
		<response>
	Attributes
		none
	Example
		<responses>
			<response>...</response>
			<response>...</response>
			<response>...</response>
		</responses>

	**************************************************
	** <actions>
	**************************************************
	Specifies actions.
	Elements
		<action>
	Attributes
		none
	Example
		<actions>
			<action>...</action>
			<action>...</action>
			<action>...</action>
		</actions>

	**************************************************
	** <digress_in> (and also digress_out and digress_out_slots)
	**************************************************
	Specifies digression settings of this node.
	For more information see https://console.bluemix.net/docs/services/conversation/dialog-runtime.html#digression-tutorial

	**************************************************
	** <metadata>
	**************************************************
	The metadata for the dialog node.

	**************************************************
	** <text>
	**************************************************
	Specifies the output text.
	Default value: empty string

	**************************************************
	** <textValues>
	**************************************************
	Enables multiple responses.
	Elements (in this order!)
		<values>
		<append>
		<selection_policy>
	Attributes
		none
	Example
		<textValues>
			<values>Hi.</values>
			<values>Nice to met you.</values>
			<append>false</append>
			<selection_policy>random</selection_policy>
		</textValues>

	Note: use the attribute structure=listItem for <values>
	e.g
	structure="listItem"
	if only one <values> item is specified

	**************************************************
	** <behavior>
	**************************************************
	Specifies what should happen after evaluation of this node.
	Allowed values
		'skip_user_input'
		'get_user_input'
		'jump_to'
		'reprompt'
		'skip_slot'
		'skip_all_slots'
	Default value: 'jump_to'

	**************************************************
	** <target>
	**************************************************
	Specifies a name of the node where to jump.
	There is build-in special key '::FIRST_SIBLING' that is
	replaced by the name of the first sibling of given dialog level.

	**************************************************
	** <selector>
	**************************************************
	Specifies where jump action continues processing.
	Allowed values
		'user input'
		'condition'
		'body'
	Default value: 'user_input'

	**************************************************
	** <handler>
	**************************************************
	Specifies handler.
	Elements
		<condition> (only once)
		<context> (only once)
		<output> (only once)
	Attributes
		eventName REQUIRED (specifies the type of the handled event)
	Example
		<handler eventName="input">
			<condition>#HELP</condition>
			<context>...</context>
			<output>...</output>
		</handler>

	**************************************************
	** <slot>
	**************************************************
	Specifies slot.
	Elements
		<handlers> (only once)
	Attributes
		variable REQUIRED
	Example
		<slot variable="$destination">
			<handlers>...</handlers>
		</slot>

	**************************************************
	** <response>
	**************************************************
	Specifies response.
	Elements
		<condition> (only once)
		<context> (only once)
		<output> (only once)
		<goto> (only once)
	Attributes
		none
	Example
		<response>
			<condition>#HELP</condition>
			<context>...</context>
			<output>...</output>
			<goto>...</goto>
		</response>

	**************************************************
	** <selection_policy>
	**************************************************
	Specifies a type of selecting text value for output
	Allowed values
		'random'
		'sequential'
	Default value: 'random'

	**************************************************
	** <append>
	**************************************************
	Specifies whether to append a value to an array or
	overwrite the values in the array with the new value.
	Allowed values
		'true'
		'false'
	Default value: 'true'