# Organization administration

## Organization administration at a glance

Organization administration is where you manage the organization’s members and audiences. An
audience is a group you use to target manuals and help content at specific reader groups. This topic sits in the
Administrative Guide’s Organizations area, alongside organization access management and
organization audit information.

| If you need to… | Go to |
| --- | --- |
| Invite a team member | [Invite a team member](#invite-a-team-member) |
| Create or maintain an audience | [Create and manage audiences](#create-and-manage-audiences) |
| Manage single sign-on or provisioning | [Manage organization access](doc:manage-organization-access) |
| Review organization activity | [Organization audit](doc:organization-audit) |
| Learn how to reach settings | [Navigation basics](doc:navigation-basics) |
| Personalize workspace presentation | [Personalizing your workspace](doc:personalizing-your-workspace) |
| Manage user accounts | [Manage users](doc:manage-users) |
| Review document access | [Document access reference](doc:document-access-reference) |
| Review security information | [Security and audit access](doc:security-and-audit-access) |

## Prerequisites for organization administration

Before you start, have the email address for the person you want to invite and decide which
Invite role option to assign. The invitation form starts with `CONTRIBUTOR` as its selected role.

> **Note:** The invitation form starts with `CONTRIBUTOR`. Choose another Invite role option before
> selecting **Send invite** when that is the role you need.

When you create an audience in **Settings audiences**, the initial color is `#3B82F6` and the
initial icon is `📄`. When you create one in **Audiences**, the initial color is `#3B82F6` and the
initial icon is `users`.

## Find the organization administration screens

Use this procedure to reach the organization and audience administration screens.

**Steps**

1. In the application navigation, select **Organization**.
2. From organization administration, open the audience settings surface when you need to create,
   edit, or delete audiences.
3. Open **Audiences** when you need to view built-in standard audiences and organization-specific
   custom audiences.

**Result:** The organization administration screen or the audience screen you selected is open.

## Understand the organization screens

The organization settings screen combines an invitation form with a member list. The invitation
form contains an email field and an Invite role choice. The member list can show each member’s
name, email, role, status, and joined date.

The audience screens use forms for audience details and lists for existing audiences. Use the
following fields when you create or edit an audience:

| Screen | Field | Type | Required |
| --- | --- | --- | --- |
 | Organization settings | **Invite email** | Email input | Yes |
 | Organization settings | **Invite role** | Select | No required marker |
| Settings audiences | **Name** | Text input | Yes |
| Settings audiences | **Slug** | Text input | Yes |
| Settings audiences | **Color** | Color and text inputs | No required marker |
| Settings audiences | **Icon (emoji)** | Text input | Yes |
| Settings audiences | **Description (optional)** | Textarea | No required marker |
| Audiences | **Name** | Text input | No required marker |
| Audiences | **Slug** | Text input | No required marker |
| Audiences | **Color** | Color and text inputs | No required marker |
| Audiences | **Icon** | Text input | No required marker |
| Audiences | **Description (optional)** | Textarea | No required marker |

## Invite a team member

Use the organization invitation form to add a person to the organization with a selected role.

**Prerequisites**

- Have the person’s email address.
- Decide whether the person needs `viewer`, `contributor`, `maintainer`, or `admin`.

**Steps**

1. Enter the person’s email address in **Invite email**.
2. Choose one option in **Invite role**: `viewer`, `contributor`, `maintainer`, or `admin`.
3. Select **Send invite**.

The invitation request can produce these messages:

| Message | What to do |
| --- | --- |
| `Only admins and maintainers can invite members.` | Ask an administrator or maintainer to send the invitation. |
| “Invite failed.” | Review the invitation details and try **Send invite** again. |
| `Request failed — please try again.` | Try **Send invite** again. |

**Result:** The invitation confirmation reads "Invitation sent to {email} — they'll get an email with a join link."

## Create and manage audiences

Use the audience controls to maintain reader groups for documentation targeting. **Settings
audiences** provides the create, edit, and delete controls; **Audiences** separates built-in
standard audiences from organization-specific custom audiences.

**Prerequisites**

- Decide the audience name, slug, color, icon, and description.
- For **Settings audiences**, use lowercase letters, numbers, and hyphens in **Slug**.

**Steps**

1. Choose the task you are doing:

   | If you want to… | First action |
   | --- | --- |
   | Create an audience | Select **New audience**. |
   | Edit an existing custom audience | Select its edit action. |
   | Delete an existing custom audience | Select **Delete** in **Settings audiences**. |
   | Cancel the audience form | Select **Cancel**. |

### Create an audience

1. Enter the audience name in **Name**.
2. Enter the audience identifier in **Slug**.
3. Set the audience color in **Color**.
4. Enter the audience symbol in **Icon (emoji)** or **Icon**, depending on the screen.
5. Enter supporting text in **Description (optional)** when needed.
6. Choose the completion action for the work you are doing:

   | If you are creating an audience in… | Select |
   | --- | --- |
   | **Settings audiences** | **Create audience** |
   | **Audiences** | **Create** |

**Result:** The new audience is submitted from the selected audience screen.

### Edit an audience

1. Enter the updated audience name in **Name**.
2. Enter the updated audience identifier in **Slug**.
3. Set the updated audience color in **Color**.
4. Enter the updated audience symbol in **Icon (emoji)** or **Icon**, depending on the screen.
5. Enter updated supporting text in **Description (optional)** when needed.
6. Choose the completion action for the work you are doing:

   | If you are editing an audience in… | Select |
   | --- | --- |
   | **Settings audiences** | **Save changes** |
   | **Audiences** | **Update** |

**Result:** The updated audience is submitted from the selected audience screen.

### Delete an audience

1. In the confirmation modal, read "Are you sure you want to delete the audience "{name}"? This action cannot be undone."
2. Select **Delete** to confirm.

**Result:** The deletion confirmation has been completed.

### Cancel the audience form

1. Select **Cancel** to close the audience form without submitting it.

**Result:** The audience form closes without submission.

The **Slug** in **Settings audiences** is converted to lowercase letters and hyphens as you
change **Name**. Standard audiences are built in and cannot be modified or deleted.

**Result:** The audience list shows the audience with its name, slug, color, and type. A custom
audience can be edited or deleted from its row.

## Handle audience and member variations

The organization screens change what you can do according to the data returned and the action’s
result.

| What you see | What it means | What to do |
| --- | --- | --- |
| A loading indicator in the member area | The member list is being retrieved | Wait for the member list or its error message. |
| A bad note in the member area | Member loading returned an error | Read the displayed error and correct the access or request problem. |
| No member rows | No organization members are returned | Use the invitation form to invite a team member. |
| A loading indicator on **Audiences** | The audience list is being retrieved | Wait for the audience list or its error message. |
| **Audiences failed to load.** | Audience loading returned an error | Read the displayed error and retry the page action. |
| Standard audiences | Built-in audiences are listed | Use them as listed; their edit and delete actions are not available. |
| **No custom audiences** | The organization has no custom audience rows | Select **New audience** to create one. |
| A create or edit modal | The audience form is open | Complete the fields and choose **Create audience**, **Create**, **Save changes**, or **Update**. |
| A delete confirmation modal | Deletion is awaiting confirmation | Read the confirmation and choose **Delete** or **Cancel**. |

The audience settings surface can also show these messages when its requests fail: "Failed to load audiences", "Operation failed", and "Delete failed".

**Result:** You know whether to wait, retry the page action, invite a team member, create an audience,
or continue to a dedicated administration screen.

## Continue with access or audit administration

Use this procedure to continue from organization settings to the dedicated administration screens.

**Steps**

1. From organization settings, select one of these controls:

   | If you need to… | Select |
   | --- | --- |
   | Continue to access configuration | **Single Sign-On** |
   | Continue to provisioning configuration | **Provisioning (SCIM)** |
   | Review organization audit information | **Audit Log** |

**Result:** The selected access, provisioning, or audit screen opens.