Skip to main content

Item Service Criteria

In addition to using an IRN to create a permission, the Item Service supports using additional criteria to target item service permissions.

Using Item Service Criteria in Permission Objects#

Resource Criteria#

Since the Item service manages different types of data (scripts, user configs, NamedUserCollections, and more), it provides an additional capability to allow you to better target your permissions.

As you may recall from the previous lessons, we can create an Item Service IRN that specifies either all NamedUserItems or a specific NamedUserItem like so:

itemsvc : nameduseritem : *itemsvc : nameduseritem : 8a972d06-e881-4452-b140-ab5644d743ec

With the Item Service managing such a wide variety of types NamedUserItems, simply creating a permission on a single item or all items can be limiting.

To accommodate permissions with a finer control, the Item Service supports an additional option on permissions by allowing you to define further criteria for the permission. Here is an example of creating a permission giving READ access to all NamedUserItem's that are Scripts:

{   "_actions": [IafPermission.PermConst.Action.Read],   "_namespace": ctx._namespaces[0],   "_resourceDesc": {      "_irn": IafPermission.NamedUserItemIrnAll,      "_criteria": {         "_itemClass": "Script"      }   },    "_user":{       "_id": apiUsersGroup._id,       "_type": IafPermission.PermConst.UserType.UserGroup   }}

Notice the additional criteria we are providing the permission specifying _itemClass: "Script".

We could also provide further criteria by specifying a _userType in the criteria as well.

{   "_actions": [IafPermission.PermConst.Action.Read],   "_namespace": ctx._namespaces[0],   "_resourceDesc": {      "_irn": IafPermission.NamedUserItemIrnAll,      "_criteria": {         "_itemClass": "Script",         "_userType": "client-script"      }   },    "_user":{       "_id": apiUsersGroup._id,       "_type": IafPermission.PermConst.UserType.UserGroup   }}

This permission would instead give only read permission to scripts with the "client-script" _userType.

You can provide criteria for any of the _itemClasses supported by the Item Service:

  • Script
  • UserConfig
  • NamedUserCollection
  • NamedFileCollection
  • NamedTelemetryCollection
  • NamedCompositeItem

Subresource Criteria#

The Item Service also provides the ability to permission individual or sets of RelatedItems in NamedUserCollections, NamedFileCollections, and NamedTelemetryCollections. This is done by providing a Subresource Criteria.

The Subresource Criteria allows you to specify criteria the individual RelatedItems must meet for the permission. For instance, only allow a user to see the RelatedItems in a collection of work orders that have a ticketType property value of 'mechanical'.

Here's an example of just such a permission using the Subresource Criteria.

{   "_actions": [IafPermission.PermConst.Action.Edit],   "_namespace": ctx._namespaces[0],   "_resourceDesc": {      "_irn": `itemsvc:nameduseritem:${workOrderCollection._id}`,      "_subresourceDesc": {         "_type": "relateditem",         "_criteria": {            "ticketType": "mechanical"         }      }   },    "_user":{       "_id": apiUsersGroup._id,       "_type": IafPermission.PermConst.UserType.UserGroup   }}

A few important things to note:

  • The IRN must reference a specific collection by its ID — not a wildcard. itemsvc:nameduseritem:* won't work here.
  • _type is always "relateditem" — this is the only subresource type the Item Service supports today.
  • _criteria is a query against the items' own properties — any property that exists on your RelatedItem objects can be used here, using the same query operators available throughout the Item Service (e.g. $eq, $in, $regex).
  • In addition to the EDIT action being assigned by the permission, the user automatically gets READ access to the collection itself — just enough to open the door, but the items they see are filtered to only those matching the criteria.