Create Azure Active Directory User Reference

This content applies to legacy design tools (such as K2 Studio, K2 for Visual Studio, or the Silverlight-based K2 workflow design tool). If you have upgraded from K2 blackpearl 4.7 to K2 Five, these tools may still be available in your environment. These legacy tools may not be available in new installations of K2 Five. These legacy tools may also not be available, supported, or behave as described, in future updates or versions of K2. Please see the legacy component support policy for more information about support for these components.

This wizard is found in the Azure Active Directory node in K2 Studio and the K2 Designer for Visual Studio.

What does it do?

The Get AAD User Reference wizard queries the Azure Active Directory for user information based on the filters you choose and creates a reusable reference to them. This reference can be used in any subsequent workflow steps where you would want to refer to each of the users you chose in the wizard.

Use Case Examples

  • Create a reference to username@xyz.com and use it as input in multiple other wizards that require a username.
  • Display a user’s details in the body of an email using reference data fields (Display Name, Job Title, Telephone Number, etc).

Permissions

The user designing the workflow must have AAD Read permission.

Additional Considerations

  • The wizard’s input fields do not support “begins with” or “contains” e.g. to create a reference to a user with the display name “First Last”, you must type in the full name.
  • Input fields are not case sensitive.
  • Multiple properties may be used to narrow down which users the wizard should create a reference to.

How is it used?

To utilize reference data in a text field (e.g. in an email), navigate to the Context Browser, expand the Item References category, expand the Reference you created with a Get Reference wizard, and drag an item to the text field. This data gets populated dynamically after you deploy the workflow and start up a new instance.

If you want to use a Group reference to more than one person, you will need to keep in mind the fact that multiple objects in a reference are stored as an array. In order to insert spaces, commas or semicolons, between each object, you will need to use the inline Join function. To do this, navigate to the Context Browser, expand the Inline Functions category, expand the Text category, and drag the Join function to the text area where you want to use the reference. In the Join menu, drag the reference data object to the Values textbox and specify a Separator.

If you want to use a user reference in another AAD wizard that requires a UPN (Get Manager Reference, Get Direct Reports Reference), make sure the reference you create in this wizard only refers to a single user. Using a reference to multiple users gets a reference to the manager/reports of only the last user in the list.

Choose criteria to define which users this reference will include and click OK to create the reference in the Item Reference node of the Context Browser.

Field Description Sample Value
Directory Select the Azure Active Directory in the drop-down box containing the user/s you want to create the reference too. Specify the Azure Active Directory from the drop-down list.
Account Enabled Specify whether the user's account is enabled or not.

Select Yes or No

OR

Click the toggle button. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
City The user's city information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Country The user's country of residence. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Department The user's department information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Given Name The user's given name information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Display Name The user's display name information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Job Title The user's job title information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Mail The user's email information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Object Id The user's object id information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
State The user's state of residence. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Surname The user's surname information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Usage Location The user's usage location information Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
User Principle Name The user's user principle name information. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.
Reference Name Specify the Reference Name the wizard will create for the user/s. This value must be unique for this workflow. Type a value, or drag a value from the Context Browser such as a pre-configured Data Field, Item Reference or a SmartObject Load method. Note that when a SmartObject Load method is used, an input property is required for the correct data to load.

In the following example, two User References are created and referred to in an email. The first reference does not contain any filters and so returns all users from AAD. The second reference contains filter information and so returns only the relevant information from AAD.

  1. Reference 1: No filters are used.

  2. Reference 2: AAD User information is filtered by Mail and Surname fields where the data is as entered.

  3. The Send Email wizard step is built by dragging fields from the created Reference 1 (UserNoInputs) and dropped next to the NoInputs label, and from Reference 2 (UserInputData) and dropped next to the InputData label.

  4. The resulting email shows all the email addresses for all the users in AAD followed by all the surnames of all the users in AAD next to the NoInputs label. As well as the specific user filtered out of the AAD users by the second created reference next to the InputData label.

    Note that the data is poorly formatted with no spaces between objects, refer to the section How is it used above for information on how to better format the data. Below is a image of the data correctly formatted.