When developing workflow apps, it is common for data selections to be input to the app during the design stage for use in input forms that will be operated by users.
In some cases it may be desirable to use these same data selections in multiple different apps, in which case repeating the input process all over again would be time-consuming. In Questetra you can export such data in XML format, therefore creating a handy file that can be transferred to other apps and platforms with ease.
This can be achieved with various methods, some of which include some automation, depending on which edition of Questetra is being used.
The Format of Choice XML
As described in R3190: Format of Choice XML a choice master contains two main components; Elements and Attributes.
Elements
Elements are the building blocks of the XML, and we will use two in this example.
- <items>: This is the root element of choice XML. All other elements and attributes will be contained within this element.
- <item>: This is to contain individual choices. Multiple <item> elements will be contained within one (items) element.
Attributes
Attributes are the data relating to one specific choice within the XML
- Value: The choice ID
- Display: the label that is displayed in input forms
Methods of Creating Choice Master XML
Manual Export from a Select-type Data Item
Select-type data items contain a function to export data held in the data item as an XML file. However, first you need to enter the data into the data item. This can be done in the App Modeler > Data Item tab, create a Select-type data item and click the Edit icon to open the edit window. Initially, the data item will have the type of data source set to “Fixed choice list” by default, and as a result the Choices section will be displayed.
To create choice master XML you should first manually enter data into the Choices section. You can do this by clicking on each individual item in the list, or by using the “Edit in CSV format” function which allows you to create a list in a text editor window where the Choice ID and the Label must be separated by a comma.
Once the data has been entered, it can be exported in XML format by clicking the “Add-on file” button at the bottom of the Choices section and selecting the option “Export Add-on file”.
This will download an XML file to your computer that can be used as a choice master for other Select-type data items and workflow apps. It is possible for Select-type data items to reference this data as an add-on file, which will be explained further in the next section, or it can be imported directly to a Select-type data item using the Add-on file > Import Add-on file buttons, which will import the data as a fixed choice list.
Using a Text Editor
XML files can be created using a simple text editor, such as Notepad or Wordpad, and though there is some code involved, it is relatively easy to write or even copy and then fill in with the data that you want to use.
The code below is an example that can be used for selecting a company, but by swapping the company names for any other character string, any kind of data can be represented using this code.
<?xml version="1.0" encoding="UTF-8"?>
<items>
<item value="1" display="Alpha Corp" />
<item value="2" display="Beta Inc." />
<item value="3" display="Gamma Ltd" />
<item value="4" display="Delta PLC" />
</items>The first line in the code is necessary for determining that the file is in fact an XML file, and the version and type of encoding that will be used. UTF-16 encoding is also available, but for text files like we will be using in this example we will use UTF-8. So for any choice master files you wish to create for use in a Workflow App the top line will always be the same.
Below the first line you must open an “items” tag using “<items>”, and once all of your items have been added it is important to close this tag using “</items>, as seen at the bottom of the code example.
Between the <items></items> tags you must place each of the items you wish to list, which must include a “value”, which is the Choice ID, and “display”, which is the Label that can actually be seen in the selection options when you input to the Data Item in the form as a processor of a task in the Workflow.
These rows should follow the format:
<item value=”[ID of your choice]” display=”[Label of your choice]” />In the example above, the values have been set as “1”, “2”, “3”, etc. but if you are using items that have a specific ID associated with them, you may use these IDs in the “value” section. Please note that each “value” (or ID) must be unique; if there are multiple values that are identical, only the first one will be displayed and all subsequent items with duplicate values will not be visible.
-
To include characters that need to be escaped in XML in an attribute value, write them as entity references
If unescaped characters are contained, the error “No choices” will occur when uploading to Questetra BPM Suite
- & ⇒ &
- < ⇒ <
- > ⇒ >
- ” ⇒ "
- ‘ ⇒ '
Using [Update Choices]
The [Update Choices] auto step is capable of saving information held in a Select-type data item as either an Add-on file or an App-shared Add-on file, the latter of which allows the imported data to be referenced by other apps on the same platform.
To demonstrate this, we will use a Select-type (Check box) data item called “Master Data Check”, and select this in the field “Select data item whose choices will be saved”. You can name the Add-on file that will be created anything you like, but here we will name it “Client Master Data”.
Once this step has completed processing, the created Add-on file will be visible in the relevant list. In the example below, the master file has been saved to the App-shared Add-on list.
From here the file can be downloaded in XML format by clicking on the download button.
Exporting Data Using Expression Language
Export from String-type
It is possible to convert text input to a String-type data item into XML using [Generate Text File] that has been prepared with EL syntax. In this way you can create a choice master by simply typing the desired choices into the data item.
Reference: R2272: Output of Strings via EL syntax
The first requirement for this is a multi-line String-type data item, as this allows for multiple choices to be output in the XML. When entering the choices into the text box, each choice must be separated by a line break (i.e. on a new line) in order for the EL to recognise it as a separate item.
The [Generate Text File] step must be prepared with the following code in the “C4: Contents of the text file” section.
<?xml version="1.0" encoding="UTF-8" ?>
<items>
#{#joiner.join(#q_client_data?.split(#NL).![#this + '" display="' + #this], '<item value="', '" />', #NL)}
</items>Please note that the part “q_client_data” is the field name for the String-type (mulitple lines) data item used in this example. When you are preparing your own app, this section of the code must be replaced with the field name of the String-type data item you have created.
Also, in this example, the item value (ID) and display (label) will be identical, however this will not adversely affect the efficacy of the choice master XML that will be created.
Export from Select-type
Using the same Select-type data item that was used to create the Add-on file in the Using [Update Choices] section, an XML choice master can be created using the [Generate Text File] step by typing a combination of XML structure and EL expressions into “C4: Contents of the text file”. In this way, it is possible to generate a choice master from a subset of an existing choice list.
You will need to set up a File-type data item to save the XML output, which will be selected in “C1: File type data item to save the text file”, and type in a file name of your choice in “C3: Saving file name”; here we will name the file “Choice Master XML” and add an expression to append the process ID as a suffix.
As described in the “Using a Text Editor” section, the header and <items> tags must be input as normal:
<?xml version="1.0" encoding="UTF-8" ?>
<items>
</items>Now, in order to pull the desired data from the Select-type data item, we must insert EL syntax between the <items> tags. The EL we will use can be found in R2272: Output of Strings via EL syntax under the Advanced Output via Functions section.
#{#joiner.join(#q_master_data_check?.![value + '" display="' + display], '<item value="', '" />', #NL )}The above code will pull all items from the Select-type (Check Box) data item that have been checked in the preceding Human Task.
Please note the section of the code:
-
- q_master_data_check: this is the Field name for the Select-type (Check Box). Please edit this to the Field name of the Select-type data item you use in your App.
When the process is run, the input form will allow users to select all options from those listed in the App-shared Add-on file.
Each selected option will be pulled into the text generated by the [Generate Text File] step, and output in the XML format.
External Service Integration
It is also possible to import data from an external cloud service in order for it to be used as choice data. The way to do this has been described in detail in the following articles, for the services Google Sheets and kintone respectively:
However, once the data has been imported to the workflow platform, you may want to convert it to XML so that it can be easily exported to other platforms. Using BPMN icons such as [Google Sheets: Download Choice Data], data from an external source can be imported automatically into an app, saved in a Select-type data item, and then converted into an XML file using the technique described above in the section Exporting Data Using Expression Language.
Automatically Importing Data
By inserting a [Google Sheets: Download Choice Data] step after the “Start” Human Task in the workflow we have already created, we are able to automatically import data held in a spreadsheet into the data items we set up to hold the client IDs and client data.
The above diagram also shows an additional Human Task between the “Download Choices” and “Update Options” auto-steps. This is to check that the imported data is as expected, but this step is not necessary if you wish to reduce the number of manual steps in the process.
You can see how to set up the [Google Sheets: Download Choice Data] by referring to the page Utilize Customer Data on Google Sheets as Choices.
With the addition of another automated step the amount of effort required to convert spreadsheet data into an XML file that can be used on any workflow platform becomes minimal, while the control over what data is included in the XML and what is omitted is retained by the user.