SmartWizards Layout.xml Reference

The SmartWizard's layout.xml definition file is the core component for a SmartWizard. The definition contained within the layout.xml file is used to make the wizard available within the thick and thin client K2 designers, and it defines the various screens and fields in the wizard and how they will behave.

WizardPage

The GUI of a SmartWizard is defined using WizardPage nodes. The WizardPage node contains a Header, a Body and a Footer property, as well as a Name, LoadandUnload attributes.

Name		Description
Attributes
Name		The unique identifier for the page, and cannot contain spaces.
Load		Event that will fire when the WizardPage loads (starts). These Events are defined in the SmartWizard layout.xml file.
Unload		Event that will fire when the WizardPage unloads (finishes). These Events are defined in the SmartWizard layout.xml file.
HelpURL		A Help URL may be defined in the WizardPages and the WizardPage nodes, to point to a specific URL for further help. At the WizardPages node it configures a generic target for all the help buttons within the wizard. At the WizardPage node it configures a specific target for that page in the wizard.
Nodes
Header		Contains the second part of the text that will appear in the title area of the wizard window (the first part comes from the folder location of the custom SmartWizard.
Body		Contains the Controls displayed within the wizard page.
Footer		Contains the instruction text displayed at the bottom of the wizard window.

Controls

The following Controls can be added within each WizardPage Body section. Keep in mind that the specific positioning of these control examples must be adjusted for your particular SmartWizard pages. They are provided in order to give you some guidance on how to use the controls.

Label

The label control is used to present text on the wizard page.

ComboBox

The ComboBox presents a drop down list and a single-line editable textbox, allowing the user to either type a value directly into the control or choose from a list of existing options. A ComboBox can present a dynamic drop down list when linked to a SmartObject, or a static list. See the Static List example from earlier in this topic, or use the dynamic example presented below.

Button

The button control presents the user with an icon linked to a set of Event actions.

RadioButton

This control presents the user with the circular radio button linked to a set of Event actions.

ToggleButton

This control presents the user with the toggle option button linked to a set of other controls.

ListBox

The ListBox control presents a drop down list on the wizard page. A ListBox can present a dynamic drop down list when linked to a SmartObject, or a static list.

CheckBox

The CheckBox control presents the check box and associated text on the wizard page.

K2TextBox

This control adds a text box to the wizard page, ready for user input where the user will be able to drag and drop a field from the context browser.

K2Data

The K2Data control provides a data field, where the user will be able to drag and drop a field from the context browser.

K2FilterGrid

The K2FilterGrid is used to Filter the results from a List Method.

K2InputMappingGrid

The K2InputMappingGrid is used to load and display all input properties for the method specified.

K2ReturnMappingGrid

The K2ReturnMappingGrid is used to load and display all return properties for a specified method. Only data fields can be used with return grids to map values back.

K2ReferenceList

The K2ReferenceList is used to load Item References created in previous wizards, where the ServiceType and ServiceObjectType match those of the SmartObject from which the reference was created.

Image

The image control displays a custom image on the wizard page.

SharePoint BreadCrumb

The SharePoint SmartObject BreadCrumb control presents the folder structure of the available SmartObjects within the SharePoint environment and allows the user to drill down into those folders to select the SmartObject data

Line

The line control is used to add a visual divider line on the wizard page.

Folder Breadcrumb

The Folder Breadcrumb control presents the folder structure of the available SmartObjects and allows the user to drill down into those folders to select the SmartObject data similar to the SharePoint Breadcrumb above. The difference between the folder and the SharePoint Breadcrumbs is that the Folder Breadcrumb has a double click method to drill down and a single click for selecting an item.

K2DatePicker

The Date Picker control is used to select dates on the wizard page

K2TimePicker

The Time Picker control is used to select time on the wizard page.

ModalDialogControl

The ModalDialogControl is used to add a pop up dialog that allows the user to select the data they want.

Control Properties

The following table shows the Controls and the properties associated with each one

Attribute	Label	ComboBox	Button	RadioButton	ToggleButton	ListBox	CheckBox	K2TextBox	K2Data	K2FilterGrid	K2InputMappingGrid	K2ReturnMappingGrid	K2ReferenceList	Image	Line	Breadcrumb	FolderBreadcrumb	DatePicker	TimePicker	ModalDialogControl	Description
Name	*	*	*	*	*	*	*	*	*	*	*	*	*	*	*	*	*	*	*	*	This attribute identifies the control. The name must be unique within the K2 SmartWizards configuration and must not contain any spaces.
Text	*		*	*	*		*	*	*												The content of the label to be presented on the SmartWizard page.
Height	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The height in pixels of the control as presented in the thick client Wizards.
Width	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The width in pixels of the control as presented in the thick client Wizards.
Top	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The pixel position from the top of the Wizard page as presented in the thick client Wizards.
Left	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The pixel position from the left of the Wizard page as presented in the thick client Wizards.
altHeight	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The width in pixels of the control as presented in the thin client Wizards.
altWidth	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The width in pixels of the control as presented in the thin client Wizards.
altTop	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The pixel position from the top of the Wizard page as presented in the thin client Wizards
altLeft	*	*	*	*	*	*	*	*		*	*	*	*	*	*	*	*	*	*	*	The pixel position from the left of the Wizard page as presented in the thin client Wizards.
Checked							*														The Event to perform when the check box is no longer in the mouse focus.
MaxLength								*													Configures the largest size of the input text.
Icon			*			*															This node configures the icon that will display to the left of the value in the drop down of the thin client.
LinkedToControl		*	*	*			*			*	*	*	*	*	*	*	*				Matches the visible or auto-hide status of this control with the referenced control.
IsEnabled		*	*	*	*	*	*	*		*	*	*	*	*		*	*	*	*	*	A Boolean setting to show the combo box or to present it as greyed out.
Click		*	*	*		*	*	*					*	*		*	*			*	The Event to perform when the combo box is clicked.
Double Click																	*			*	The Event to perform when the control is double clicked.
Load		*	*	*		*	*	*		*	*	*	*	*		*	*			*	The Event to perform when the combo box is first loaded.
LostFocus		*	*			*		*		*	*	*	*	*		*	*			*	The Event to perform when the combo box is no longer in the mouse focus.
Required		*		*		*	*	*	*				*			*	*			*	Sets having a value for the combobox as a pre-condition for completing the WizardPage. This will add a red indicator to the control to show that it is a required field.
ResultType		*				*		*								*	*			*	Sets the expected data load type for the control. It can be one of three types: Service Instance, SmartObject, and None (used for static values)
ConfirmText		*	*	*	*	*	*	*					*			*	*				If this is specified on a control that has an event that fires, it will bring up a dialog that shows the text specified here where the user would choose yes or no, and depending on the option chosen, the event will fire or not.
SpinnerText		*	*	*	*	*	*	*					*			*	*				The text that will display on the spinner when the event on the control is fired.
InitialControls					*																Sets the controls that are toggled as 'enabled' on the page.
ToggleControls					*																Sets the controls that are toggeld as 'disabled' on the page.
WatermarkText								*													Grey text presented within the text box as a tip or instruction to the user.
Validation								*													The Validation Event to perform on the value of the text box before displaying user input.
Multiline								*													Sets whether or not the text box covers a single line or spreads to multiple lines on the page.
AllowUserInput								*													Setting this option to "false" will disable text input into the control so that the user can only use drag-and-drop inputs from the K2 context in the Object Browser.
ServiceType													*								Used to filter out un-wanted data by specifying a reference to a specific namespace, i.e. sourcecode.smartobjects.services.crm.
ServiceObjectType													*								Used to filter out un-wanted data by specifying an object type, i.e. entity.
Source														*							The path and name of the image file. The Image control supports only png images.
Values		*																			Creates mappings to Static Values or ServiceInstance and SmartObject data set by the ResultType property.
CategoryIcon																*	*			*	This node configures the icon that will display next to the SharePoint Category folders.
InfoBar																*	*			*	Used to create a popup that that can be configured to present contect information, for example, to inform the user what may be done if certain items are not in the list of items. The InfoBar has the following required sub-properties: InfoBarWidth: Sets the width of the popup that will display. InfoBarHeight: Sets the height of the popup that will display. The InfoBar then has a subnode to define the text that will be displayed in the popup. InfoBarText: Sets the text that will be displayed in the popup. \n can be used to state that the text following the \n should display on a new line
Drilldown																*	*			*	Sets the event that fires when the user clicks on an item in the list of the breadcrumb and that item is a category that contains other items.
IncludeTime																	*				Sets the property to add time to a date
DateFormat																	*				Specifies how the date is formated.
BreadCrumbType																				* (FolderBreadCrumb/FileBreadCrumb)
Browse																				*	Event fired when Ellipses button is clicked
* = Required Property, * = Optional Property

The SmartWizard Control definitions provide the user interaction and graphical presentation of the SmartWizard. All SmartWizard Controls have the Name property. This property is used in the various data mapping nodes for identifying which control will be used for input or return data. When used for mapping purposes the Control name is contained within a curly bracket {nnnControl} reference.

Control Positions

Four properties are used to define where on the WizardPage a control will be displayed. One set of four is used for the thick client (Height, Width, Top, Left). Another set is used for the thin client (altHeight, altWidth, altTop, altLeft).

For the thick client, the Top Left coordinates are 0,0 to bottom right 558, 380.

For the thin client, the altTop and altLeft coordinates are 0,0 to bottom right is 628, 500.

Thick client controls are typically spaced 30px vertically from one another and the labels are placed 5px lower than the corresponding control.

Static Values

The following controls may be configured with static control values:

• ComboBox
• TextBox
• ListBox

When creating a static drop down (K2ComboBox) control, the ReturnType must be set to 'None", and the <Values></Values> subnodes will specify the static list of values for the drop down. The snippet below shows an example of static values defined for a ComboBox:

Events

SmartWizard Events are where the actions of the SmartWizard take place. These events can either happen during the execution of the Wizard at design time, or at runtime when the workflow is executing the step.

An Event performs an action that has been defined in either a DataMappings node or a SmartObjectMappings node. DataMapping actions are typically only used in design time as they take Wizard data values from one control to another. SmartObjectMapping can be used for either design time or runtime actions, depending of where the Event is called.

The Events node contains Event subnodes that defines data based input and return action. An Event calls either a DataMapping or a SmartObjectMapping node,  identifying the target method to be performed. The Event subnode contains the following attributes:

Attribute	Use	Description
Name	Required	Identifies the Event. The name must be unique within the K2 SmartWizards configuration.
Type	Required	Identifies the SmartWizard data definition used in the Event, either a DataMapping or a SmartObjectMapping.
Target	Required	This identifies the data method used for the Event.

The snippet below is an example of a collection of Events.

Runtime

The Runtime section configures the Events that will be run at runtime, presenting each Event in a step sequence. Typically there would be at least one Event to run at runtime. The following table defines the attributes of the Step subnodes.

Attribute	Use	Description
ID	Required	Sets the sequence number for that runtime event.
Name	Required	This attribute identifies the Step. The name must be unique within the K2 SmartWizards configuration.
Event	Required	Calls the SmartWizard Event for that step.

The following XML sample provides an example of how this RuntimeSteps are configured.

Validations

The Validations node contains one or more Validation subnodes, refered to from the WizardPage Body text-based input controls. The snippet below shows an example of the Validations node.

Attribute	Use	Description
Name	Required	This attribute identifies the Validation. Name must be unique within the K2 SmartWizards XML file.
Expression	Required	The Regular Expression that expression that the input text will be validated against.
ErrorMessage	Required	The text message sent back to the WizardPage if the expression does not resolve successfully.

Data

DataMappings

The back end data channels of the K2 SmartWizard are defined through the DataMappings and SmartObjectMappings objects. These are container nodes for calling and sending data from one event to another, or from and to a SmartObject.

The DataMappings node is a container node for one or more DataMappingSet items that can be called from an Event, using the Type="DataMapping" Target="[DataMappingSetName]" attributes. Each DataMappingSet can contain multiple DataMappings elements.

The following table lists the attribute for the DataMapping element.

Attribute	Use	Description
Name	Required	Identifies the DataMapping object. The name must be unique within the K2 SmartWizards configuration.
InputControl	Optional	The SmartWizard Body Control from which the input value will be taken.
InputProperty	Optional	The data value for the InputControl.
ReturnControl	Optional	The SmartWizard Body Control to which a data value will be sent.
ReturnProperty	Optional	The data value sent to the ReturnControl.

SmartObjectMappings

SmartObjectMappings The SmartObjectMappings node is a container node for one or more SmartObjectMapping objects that can be called from an Event.

Attribute	Use	Description
Name	Required	Identifies the SmartObjectMapping object. The name must be unique within the K2 SmartWizards configuration.
SmartObject	Required	The K2 SmartObject system name being referenced in the mapping.
Method	Subnode	This is a complexType node with its own attributes and subnodes. Please see the following tables for further details.

The following examples shows an example of using a SmartObject to retrieve a list of Service Instances.

The following snippet shows an example of calling a Create Methods for a SmartObject, passing in values from text controls on the wizard page.

You can specify more than one Control to pass values to the SmartObject. For example, the first object will be parsed if the rdbUseReference is true and checked. If not it will use the second SmartObject.

Method

The SmartObjectMapping Method node lists the instance object type and the SmartObject properties accessed through the mapping. The Method attributes are as follows:

Attribute	Use	Description
Name	Required	Identifies the Method object. The name must be unique within the K2 SmartWizards configuration.
Type	Required	Sets the type of SmartObject Method.
ListControl	Optional	Identifies the control used to access the List data. For example the name of a ListBox in the Body Control section.
SaveReference	Optional	Configures whether a Save is performed once the Method has completed.
LoadReference	Optional	Configures whether or not values will be loaded from a Reference Object
Properties	Subnode	This is a complexType node with its own attributes, please see the following table for further details

Property

The Property subnode contains a Name object and then either an InputControl object or a ReturnProperty object. Typically a Property would identify an InputControl, and then a ReturnProperty Key and a ReturnProperty Value.

Attribute	Use	Description
Name	Required	Identifies the Property object. The name must be unique within the K2 SmartWizards configuration.
InputControl	Optional	Identifies the control from the SmartObject Body section that provides an input value to this property.
ReturnProperty	Optional	Identifies the SmartObject Return value as a Key or Value fields.

References

The Parent References node can contain one or more Reference Property objects. These are data objects that can either be used to save a reference to a certain SmartObject, or to load the reference and use the loaded reference’s properties in your wizard. For example:

• Creating an Entity: This creates a reference object and enables the reference’s properties to be used in other wizards by dragging the from the context browser.
• Updating an Entity: This loads the reference created in the previous wizard and automatically maps the required properties of the Load method specified in the Create with the properties in the Update method. This ensures that the user does not have to supply the ID of an entity again when needing to update or use the reference in a subsequent step in the workflow.

Attribute	Use	Description
DefaultLoad	SubNode	This node is used to store data regarding the load/read method for a specific SmartObject.
Name	Required	This attribute identifies the Reference object and is used for mapping purposes within the SmartWizard. The name must be unique within the K2 SmartWizards configuration.
SystemName	Required	This attribute is used to save the Reference when the Wizard completes.