How To: Configure the Picker control to display a list of employees using a security provider

This topic shows you how to configure the Picker control to use the URM (User Role Manager) service to list employees in an organization. The URM service provides methods for returning user, group, role, and security label information from all configured providers. When you select employees from the list and click a button, a rule checks which employees are selected and sends an email to them.

Picker control listing employees from the URM service
Return employees in picker using AD

Scenario

You are scheduling an upcoming training. As part of the process you want to select multiple employees from a list and send an email to them.

Steps

In this scenario, you create an advanced SmartObject using the URM (User Role Manager) service. You create an item view based on the SmartObject. The item view contains a Picker control and a Send Email button. You configure a rule that sends an email to all employees you select in the picker when you click the button.

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Configure the Picker control.

From the Designer, create an advanced SmartObject called Employees using the URM (User Role Manager) service. Use the table below as a guide for adding properties. This is the SmartObject that stores employee information.

Property	Data Type	Key	SmartBox	Required	Unique
Name	Text	No	No	No	No
Description	Text	No	No	No	No
Email	Text	No	No	No	No
Manager	Text	No	No	No	No
DisplayName	Text	No	No	No	No
FQN	Text	No	No	No	No
UserName	Text	No	No	No	No
Sip Account	Text	No	No	No	No
Object SID	Text	No	No	No	No

Launch the Designer.
If you do not know how to access the Designer, see Accessing Sites.
Create categories to keep your work organized. Right-click All Items and select New Category. Use the image below as a guide for adding and naming categories.
Right-click Employees and select New SmartObject.
Name the SmartObject
Employees
and select the Advanced SmartObject option. You want to use the SmartObject Services which include the URM (User Role Manager) service. Click Create.
In the Properties and Methods tab, expand the URM Service and User nodes, and then drag Get Users from the ServiceObject Explorer onto the canvas as shown below.
.
The Add Method wizard opens. On the Details screen ensure List is selected as the Type as shown below. Click Next.
On the Inputs & Outputs screen click Create All. Input and return properties are created for all the properties of the Get Users SmartObject. You use these properties to configure the Picker control and rule. Click Next and then click Finish.
Click Finish to save and exit the SmartObject.

Configure the Picker control

In this step, you configure the Picker control to return values from the URM service.

Configure the Picker control. Create an Item View called Training Email. Include only a Button control and a Picker control. Name the button Send e-mail and use the Employees SmartObject as the data source for the Picker control. Select Name, Email and DisplayName as the filter properties, Email as the identifier property, and DisplayName as the display property.
1. Right-click the Employees category and select New View.
2. In the General tab, name the view
  Training Email
  and keep the Item View type. Click Create.
3. Add a Picker control and a Button control to the canvas by dragging the items from the Toolbox onto the canvas and dropping them into cells.
4. Assign a name and text value to the Button control. Select the control. In the Properties on the right side of your screen, change the Name to
  Send EmailButton
  and add a Text value of
  Send Email
5. Next configure the data source to use for the Picker control. Select the control and click the ellipsis next to SmartObject in the Data Source section.
6. The Configure Data Source dialog opens. Click the ellipsis next to SmartObject.
7. Expand the folders where you saved the Employees SmartObject. Select the SmartObject and click OK.
8. Specify SmartObject properties on which you want to search when you type a value in the picker at runtime. Uncheck All next to Filter Properties and then mark the check boxes next to Name, Email and DisplayName.
9. Specify the SmartObject property to use when you save values in the picker. You want to use this property to send an email to all employees you select in the picker. Select Email from the drop down list next to Identifier.
10. Specify the SmartObject property (text) to display at runtime. Click the ellipsis in the Display field.
11. Delete Name by clicking next to the text and then pressing backspace on your keyboard.
12. Drag and drop DisplayName from the Context Browser onto the Display Items canvas. Click OK and OK again on the Configure Data Source page.
13. Ensure the Allow Multiple option is selected to allow the control to save and load multiple values.
Next you edit the resolving rule to specify the parameter required for the URM service. You create another rule that executes when you click the Send Email button. The rule checks for all selected items in the Picker control and sends an email to all selected employees.
1. To specify the URM service parameter, on the Rules page select the When Picker is Resolving rule and click Edit Rule.
2. Click configure to configure the populate action of the picker.
3. The Get Users method requires a Label Name parameter to identify the Security Provider to use. Type a value or drag and drop a value from the Context Browser.
  You can get a list of the security providers in Management > Integration > Service Instances. Edit the URM Service and then click the Security Provider menu.
4. Click Finish and then OK to save the rule.
5. Click Add Rule.
6. Select the Events tab, click When a control on the View raises an event in the Control Events section, and then select Send EmailButton and Clicked.
7. Select the Conditions tab, click For each item in a list control on a View in the For-Each Looping section, and then select Selected and Picker.
8. Select the Actions tab, click Send an e-mail in the Notifications section, and then click configure.
9. Specify a value in the From field. You can type a value or drag and drop a value from the Context Browser. Drag and drop the Picker control's value in the To field as shown below. The value of the Picker control is the Email property of the Employees SmartObject that you configured as the Identifier earlier. When you use the picker at runtime, an email is sent to those employees you select. Specify a Subject and message for the email. You can use values from the Context Browser to personalize the email if necessary. Click OK.
10. You just configured a rule that sends an email to all selected employees when the Send EmailButton is clicked. Click OK to save the rule and then click Finish to save the view.
Test your view by running the Training Email view. Select employees using the Picker control and then click the Send Email button. Verify that all employees you selected received the email.
1. To test the view, select the Training Email view, then click Run.
2. Click the search icon of the picker as shown below.
3. The Search dialog opens. Search for the employees you want to send the email to and add them by clicking Add at the bottom. When you are done, click OK.
4. Click the Send Email button.
5. Verify that all employees you selected in the picker received emails.

Review

Use the Picker control to return values such as employees of an organization. You can select single or multiple items from the list and add rules containing For-Each Looping conditions if you want to execute an action on selected items. Rules allow interaction between controls such as sending an email when a button is clicked. See Picker control and Using the Picker control for more information about configuring the control and how to use it.