How to reference groups

Groups in Itential Platform can be uniquely identified by a database ID, or by a name and provenance pair where provenance is the name of the AAA adapter from which the group originated. This page covers best practices for group representation and how to query documents with referenced groups.

Guidelines

• If you have no custom applications, no action is required. Itential’s migration scripts handle the migration of internal platform data.
• If your custom applications are not RBAC-enabled, no action is required.
• If your custom applications are RBAC-enabled, plan for an application update to use the new group reference APIs and a data migration script to move from group names to group IDs.

Best practices

Group references in database documents

Reference groups via database ID. In MongoDB, groups are keyed with ObjectId, and references should use that type as well. This allows applications to use $lookup in the MongoDB aggregation pipeline to sort and filter by group fields, and enables more efficient querying when group data needs to be retrieved.

Displaying groups in the UI

Do not present users with a list of group IDs. Display group lists and references using the group name and provenance fields. Group name alone is no longer sufficient — users may need to distinguish between similarly named groups in different systems.

Group references in APIs

APIs should accept and return both group IDs and name/provenance pairs depending on context. Where group IDs are exposed, they should appear as strings in JSON. APIs must take on the burden of validating IDs, converting them to ObjectId where appropriate, and testing for equality using the appropriate methods.

Query documents with referenced groups

The examples below use the following group document:

1
{
2
  "_id": ObjectId("5aebd2ffe2c5b5614927362d"),
3
  "provenance": "Local AAA",
4
  "name": "group1",
5
  "description": "Sample Group",
6
  "memberOf": [...],
7
  "assignedRoles": [...]
8
}

Denormalizing group data — for example, storing a copy of the group name alongside the group ID — creates a maintenance problem when the group data changes but the copy does not. Instead, load group data at query time to include it in the API response.

Example workflow document

1
{
2
  "_id": "b6517ac9-a8fc-4621-902b-174458005c90",
3
  "name": "Example Workflow",
4
  "tasks": {},
5
  "transitions": {},
6
  "created": "5/18/2018, 9:32:50 AM",
7
  "created_by": {
8
    "id": ObjectId("5aebd2fae2c5b5614927362b")
9
  },
10
  "last_updated": "5/18/2018, 9:33:31 AM",
11
  "last_updated_by": {
12
    "id": ObjectId("5aebd2fae2c5b5614927362b")
13
  },
14
  "groups": [
15
    ObjectId("5aebd2ffe2c5b5614927362d")
16
  ]
17
}

Example API response with inline group data

This response includes the group’s human-readable fields alongside the group ID:

1
[
2
  {
3
    "id": "b6517ac9-a8fc-4621-902b-174458005c90",
4
    "name": "Example Workflow",
5
    "groups": [
6
      {
7
        "id": "5aebd2ffe2c5b5614927362d",
8
        "provenance": "Local AAA",
9
        "name": "group1",
10
        "description": "Sample Group"
11
      }
12
    ]
13
  }
14
]

Aggregation pipeline query

This query produces the desired data in a single request to MongoDB:

1
const workflowListWithInlineGroupsPipeline = [
2
  {
3
    $lookup: {
4
      from: 'groups',
5
      localField: 'groups',
6
      foreignField: '_id',
7
      as: 'groups'
8
    }
9
  },
10
  {
11
    $project: {
12
      name: 1,
13
      created: 1,
14
      groups: 1
15
    }
16
  }
17
];
18
19
const workflowList = await workflowsCollection.aggregate(workflowListWithInlineGroupsPipeline).toArray();