Multiple-Select Functionality

Background

This article discusses XMPro’s Multiple-Select Browse Page functionality, how a System Administrator can install this functionality, and a step-by-step guide to configure the multi-select browse page functionIs a Stream Objects that performs mathematical and statistical operations.. This article is intended for advanced XMPro consultants.

The Browse Page functionality allows users to select one row of data at a time from a dataset. The Multiple-Select Browse Page functionality looks and feels like a traditional browse page, but it enables users to select more than one row of data at a time and add them altogether to an object group. The multi-select functionality helps save users a lot of redundant clicks, time and effort, when compared to a browse page where they have to select a single row of data at a time.

Steps

The following are the steps to install the multi-select functionality. After the installation steps have been completed, there is a step by step walkthrough to enable and configure the multi-select functionality.

Step 1

An XMPro System Administrator needs to download the following files

• Shared Library file
  • XC.XMWorkspaceExtensions.dll * This file should not be modified

• Active Server Page Extended file
  • Browse_Multi.aspx * This file should not be modified

• Custom XMPro TransformationIs a Stream Objects that alters the shape and form of data. Extensible Stylesheet Language file(s)
  • ActivityDisplay_MultiSelect.xsl
  • *This ActivityDisplay_MultiSelect.xsl is a custom stylesheet file that can be modified if necessary, by advanced users only – Users who have experience creating or editing style sheets using Extensible Stylesheet Language (XSL). By default, this sample stylesheet file provided includes the multi-select browse page function represented by a ‘magnifying glass’ or ‘browse page’ icon, alongside the regular ‘plus’ (add) and ‘minus’ (remove) icons found on an object group.
  • ObjectTemplates.xsl (download only if the ‘transform → custom’ folder does not already contain this file) * This file should not be modified

The files vary for XMPro v6.1 and XMPro v6.5 – please select the right files according to the respective installed XMPro version. The files for v6.1 can be downloaded from this link, and those for v6.5 can be downloaded from this link.

Step 2

Once the files have been downloaded for the respective XMPro version, they need to be placed in the XMPro Server folder and respective subfolders to enable the multi-select browse page. This is an important step as the multi-select function is currently a custom add-on and will need these files in order to make this functionality available onto the user’s current version of XMPro.

The following are the relative locations where the downloaded files need to be placed, respective to the user’s XMPro Server folder:

• XC.XMWorkspaceExtensions.dll
  •  <Drive> → inetpub → wwwroot → <XMPro Server Folder> → bin
  • * This file will already exist if the multiple-select browse page functionality has been previously set up
• Browse_Multi.aspx
  • <Drive> → inetpub → wwwroot → <XMPro Server Folder>
• ActivityDisplay_MultiSelect.xsl
  • <Drive> → inetpub → wwwroot → <XMPro Server Folder> → transform → custom
  • * This sample file also contains the stylesheet for the multi-file upload function, should the user choose to use both the functions on the same activityA specific step in a process.  It will be the user interface for that step (web form or a screen), for example, the Leave Application (screen interface or web form) will be the first Activity in the Leave Requisition process.  The Leave Application Authorization will be the second step or Activity in the Leave Requisition process.  One Process can have multiple activities., given that the respective dll and aspx files have already been installed for multi-file upload.
    It includes the multi-file upload function by replacing the ‘add a line’ function of the object group on the ‘add’ icon placed next to the ‘remove’ icon. 

* If the “custom” folder does not exist within the “transform” folder, go ahead and create it, and place the ObjectTemplates.xsl in it along with the ActivityDisplay_MultiSelect.xsl file.

* If the “custom” folder already exists within the “transform” folder:

• Then it should most likely already have the ObjectTemplates.xsl in there.
• If ObjectTemplates.xsl isn’t present, copy it from the downloaded file and place it in there.

*The provided .dll and .aspx system files should be used as-is. These are core library and active server page extended files that are needed to enable the multi-select functionality, and should not be modified.

High-Level View of Configuration

The following is the high-level view of all the steps that are necessary to configure the multi-select function. A detailed walkthrough will be covered in the next section of the article – Configuration Using a Sample Process.

1. Complete the Installation as listed above in this article.
2. Select the activity where multi-select function will be configured and type the custom stylesheets name in the ‘Stylesheet’ property for the activity. In this example, enter the name “ActivityDisplay_MultiSelect.xsl”
3. Create an object group on the same activity, and name it with the suffix “_Multi”. The suffix is case-sensitive.
4. Add a browse page field in the activity for the SQL integration. Associate the browse page controls with the object group created above to enable the multi-select function on the object group.

This object group can now be seen on the form with a “browse page” icon in addition to the regular “add” and “remove” icons.

Clicking on this browse page icon will retrieve the data from the database (as set up in the SQL integration), with a check box option on the left to select multiple rows.

With this, the multi-select function has been successfully configured.

Multiple-Select Functionality Example

Background Information

