ApplicationTags ^v2.7.212

An application's access tags, and which users hold them.

const app = security.application("My Application");

const tag = app.tags.createElement("North Region", "Region", "Default");
tag.set("North", "write");

Constructor

Reached through the tags property of an ApplicationSecurity. It can't be created directly.

Overview

• Two kinds of tag: an ElementTag controls which elements of a dimension its users can read or write. A ScreenTag controls which screens they can see.
• Users: methods that take a user accept their id, email address or a User.

Methods

list list(includeAccessEntries) array

Returns a summary of every tag in the application.

Parameter	Type	Description
includeAccessEntries	boolean	Optional. true to include each tag's access entries.

get get(tagNameOrId) ElementTag | ScreenTag | null

Returns a tag, or null when there's no such tag. Call type() on it to tell which kind it is.

Parameter	Type	Description
tagNameOrId	string	The tag's name or id.

exists exists(tagNameOrId) boolean

Returns true when the tag exists in the application.

Parameter	Type	Description
tagNameOrId	string	The tag's name or id.

createElement createElement(name, dimensionId, hierarchyId) ElementTag | null

Creates an ElementTag for a dimension hierarchy, or returns null when the dimension or hierarchy can't be found. The tag starts with no access; grant it with set().

Parameter	Type	Description
name	string	The tag's name. It must be unique in the application.
dimensionId	string	The dimension's name or id.
hierarchyId	string	The hierarchy's name or id.

createScreen createScreen(name) ScreenTag

Creates a ScreenTag. Every screen starts hidden; show screens with set().

Parameter	Type	Description
name	string	The tag's name. It must be unique in the application.

remove remove(tagNameOrId) boolean

Deletes a tag. Returns true when it was deleted.

Parameter	Type	Description
tagNameOrId	string	The tag's name or id.

removeAll removeAll() boolean

Deletes every tag in the application.

userGetTags userGetTags(user) array

Returns every tag a user holds in the application.

Parameter	Type	Description
user	number | string | User	The user's id or email address, or the user.

userGetElementTags userGetElementTags(user) ElementTag[]

Returns the element tags a user holds in the application.

Parameter	Type	Description
user	number | string | User	The user's id or email address, or the user.

userGetScreenTags userGetScreenTags(user) ScreenTag[]

Returns the screen tags a user holds in the application.

Parameter	Type	Description
user	number | string | User	The user's id or email address, or the user.

userGetElements userGetElements(user, dimension, hierarchy) string[]

Returns the names of the elements a user's tags give them access to in a hierarchy.

Parameter	Type	Description
user	number | string | User	The user's id or email address, or the user.
dimension	string	The dimension's name or id.
hierarchy	string	The hierarchy's name or id.

userSetTags userSetTags(user, tags)

Replaces a user's tags in the application. Tags not in the list are removed, and unknown tags are skipped.

Parameter	Type	Description
user	number | string | User	The user's id or email address, or the user.
tags	array	Tag names or ids, or tags.

userRemoveAll userRemoveAll(user) boolean

Removes every tag a user holds in the application.

Parameter	Type	Description
user	number | string | User	The user's id or email address, or the user.

Examples

Create tags and give them to a user

const app = security.application("My Application");
const tags = app.tags;

const regionTag = tags.createElement("Region Access", "Account", "Default");
const screenTag = tags.createScreen("Planner Screens");

tags.userSetTags("user@example.com", [regionTag, screenTag]);

List a user's tags

const app = security.application("My Application");

for (const tag of app.tags.userGetTags("user@example.com")) {
    console.log(tag.name() + " (" + tag.type() + ")");
}

Related

• ElementTag and ScreenTag: the two kinds of tag.