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.

  1. From K2 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.
    PropertyData TypeKeySmartBoxRequiredUnique
    NameTextNoNoNoNo
    DescriptionTextNoNo

    No

    No

    EmailText

    No

    No

    No

    No

    ManagerText

    No

    No

    No

    No

    DisplayNameText

    No

    No

    No

    No

    FQNText

    No

    No

    No

    No

    UserNameText

    No

    No

    No

    No

    Sip AccountText

    No

    No

    No

    No

    Object SIDText

    No

    No

    No

    No

    1. Launch K2 Designer.
      If you do not know how to access K2 Designer, see Accessing K2 Sites.
    2. 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.
      Create Categories
    3. Right-click Employees and select New SmartObject.
    4. 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.
      Create SmartObject
    5. 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.
      Select URM.
    6. The Add Method wizard opens. On the Details screen ensure List is selected as the Type as shown below. Click Next.
      Add Properties
    7. 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.
      Add Properties
    8. Click Finish to save and exit the SmartObject.
      Add Properties
  2. Configure the Picker control

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

    1. 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.
        Create Item View
      2. In the General tab, name the view
        Training Email
        and keep the Item View type. Click Create.
        Create Item View
      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.
        Create Item View
      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
        Update Properties
      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.
        Data Source
      6. The Configure Data Source dialog opens. Click the ellipsis next to SmartObject.
        Configure Data Source
      7. Expand the folders where you saved the Employees SmartObject. Select the SmartObject and click OK.
        Configure Data Source
      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.
        Configure Data Source
      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.
        Configure Data Source
      10. Specify the SmartObject property (text) to display at runtime. Click the ellipsis in the Display field.
        Configure Data Source
      11. Delete Name by clicking next to the text and then pressing backspace on your keyboard.
        Configure Data Source
      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.
        Configure Data Source
      13. Ensure the Allow Multiple option is selected to allow the control to save and load multiple values.
        Configure Data Source
    2. 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.
        Configure Rule
      2. Click configure to configure the populate action of the picker.
        Configure Rule
      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.
        Configure Rule

        You can get a list of the security providers in K2 Management > Integration > Service Instances. Edit the URM Service and then click the Security Provider menu.
        Configure Rule

      4. Click Finish and then OK to save the rule.
      5. Click Add Rule.
        Configure 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.
        Configure Rule
      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.
        Configure Rule
      8. Select the Actions tab, click Send an e-mail in the Notifications section, and then click configure.
        Configure Rule
      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.
        Configure Rule
      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.
        Configure Rule
    3. 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.
        Test view
      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.
        Test view
      4. Click the Send Email button.
        Test view
      5. Verify that all employees you selected in the picker received emails.
        Test view
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.