The sample process used to demonstrate the multi-select browse page functionality is a two-step process where in the first activity a request is raised to order parts for maintenance, and in the second step the order is reviewed and approved. The maintenance parts request activity uses the multiple-select functionality to enable users to bulk order parts from a common list of items.

The Maintenance Parts Request activity has an object group where the list of common parts can be accessed. The object group will have a ‘browse page’ icon on the header (next to the add/remove icons), which is the button for the multi-select function. Clicking on this button retrieves the list of parts and their related fields from the database, and multiple selections can then be made by clicking on the checkboxes of the rows and then clicking on the ‘select’ button. This screen behavior can be seen in the results section.

Step by Step Walkthrough

Step 1

Navigate to the process and activity on which the multi-selection functionality is going to be configured on, which in this case is the Maintenance Parts Request activity, to enable the Properties toolbar on the right hand side.

Step 2

Enter the custom stylesheet’s name (as copied across in the transform → custom folder in the installation step) in the ‘Stylesheet’ field. This is a free text field, and is not case-sensitive, hence the name can be typed in or copy-pasted.

Step 3

Click on the three-dotted icon on the ‘Object Groups’ option to open the Object Group configuration window

Step 4

Click on the ‘Add’ button to create a new Object Group

Step 5

Click on the newly created Object Group “NP1010ObjectGroup” to change its properties

Step 6

Update:

• Description to “Maintenance Object Group”
• Name to “NP1010Maintenance_Multi”

*The suffix “_Multi” as below is necessary for the multi-select functionality to work, and is case-sensitive. This enables the files as set up in the installation section to recognize that this Object Group associates to the Multi-Select Browse Page functionality.

Step 7

Once the Object Group is set up navigate in to the activity, either associate existing fields, or create the fields that need to be associated with the Multi-Select Browse Page functionality with the “Maintenance Object Group”.

*As an option, new fields, aside from the first browse page field, can automatically be created using the Integration Wizard which you will see in Step 13.

*The first browse page field associated to the Object Group index wise (in case there is more than one browse page field) is used by the Multi-Select Browse Page function to associate with the Multi-Select button

Step 8

Next click on the Browse Page field as set up above, and select on Visible = ‘False’ from the drop down options to hide this field on the form

*This step is done as typically a multi-select functionality would be configured to allow users to make multiple selections at a time from the browse page window, and not have to make individual selections on each row on the object group. Making visible property as ‘false’ hides the browse page column from the object group.

*Alternatively, the user can choose to display the browse page field associated with the multi-select function by choosing the visible property value as ‘true’. This will display the column with the browse page icon once the results are loaded on the screen, and give the users the ability to either change the particular row’s values or add new rows and select values from them using this field on the individual rows.

A screenshot of both these options is displayed in the next section of this article – ‘Output on Workspace’

Step 9

Run the Integration Wizard on the Browse Page Field “NP1050MultiSelectObject”

*It is important to note that the integration has to be run on a Browse Page field (and not on any other field or on the activity) as the setup files from the installation section use this field to emulate the Browse Page function

Step 10

Select ‘XMPro SQL Connector’ as the Plugin and the relevant database in the Initializing Parameters’ Connection field in the Connector tab

Step 11

Choose the relevant data table as the Source Object in the Objects tab

Step 12

Select ‘Read’ as the Allowed Operation in the Operations tab

Step 13

Select all the relevant data columns as the Output Mappings in the Output Properties tab

Step 14

Select the following:

• NP1010Maintenance_Multi in the Object Groups drop down
• All relevant fields on the activity against the respective objects from the data table

*Note that <<New>> can be selected as the Mapped Control in the event that the fields to be mapped don’t already exist on the activity, and they will then be automatically created and associated to the Object Group

Step 15

Configure conditional mappings if any on the Conditional Mappings tab, which is none in this sample scenario

Step 16

Give the integration a meaningful name as below, “Maintenance Multi-Select Browse Integration” and then click on “Finish” on the Save tab

Output on Workspace

Log in to the XMPro site and navigate to the form or activity where the multi-select function was configured. The multi-select browse page functionality button associated with the object group is shown below:

Once the multi-select button is clicked, the following pop-up window appears:

The multi-select browse page looks and feels the same way as a regular browse page, with the exception that instead of being able to select only one row at a time, the user is able to select multiple rows at a time with the checkbox option on the left

Here several rows of data can be selected at a time. Click on ‘Select’ to add all the selected rows to the object group at once:

Click on the ‘Select All Items’ checkbox in order to check all the rows, or click it for a second time to uncheck all the rows

All the selected rows get added to the object group as below:

The field ‘Quantity’ although not mapped to any data column through the integration, was added to the object group, and demonstrates the capability to have solely user-input columns associated with the rows added from the multi-select function

Screenshot with Browse Page field hidden (From Config. Step 8)

Screenshot with Browse Page field visible (From Config. Step 8)

A line can also be added to enter all manual values in a row by clicking on the ‘plus’ icon:

Any row of data can be deleted by selecting the specific row(s) and clicking on the ‘minus’ icon: