PingIDM

Manage relationships using the Platform admin UI or the legacy admin UI

This section describes how to set up relationships between managed objects using the Platform admin UI or the legacy admin UI. You can set up a relationship between any object types. The examples in this section demonstrate how to set up a relationship between users and devices, such as IoT devices.

For illustration purposes, these examples assume that you have started IDM and already have some managed users. If this is not the case, start the server with the sample configuration described in Synchronize data from a CSV file to IDM, and run a reconciliation to populate the managed user repository.

In the following procedures, you will:

Create a new Device object type

This procedure illustrates how to set up a new Device managed object type, and add properties to collect information such as model, manufacturer, and serial number for each device.

Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI.

Both UIs are available as separate downloads from the Backstage download site:

Using the Platform admin UI

  1. From the sidebar, click people Identities > Configure.

  2. Click Managed Object Type.

  3. In the New Managed Object Type modal, enter information in the following fields, and click Save:

    Field Value

    Object Type Key

    Device

    Display Label

    Device

    Description (optional)

    Devices

    Icon Code

    phone

    The Managed Object Type page for Device displays.

  4. Click the Properties tab.

  5. For each following property, click Add a Property, select String, enter the information, enable Required, and click Save:

    Property Key Display Label Required

    model

    Model

    Yes

    serialNumber

    Serial Number

    Yes

    manufacturer

    Manufacturer

    Yes

    description

    Description

    Yes

    category

    Category

    Yes

    After you finish, the properties list should look like this:

    device managed object
  6. To have a property display as a column when you list devices in people Identities > Manage, click the property, click the Display tab, and enable Show in Admin List View.

  7. From the sidebar, click people Identities > Manage.

  8. On the Manage Identities page, click phone Devices.

  9. For each of the following devices, click New Device, enter the applicable information, and click Save:

    • Device 1

    • Device 2

    • Device 3

    • Device 4

    Field Value

    Model

    Generic Phone

    Serial Number

    Phone-1

    Manufacturer

    PhoneCo

    Description

    Entry level phone

    Category

    Smart Phone

    Field Value

    Model

    Generic Watch

    Serial Number

    Watch-1

    Manufacturer

    WatchCo

    Description

    Entry level watch

    Category

    Smart Watch

    Field Value

    Model

    Special Phone

    Serial Number

    Phone-2

    Manufacturer

    PhoneCo

    Description

    Intermediate level phone

    Category

    Smart Phone

    Field Value

    Model

    Special Watch

    Serial Number

    Watch-2

    Manufacturer

    WatchCo

    Description

    Intermediate level watch

    Category

    Smart Watch

  10. From the sidebar, click people Identities > Manage, and select the Devices tab.

    The Devices page should list the devices you created:

    Devices page listing the four test devices
    The other procedures in this topic assume that you’ve added these devices.

Using the legacy admin UI

  1. From the navigation bar, click Configure > Managed Objects.

  2. On the Managed Objects page, click New Managed Object.

  3. On the New Managed Object page, enter information in the following fields, and click Save:

    Field Value

    Managed Object Name

    Device

    Readable Title

    Device

    Managed Object Icon

    fa-mobile-phone

    Material Design Icon

    phone

    Description

    Devices

    The Managed Objects > Device page displays.

  4. Click the Properties tab.

  5. For each following property, click Add a Property, enter the information, and click Save:

    Property Name Label Type Required

    model

    Model

    String

    ui-initial-mo

    serialNumber

    Serial Number

    String

    ui-initial-mo

    manufacturer

    Manufacturer

    String

    ui-initial-mo

    description

    Description

    String

    ui-initial-mo

    category

    Category

    String

    ui-initial-mo

    After you finish, the properties list should look like this:

    ui-initial-mo
  6. From the navigation bar, click Manage > Device.

  7. For each of the following devices, on the Device List page, click New Device, enter the applicable information, and click Save:

    • Device 1

    • Device 2

    • Device 3

    • Device 4

    Field Value

    Model

    Generic Phone

    Serial Number

    Phone-1

    Manufacturer

    PhoneCo

    Description

    Entry level phone

    Category

    Smart Phone

    Field Value

    Model

    Generic Watch

    Serial Number

    Watch-1

    Manufacturer

    WatchCo

    Description

    Entry level watch

    Category

    Smart Watch

    Field Value

    Model

    Special Phone

    Serial Number

    Phone-2

    Manufacturer

    PhoneCo

    Description

    Intermediate level phone

    Category

    Smart Phone

    Field Value

    Model

    Special Watch

    Serial Number

    Watch-2

    Manufacturer

    WatchCo

    Description

    Intermediate level watch

    Category

    Smart Watch

  8. From the navigation bar, click Manage > Device.

    The Device List page should look similar to the following:

    ui-mo-iot
    The other procedures in this topic assume that you’ve added these devices.

Configure the relationship between a device and a user

To set up a relationship between the Device object type and the User object type, you must identify the specific property on each object that will form the basis of the relationship. For example, a device must have an owner and a user can own one or more devices. The property type for each of these must be relationship.

In this procedure, you will update the managed Device object type to add a new Relationship type property named owner. You will then link that property to a new property on the managed User object, named device. At the end of the procedure, the updated object types will look as follows:

A diagram showing the updated Managed User and Managed Device objects. The Managed User’s device property is linked to the Managed Device’s owner property.
Figure 1. Relationship Properties on User and Device Objects

Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI.

Both UIs are available as separate downloads from the Backstage download site:

Using the Platform admin UI

Unlike the legacy admin UI, the Platform admin UI configures both sides of a relationship, and their cardinality, in a single guided flow, on either object type’s Relationships tab.

  1. From the sidebar, click people Identities > Configure, and select the Device object type.

  2. Click the Relationships tab, then click Relationship.

  3. From the Object Type list, select User.

  4. Set the cardinality on each side of the relationship: leave the Device side set to Has one (a device has one owner), and set the User side to Has many (a user can own more than one device).

  5. Click Next.

  6. On the Relationship Property step, configure each side of the relationship:

    Side Configuration

    Device

    Enter owner in Property Name. From Display Properties, select the User properties to display when viewing a device’s owner, such as userName, mail, and telephoneNumber.

    User

    Enter device in Property Name. From Display Properties, select the Device properties to display when viewing a user’s devices, such as model and serialNumber.

    Set Display Properties on both sides. If you leave it unset, the relationship picker for that side can’t display a label for each related object.

  7. Click Next to skip the optional Derived Properties step.

  8. On the Relationship Settings step, leave Validate Relationship enabled.

    This setting ensures the relationship is valid when a device is assigned to a user. IDM verifies the user and device objects exist, and that the device hasn’t already been assigned to another user.

  9. Click Save.

    The new relationship displays on the Relationships tab of both the Device and User object types.

Unlike built-in relationships such as Manager, a custom relationship you configure this way doesn’t automatically get a dedicated tab on either object’s detail page in people Identities > Manage. The device property on User doesn’t appear as its own tab. To assign a device to a user, use the device’s own owner property instead, as described in Demonstrate the Relationship.

Using the legacy admin UI

  1. Create a new relationship property on the Device object:

    • From the navigation bar, click Configure > Managed Objects, and select the Device object.

    • On the Managed Objects > Device page, click the Properties tab.

  2. Click Add a Property, enter the information, and click Save

    Property Name Label Type Required

    owner

    Owner

    Relationship

    ui-initial-mo

    You cannot change the property Type after creation. If you create a property with an incorrect Type, you must delete the property and recreate it.
  3. Click the owner property row.

    The Details tab displays the current Relationship Configuration:

    ui-device-relation

  4. Click the + Related Resource area.

  5. In the Add Resource window, select user from the Resource list.

    This sets up a relationship between the Device object and the managed user object.

  6. From the Display Properties list, select the user object properties to display when viewing a user’s devices in the UI. For example, you may want to access a user’s userName, mail, and telephoneNumber.

  7. Click Show advanced options. Notice that the Query Filter field is set to true. This setting lets you search on any selected Display Properties when assigning a device to a user.

  8. Click Save.

    Add Resource Window

    The Managed > Device > owner page now displays the one-way relationship between a device and a user.

    Owner to Device one-way relationship

  9. Click Save.

  10. To configure the reverse relationship, click + Two-way Relationship:

    1. In the Reverse Relationship pop-up, select Has Many. This indicates a single user can have more than one device.

      The Configure Reverse Relationship window displays.

      Configure Reverse Relationship Window

    2. In the Reverse property name field, enter the new property name that will be created in the managed user object type, device for this example.

    3. From the Display Properties list, select the properties of the device object to display when viewing a user in the UI. For example, you might want to access the model and serialNumber of each device.

    4. Click Show advanced options. Notice that the Query Filter field is set to true. This setting allows you to search on any of the selected Display Properties when assigning a device to a user.

    5. Enable Validate relationship.

      This setting ensures the relationship is valid when a device is assigned to a user. IDM verifies the user and device objects exist, and that the device hasn’t already been assigned to another user.

    6. Click Save.

      The Managed > Device > owner page now displays the two-way relationship showing that a user objects can have many devices.

      Devices to owner two-way relationship

    7. Click Save.

  11. From the navigation bar, click Configure > Managed Objects.

  12. On the Managed Objects page, click User.

  13. On the Managed Objects > user page, click the Properties tab.

    Notice the device property was created automatically when you configured the relationship.

Demonstrate the relationship

This procedure demonstrates how devices can be assigned to users, based on the relationship configuration that you set up in the previous procedures.

Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI.

Both UIs are available as separate downloads from the Backstage download site:

Using the Platform admin UI

The device property you created on User doesn’t have its own tab in people Identities > Manage (refer to the note in Configure the Relationship Between a Device and a User). Assign the relationship from the Device side instead, using its owner property:

  1. From the sidebar, click people Identities > Manage, and select the Devices tab.

  2. Select a device.

  3. On the device’s Details tab, select the Owner field, and search for the user to assign as owner.

  4. Click Save.

  5. Repeat for a second device, assigning it to the same user.

    If you select a device that’s already assigned to a different user, and Validate Relationship is enabled for the owner relationship, the UI displays a validation error when you try to save.

Using the legacy admin UI

  1. From the navigation bar, click Manage > User.

  2. On the User List page, click a user entry.

  3. On the User > userName page, click the Device tab, and then click Add Device.

  4. In the Add Device window, click the Device field to display the list of devices that you added in the previous procedure.

    ui-user-add-device

  5. Select two devices, and click Add.

    The Device tab displays the added devices.

    Device tab with two added devices

  6. Click the Show Chart button.

    A graphical representation of the relationship between the user and her devices is displayed:

    ui-device-chart

  7. You can also assign an owner to a device.

    From the navigation bar, click Manage > Device, and click a device that you did not assign in the previous step.

  8. On the Device > model page, click Add Owner.

  9. In the Add Owner window, select a user, and click Add.

  10. Click Save.

To demonstrate the relationship validation, try to assign a device that has already been assigned to a different user.

The UI displays the error message Conflict with Existing Relationship.

View the relationship configuration in the UI

Widgets are deprecated and will be removed in a future release of IDM. For more information, refer to Deprecation.

The Managed Objects Relationship Diagram provides a visual display of the relationship configuration between managed objects. Unlike the Identity Relationships widget, described in View relationships in graph form, this widget does not show the actual relationship data, but rather shows the configured relationship types.

This widget is not displayed on any dashboard by default. You can add it as follows:

  1. Sign on to the legacy admin UI.

  2. From the navigation bar, click Dashboards, and select a dashboard. Alternatively, create a dashboard.

  3. On the applicable dashboard page, click Add Widget.

  4. In the Add Widget window, click the list, scroll down to the Utilities item, and select Managed Objects Relationship Diagram.

    There are no configurable settings for this widget.
  5. The Preview button shows the current relationship configuration. The following image shows the relationship configuration for a basic IDM installation with no specific configuration:

    managed-objects-relationships

    The legend indicates which relationships are required, optional, one-to-one, and one-to-many.