Permission manifest

A permission manifest specifies a set of node permissions and optionally a list of user groups that should have those permissions. A permission manifest is specified in JSON as one or more members in the field Permission manifest.

The permission manifest has the form:

[
{
"node": node,
"permission": permission,
"user": user
}, ...
]

node identifies the node or nodes on which permissions should be granted. It is a single node version reference or a list of node version references. Permissions are only granted on nodes, not node versions, but for consistency node version references can be passed. A node value of true specifies the node that holds the manifest.

permission identifies the types of permissions that should be granted, as either a single item or an array of items. Each item should either be the references (such as "node-read"), or the system nodes that represent the permissions (e.g. Node read), or another node that contains the permission type reference in the Permission type reference field. 

user is optional and specifies the users or user groups to whom the permissions should be granted. It can be a single item or an array of items. Each item can be:

  • A user logon reference.
  • A user group reference.
  • A node version reference for a node that contains a User Logon Reference field for an individual permission.
  • A node version reference for a node that contains a User group reference field for a group permission.

Specifying a user in the permission object grants the user only the permissions within the permission object. Granting node-us-manifest to user gives them all the permissions within the manifest.

The permission object repeats within an array. The Permission manifest field can have more than one member. The arrays of all the members are merged into a single list of permission objects. Having multiple members allows permission manifests to be inherited more easily.

Use the Permission Manifest node type to create a standalone permission manifest. This allows the node, permission and user of the permission manifest to be specified using bindings, or by node/field combinations, as described by the following examples.

somecompany.node.reference The somecompany.node.reference node.
${someNode} The node bound to reference someNode.
${someNode}:system.NODE_LIST All the nodes listed by the system.NODE_LIST field of the node bound to the reference someNode.
${someNode}:* The package contents of the node bound to the reference someNode.

Although it can be, the Permission manifest field is not designed for manual editing. Solutions should use either a combination of permission manifest items and permission manifest specification (see Permission manifest items and specification) or use derivation to create permission manifests from the application data.

Users

The users who should be granted the permissions are specified either in the user property or through the granting of node-use-manifest on the node that contains the permission manifest, which adds the users to each permission object in the manifest. This can be done on a separate node. For example, the following have the same effect.

Method 1 - users defined in the same manifest

[
{
"node":"company.node1",
"permission":"node-administer",
"user":["user1","user2"]
},
{
"node":"company.node2",
"permission":"node-update-all-members",
"user":["user1","user2"]
}
]

Method 2 - users defined in a different manifest

company.manifest.nodea contains the permissions.

{
{
"node":"company.node1",
"permission":"node-administer"
},
{
"node":"company.node2",
"permission":"node-update-all-members"
}
}

A separate node grants permission to use the manifest.

[
{
"node":"company.manifest.nodea",
"permission":"node-use-manifest",
"user":["user1","user2"]
}
}

Both methods are valid. The former method is useful for instance-type permissions within a solution, and it allows different permissions to be set for different user groups. The latter is useful for library-type permissions that need to be reused, for example product library manifests.

User group permissions

Permissions on user groups (such as administer-usergroup) are defined in exactly the same way. The nodes must identify the user groups on which permissions are to be granted using the User group reference field.

Manifest Items

Manifest Items (not to be confused with permission manifest items) provides an alternative method of specifying permission manifests for nodes. Manifest Items contains multiple members, the target of each represents a node on which permissions are to be granted and the value of which contains a whitespace-delimited list of permission type references.

Manifest Items can be translated to the equivalent Permission manifest. For example, consider the following Manifest Items members.

TargetValue
company.nodeA node-read-all-members node-use-draft
company.nodeB node-read-all-members node-use-draft
company.nodeC node-administer

Its equivalent Permission manifest would be:

[
{
"node":["company.nodeA","company.nodeB"],
"permission":["node-read-all-members","node-use-draft"]
},
{
"node":"company.nodeC",
"permission":"node-administer"
}
]

Unlike Permission manifest, Manifest Items cannot be used for setting usergroup or global permissions.

Actioning manifests

The script node method refreshManifestPermissions() applies manifest permissions in both Manifest Items and Permission manifest, and can be invoked in a derivation script.

The node-use-manifest permissions in the manifest are applied first, as users with node-use-manifest permissions then get all the permissions specified in the manifest.

Permissions are granted using the authority of the manifest node owner. Any permissions that they are not authorised to grant (either because they cannot grant to the user or cannot grant on the resource) are silently ignored, as are any errors with interpreting the node, permission or user specifications.