---
url: /process-functions/security-application-tags.md
description: An application's access tags, and which users hold them.
---

#  ApplicationTags 

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

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

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

## Constructor

Reached through the [tags](/process-functions/security-application#properties) property of an [ApplicationSecurity](/process-functions/security-application). It can't be created directly.

## Overview

* **Two kinds of tag:** an [ElementTag](/process-functions/security-application-elementtag) controls which elements of a dimension its users can read or write. A [ScreenTag](/process-functions/security-application-screentag) controls which screens they can see.
* **Users:** methods that take a user accept their id, email address or a [User](/process-functions/userSecurity-user).

## Methods

### list `list(includeAccessEntries)`  {#list}

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)`  {#get}

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)`  {#exists}

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)`  {#createelement}

Creates an [ElementTag](/process-functions/security-application-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()](/process-functions/security-application-elementtag#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)`  {#createscreen}

Creates a [ScreenTag](/process-functions/security-application-screentag). Every screen starts hidden; show screens with [set()](/process-functions/security-application-screentag#set).

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

### remove `remove(tagNameOrId)`  {#remove}

Deletes a tag. Returns `true` when it was deleted.

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

### removeAll `removeAll()`  {#removeall}

Deletes every tag in the application.

### userGetTags `userGetTags(user)`  {#usergettags}

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)`  {#usergetelementtags}

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)`  {#usergetscreentags}

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)`  {#usergetelements}

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)` {#usersettags}

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)`  {#userremoveall}

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

```js
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

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

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

## Related

* [ElementTag](/process-functions/security-application-elementtag) and [ScreenTag](/process-functions/security-application-screentag): the two kinds of tag.