# Cache Warming
Source: https://docs.curator.interworks.com/best_practices/performance/cache_warming

Improve initial page load times by pre-warming caches for better user experience

Sometimes the initial page load or log in flow for your users can be very slow. This is because we must perform API
calls to check if the user has permission to see each navigation item related to analytic content. Single API calls are
fast but when your menu is large and many calls must be made it can really anchor the load time.

This feature allows you to choose a select group of Curator users to warm the cache for. This improves the initial page
load and skips the long wait caused by permission checks. The affect is even greater if your menu is very large.

## Global Cache Warming (Default Behavior)

By default, Curator warms the cache for every user when they log in via the `/curator/loading` route. This runs the same
permission checks and menu-building logic upfront so that subsequent page loads are fast for the entire user base, not
just the smaller Frontend Group described in the next section.

This default behavior works well for most portals, but on installations with a very large user base or a very large
analytic content menu it can drive significant memory usage as each login warms a full cache slice. In rare cases this
can lead to PHP memory exhaustion or HTTP 503 errors during peak login periods.

To disable global cache warming without affecting the targeted Frontend Group warming described below:

1. Navigate to **Curator Backend > Settings > Curator > Portal Settings > Features**.
2. Enable the “Disable All Cache Warming” toggle.
3. Click **Save**.

<Note>
  Disabling global cache warming will make the first page load after login slower for users, since permission checks and
  menu building will happen on demand instead of upfront. On-Prem: if you are hitting memory limits, also review the
  `memory_limit` setting in your `php.ini` against the
  [Server Requirements](/get_started/self_hosted_overview#server-requirements) before disabling global cache warming.
</Note>

## Setting Up the Group

First, we need to make sure you have a Frontend Group that contains the users needing their cache warmed. This Frontend
Group needs to have less than 200 users because this process is intensive. Increasing the number of users could clog the
queue and hurt performance. We're still playing with the sweet spot for number of users so this may change in the future.

1. Navigate to your Curator backend > Settings > Users > Frontend Groups. If you already have a group with less than
   200 members that contains the users you’d like to receive the speed bump, you’re good to go and can skip to “Setting
   Up the Feature”! Otherwise, hit the “New Frontend Group” button:
2. Give your group a name:
3. Either manually select users in the “Group Members” section or choose a group from one of your analytic platforms in
   the sections below:
4. Hit “Save!”

## Enabling Cache Warming for your Group

1. Navigate to your Curator backend > Settings > Curator > Portal Settings > Features tab:
2. Enable the “Cache Warming” feature at the top of the Functionality section:
3. Choose the Frontend Group we created earlier.
4. Hit “Save!”

## Changing the Cache Driver

Curator's cache driver is set by the `CACHE_DRIVER` environment variable in the `.env` file at the Curator
webroot (on Linux this is `/var/www/html/.env`). When `CACHE_DRIVER` is not set, Curator defaults to the
`file` driver.

Supported drivers:

| Driver      | `CACHE_DRIVER` value | Notes                                                                               |
| ----------- | -------------------- | ----------------------------------------------------------------------------------- |
| File system | `file`               | Default; no extra services required                                                 |
| Memcached   | `memcached`          | Requires memcached (Recommended on Linux installations)                             |
| Database    | `database`           | Uses the `cache` table in Curator's database (Not usually recommended due to speed) |

To switch away from memcached (or any other driver) to file-based caching:

1. Open the `.env` file in the Curator webroot.
2. Add or update the `CACHE_DRIVER` line:
   ```
   CACHE_DRIVER=file
   ```
3. Clear the existing cache by clicking the **Clear Cache** button in the Curator backend (or run
   `php artisan cache:clear` from the webroot).
4. Restart your web server so the new environment value is picked up.

<Note>
  Switching drivers does not migrate previously cached data. Cached items are rebuilt on the next user request
  or cache warming cycle.
</Note>


# Menu Tuning
Source: https://docs.curator.interworks.com/best_practices/performance/menu_tuning

Optimize menu system performance with tips and configuration recommendations

## Menu Overview

While Curator’s menu system is about as streamlined as possible, there are some tips and tricks you can use to tune its
performance if fancy yourself as a Vin Diesel type. Most of the delays Curator clients see when rendering their
navigation relates to the permission checking that ensures each user only sees the links they have access to view. One
of the big selling points with Curator is that it inherits permissions from the connected platforms by default, so this
is a necessary step. The good news is that Curator does cache all of those permission checks, so it’s really only an
issue when users first log in to Curator for the day. However, that’s also the first impression users get to your
Curator portal, so it’s understandable that this should be as fast as possible. With a little thought, this is where
performance gains can be realized.

## The Obvious Stuff

The first thing to check is always that Curator and any platforms it is connected to are running at full speed. If your
Tableau Server is underpowered or is being bombarded by users, that will slow down the permission checks Curator needs
to make. Same goes if the network connection between Curator and the other platforms is handled by letter-carrying
snails instead of bullet train-esque transfers. Lastly, the most common cause of general performance issues with Curator
itself is file system speed. If the storage mounted to your Curator server runs through the laziest of digital
stonemasons hand chiseling each bit on the drive platters, it’s going to slow down things like Curator’s caching system
and generally make life unbearable. Many times, the file system itself is fast but malware detection running on the
server prevents it from running at full speed.

## Short-Circuiting

Let’s say your main navigation is organized by high level categories. If most of your users only have access to one or
two of those categories, then it doesn’t make sense to check permissions on each link under the others. By using
Curator’s restrict access functionality, you can set which groups have access to each category and this will essentially
short circuit the permission checking for any top-level categories where the user is restricted.

For instance, if you have a category for human resources and you set its restrict access to only allow users in the HR
group, any user who isn’t in the HR group will skip checking the links under the human resources category. Any
permission checks that get skipped means the navigation will render that much faster.

## Utilizing Landing Pages

If you’ve got hundreds or thousands of links in your navigation and can’t use the short-circuiting approach above, then
you could try creating landing pages for sections of the navigation to reduce the number of links it needs to check
permissions against.

Using the same human resources example, you could create a human resources page that has links to the various human
resources content using the built-in tiles or lists. When you add this page to the navigation, Curator only has to check
whether the user is allowed to see that page, which should be quick. Only when a user clicks to open that human
resources page will Curator check permissions for each of those links on the page. If you repeat this for several
sections of the navigation, it really cuts down on the number of permission checks the menu system needs to make before
showing the home page.
Combining Tableau Workbooks

The way Curator checks permissions for Tableau is by getting the list of workbooks a user has access to on a per site
basis and then checking which dashboards are in each of those workbooks. This means that if you have a million
dashboards and they are all in their own workbook, Curator is going to have to make a million API (application
programming interface – or a fancy way to say that Curator is talking to Tableau) calls to Tableau just to determine
whether a link should be shown in the navigation. On the other hand, if you combined those into a single workbook with a
million dashboards, Curator would only have to make one API request to Tableau to check. While your network connection
and Tableau Server might be supercharged, there will always be overhead delays when increasing the number of API calls
over the web. By minimizing the number of API calls, you’ll see better performance.

## Combining Tableau Sites

Tableau sites are wonderful for making sure your various audiences are segregated from each other, since each site is
independent from the others. However, this also means that if you have content published from multiple sites, Curator
has to make separate API calls to check permissions for each one. Like combining your dashboards into fewer workbooks,
combining your workbooks into fewer sites will also see those gains.
Connecting to Tableau Server’s Repository

As mentioned earlier, making API calls between Curator and Tableau incurs some overhead which slows down the process. An
alternative to that is allowing Curator to connect directly to Tableau Server’s underlying database (AKA repository).
This avoids a lot of that overhead. Additionally, Curator is able to create custom queries to pull exactly the
information it needs in a single request. This includes checking all workbooks at the same time as well as only
requiring Curator to authenticate once instead of once per Tableau site. Needless to say, whenever Curator can use the
repository connection instead of the API, it’s able to shave precious seconds off of its quarter mile time.

Unfortunately, connecting to the repository is only possible for Tableau Server; so if you’re using Tableau Cloud, this
won’t be an option for you.

## Warming the Cache (Advanced)

As you’ve probably seen in a lot of motor sports, racers often spin their tires to warm them up before a race. This
increases traction and allows them to go faster around the track. Since Curator uses cache for permission checks, one
way you can make it go faster around the track is to warm its cache at the beginning of each day. In a nutshell, this is
scheduling something each morning to call Curator’s API to generate the navigation for each user before they try to log
in for the first time. When a user does log in for the first time, all of the permission checks will have already been
cached, so Curator can build the navigation fast and furious.

Curator’s API end point can be found at /api/v1/Content/generateNavMenus. You’ll need to pass it a valid API key, the ID
of the menu to generate, and the username to generate it for. Documentation on how to call this API endpoint can be
found by navigating to Backend >Settings >Curator >API Keys, click on one of the keys, and change the drop-downs at the
bottom to “Content” and “generateNavMenus,” respectively.

If you don’t have a good way to schedule API calls, you can take advantage of Curator’s automation scripts. This feature
is disabled by default, so to enable it navigate to Backend >Settings >Curator >Portal Settings >Features tab >
Functionality Section >Integration Automation switch and save. Once enabled, refresh the page and you should see a new
section under Backend >Integrations >Automation to create scripts or commands. This is an advanced topic, so we’ll leave
the rest up to you to implement, but if you want to create a script to call the API you’ll use Manage Scripts. If you
want to issue commands on Curator’s server to call the API, you’ll use Manage Commands. Both can be configured for
whatever schedule makes sense in your environment.


# Password Settings
Source: https://docs.curator.interworks.com/best_practices/security/password_settings

Configure password complexity requirements and security policies for enhanced site security

It’s always a good idea to keep your site as secure as possible. Beyond settings like https, multi-factor authentication
and firewalls, you can now set better password policies. Password complexity options allow you to set stricter rules for
passwords to prevent users from creating weak passwords. Password expiration allows you to require users to change their
passwords on a frequent basis. Let’s take a deeper look into these two settings.

## Password Complexity Options

Password complexity allows you to set rules to require stronger passwords. To enable and configure password complexity
options, go to Backend > Settings > Curator > Portal Settings. Under the general tab, you will find a section called
Security. Expand that, and you can now find the Password Complexity Options toggle. Please note that in order to view
and configure this setting, you must have Password Change or Password Reset settings (or both) enabled, which require
you to use Tableau or Curator as your authentication:

Once you toggle on Password Complexity Options, you will see three different options you can set to require stronger passwords:

It’s a good idea to set a long length requirement, the longer the better, but don’t go too overboard or your users may
want to write their passwords down on a Post-it note attached to their display. The first time you enable this setting,
it will default to 10.

Once enabled, you will now see these requirements on pages that allow you to set a password:

## Password Expiration

Password expiration can be found on the same Portal Settings page and tab, right next to the Password Complexity
Options. Like the prior option we looked at, you must have Password Change or Password Reset enabled to be able to view
password expiration. Click the toggle to enable it, and you will now see you can set the number of days until user
passwords will expire:

If enabled, the login page will check to see if the user’s password is expired and, if so, redirect them to a page to
set a new password. Once this is done, they will be able to log in with the new password.

Setting a prudent expiration date, such as 90 days, and turning on password complexity options are easy, effective ways
to make your Curator portal even more secure.


# API Relays
Source: https://docs.curator.interworks.com/creating_integrations/api_relay

Forward requests to external APIs through Curator, keeping credentials secure and centralizing access control.

## Overview

An API relay is a server-side proxy that sits between your users and an external API, letting Curator call
third-party services without exposing credentials to the browser. You configure the relay once; Curator then
attaches your stored credentials, validates incoming calls, and forwards the assembled request to the external
service on the caller's behalf.

The result: sensitive credentials never leave your server, your external API surface is limited to exactly what
you expose, and you get a single, auditable integration point you can monitor, update, or disable without
touching the calling code.

## When to use an API relay

API relays bridge Curator with any third-party API. Common scenarios:

* **Custom BI embeds from non-integrated platforms** — a custom JavaScript embed that fetches live data from an
  external REST API, with the API key stored as a Curator constant instead of in the browser.
* **Submitting form data to a webhook** — Data Manager routes mark-commenting submissions to any HTTP endpoint,
  using an API relay as the connection point. See [Sending Data to Webhooks](/embedding_using_analytics/data_manager/sending_data_to_webhooks).
* **AI chat integration** — let users talk to an AI assistant without exposing your paid AI account credentials.

## Prerequisites

API relays require the **Integration Automation** feature to be enabled:

1. Log in to the Curator backend.
2. Navigate to **Settings** > **Portal Settings** > **Features**.
3. Enable **Integration Automation** under the Functionality section.
4. Save and refresh the page.

After enabling, the **Integrations** > **Automation** > **API Relay** section will appear in the left-hand menu.

## Creating an API relay

1. Navigate to **Integrations** > **Automation** > **API Relay**.
2. Click **New** at the top of the list.
3. Fill in the form (see the field reference below) and click **Save**.
4. Once saved, the **Link** shown at the top of the edit form is the URL you will call to trigger
   the relay. Copy it and use it in your integration.

> **Security note:** The Portal Link is publicly accessible by default — any caller who knows the URL can trigger
> the relay, and it is not tied to a logged-in user. If the relay exposes a sensitive upstream API, restrict
> access (see [Securing a relay](#securing-a-relay) below).

## Field reference

### Basic settings

| Field                | Description                                                                                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**             | A descriptive label for the relay. Used only in the backend list — not exposed to callers.                                                                                                                |
| **Description**      | Optional free-text notes. Useful for documenting what the relay does and who relies on it.                                                                                                                |
| **Log Relay Usage?** | When enabled, Curator writes a log entry every time the relay is triggered. Includes the incoming input, outgoing request details, and the response. Useful for debugging but may be noisy in production. |

***

### Outgoing Request URL

This section controls where Curator sends the relayed request.

| Field                    | Description                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **URL**                  | The full external API endpoint URL. Do not include a query string here, variables and constants are appended automatically.                                                                                                                                                                                                                                        |
| **Allow Dynamic URL**    | When enabled, a caller can supply a different target URL at call time via the variable name set in **Dynamic URL Variable**. If the caller omits the variable, the static URL above is used.                                                                                                                                                                       |
| **Dynamic URL Variable** | The query parameter name the caller should use to pass an override URL. Only shown when **Allow Dynamic URL** is enabled.                                                                                                                                                                                                                                          |
| **Used In Webhook?**     | Changes how the outgoing request body is constructed. When enabled, Curator forwards the entire incoming request body to the upstream URL rather than only the configured variables and constants. Enable this when the relay will be selected in a Data Manager Data Group's **Send to Webhook** setting, where the full submitted payload needs to be forwarded. |

***

### Outgoing Request Content

This section defines what Curator sends to the external API: the headers, fixed values, caller-supplied values,
and body content.

#### Headers

HTTP headers to attach to every outgoing request (e.g. `Content-Type: application/json`, `Accept: application/json`).
Each header entry has a **Key**, a **Value**, and an **Allow Dynamic Values** toggle. When dynamic values are enabled,
a caller can override that header's value by sending an HTTP header of the same name in their request to the relay.

#### Constants

Fixed key-value pairs that are always sent with the outgoing request regardless of what the caller provides.
This is the right place for credentials, API keys, tokens, or any other value that must remain server-side and
must never be visible to the caller. Constants cannot be overridden by incoming requests.

Each constant also has an **Encrypt Value** toggle. Turn it on for sensitive values such as API keys or client
secrets: the value is then stored encrypted in the database and shown as `***redacted***` in relay logs instead
of in plain text. The outgoing request still receives the real value.

Encryption is one-way. Once saved, the form only ever shows the encrypted form of the value, and Curator never
decrypts it back for display. Turning **Encrypt Value** off while the encrypted value is still in the field is
rejected when the relay is saved. To store a constant unencrypted again, clear the field and enter a new value.

#### Variables

Named parameters that the caller is expected to supply at call time (e.g. `start_date`, `region`, `user_id`).
Each variable has a **Key** (the parameter name) and an **Is Required?** toggle. Required variables will cause
the relay to reject the call if they are missing. Variables are passed by the caller as query string parameters
or POST body fields using the same key name defined here.

#### Body Content

Static body content to include in the outgoing request (e.g. a fixed JSON or XML payload). Leave blank if the
request body is built entirely from variables and constants. Body content applies to POST relays only — a GET
relay sends its parameters on the URL and ignores the body.

To let an incoming request set or edit the body at call time — whole-body replacement, placeholder substitution,
or transforming the value before it is injected — enable **Allow Dynamic Body Content**. This is covered in full
in [Dynamic Body Content in the API Relay](/embedding_using_analytics/data_manager/api_relay_dynamic_body_content).

***

### Response Caching

Optional. A relay makes a fresh outgoing request on every call by default. Turn on caching when the same
response is valid for more than one caller or more than one moment, so repeated calls skip the round trip to
the upstream API.

* **Cache Relay Responses?** — off by default. When on, Curator stores the upstream response and reuses it for
  any later call that would have produced the same outgoing request. Calls that differ in their HTTP method or
  in the parameters they send are cached separately; parameter order does not matter, so `?a=1&b=2` and
  `?b=2&a=1` share one cached response.
* **Cache Duration (seconds)** — how long a cached response stays valid. Defaults to 60. Keep this shorter
  than the lifetime of anything the response contains: a relay that returns a short-lived OAuth token should
  expire its cache well before the token does.
* **Cache Per User?** — off by default, which is correct when every caller legitimately receives the same
  response, such as a client credentials OAuth flow. Turn it on when the upstream response differs per user.
  Curator then keeps a separate cached response for each signed-in user, and any call it cannot attribute to a
  specific user is not cached at all — including calls to the relay's own unauthenticated URL, and every call
  on a portal using Pass-Through authentication, where all visitors share one identity.

Three things are never served from, or written to, the cache:

* **Webhook relays.** A webhook forwards the incoming payload upstream as a write, so replaying an earlier
  response would silently drop a repeated submission.
* **Requests carrying a file upload**, which cannot be matched against an earlier call.
* **Requests that fail Incoming Request Validation**, which are rejected before the cache is consulted.

Saving the relay clears its cached responses, so any configuration change takes effect on the next call rather
than after the cache duration elapses.

***

### Incoming Request Validation

Optional rules that Curator evaluates before forwarding any request. If a request fails validation, the relay
is not called and Curator returns an error.

#### Header-based validation

Define conditions on specific HTTP headers in the incoming request. For each rule, specify:

* **Header** — the HTTP header name to inspect.
* **Condition** — one of: Matches, Does not match, Contains, Does not contain, Starts with, Ends with.
* **Value** — the value to test against.

All defined rules must pass for the relay to proceed.

#### Variable-based validation

The same conditional structure applied to query string or POST body parameters rather than headers.

#### Validation failure response

By default, a validation failure returns an **HTTP 403** response. Disable **Should validation failures respond
with error code?** to return an **HTTP 200** with an error message in the body instead. Some webhook endpoints
or client-side integrations expect 200 for all responses; use this toggle if the caller cannot handle 4xx
status codes.

***

## Securing a relay

The relay endpoint is public and unauthenticated — it does not require a logged-in user, and any caller who
knows the Portal Link can trigger it. Your credentials stay safe (they live in **Constants**, server-side), but
the endpoint itself is open. To lock it down:

* **Require a shared secret (recommended).** Add an **Incoming Request Validation** rule that checks for a header
  or variable only authorized callers know — e.g. a header `X-Relay-Token` with condition **Matches** and a
  long random value. Requests without it are rejected before the relay forwards anything.
* **Restrict by IP at the network layer.** Curator has no built-in per-relay IP allowlist. To limit the relay to
  specific source IPs, enforce it in front of Curator — in your web server (nginx/Apache), load balancer,
  firewall, or WAF — by allowing only trusted IPs to reach the `/api/v1/integration/apiRelay` path. Do not rely
  on a validation rule against a forwarded header such as `X-Forwarded-For`: that header is caller-supplied and
  can be spoofed.

## Calling the relay

Once a relay is saved, Curator generates a **Portal Link** shown at the top of the edit form. This is the
URL you call to trigger the relay. Its structure is:

```
https://your-curator-instance.com/api/v1/integration/apiRelay?api_relay_id=X&variable1=X&variable2=X
```

* `api_relay_id` is the numeric ID of the relay record (fixed).
* Each configured **Variable** appears as a query parameter.

The relay accepts both **GET** and **POST** requests. For POST, variables can be supplied in the request body
instead of the query string.

### Response format

Curator returns a JSON object in all cases. The shape depends on whether the relay succeeded, failed, or was
blocked by validation.

**On success:**

```json theme={null}
{
  "result": "Success",
  "msg": { ... }
}
```

| Field    | Description                                                                      |
| -------- | -------------------------------------------------------------------------------- |
| `result` | `"Success"` or `"Failure"`.                                                      |
| `msg`    | The external API's response body — parsed if it is JSON, otherwise a raw string. |

**On failure** — `result` is `"Failure"` and `msg` is a human-readable error. This covers both relay-level
problems (missing or invalid `api_relay_id`, a missing required variable) **and** upstream API errors: if the
external API responds with an HTTP status of 400 or higher, the relay reports failure with a message like
`There was an error processing your request: API Relay call failed with HTTP code 500`.

```json theme={null}
{
  "result": "Failure",
  "msg": "There was an error processing your request: ..."
}
```

**When Incoming Request Validation blocks the call:**

```json theme={null}
{
  "status": "error",
  "msg": "Invalid incoming request for API relay"
}
```

Validation failures use a different envelope (`status` instead of `result`) and return HTTP 403 by default (or
HTTP 200 if you have disabled the **Should validation failures respond with error code?** toggle).

***

## Good to know

* **Constants are never exposed to callers.** They are stored server-side and merged into the outgoing request
  by Curator. A caller inspecting browser network traffic will only see the Curator relay URL and their own
  variables — not the upstream API credentials.

* **Variable names are pass-through.** A variable named `start_date` in the relay configuration must be sent
  as `start_date` in the incoming request. Curator does not rename or transform variable names — only dynamic
  body content advanced processing can modify values.

* **Headers sent by the caller are not forwarded by default.** Only headers you explicitly define in the
  **Headers** section are included in the outgoing request. This prevents accidental forwarding of cookies,
  session tokens, or other browser headers to the external API.

* **Relay calls are unauthenticated by default.** Curator does not require the caller to be a logged-in user to
  hit the relay endpoint — see [Securing a relay](#securing-a-relay) if you need to restrict access.

* **Enabling Log Relay Usage adds full request/response logging.** This is useful during development and
  debugging but can be verbose. Logs are written to Curator's standard application log files under
  `storage/logs/`. Disable logging in production once the integration is confirmed working. Constants flagged
  with **Encrypt Value** are redacted from these logs (shown as `***redacted***`) in the logged arguments and
  outgoing URL, and are also scrubbed from the logged upstream response when it echoes the value back. Values
  shorter than 8 characters are only redacted from the arguments and URL, since matching such short strings
  elsewhere would corrupt unrelated parts of the log.

* **The relay is a thin forwarder.** It returns the upstream response body largely as-is (parsing it if it is
  JSON) rather than reshaping it. The one thing it does act on is the upstream HTTP status: a 400-or-higher
  response is turned into a `"Failure"` envelope rather than passed through as a success.

* **`[Grouped] API Relay X was used` in the Event Log is log grouping, not a cap on relay calls.** When the same
  Event Log message repeats often enough, Curator stops writing a separate line for every occurrence and logs one
  entry standing in for the duplicates instead — see
  [Log Rate Limiter](/site_administration/logging/log_rate_limiter). Nothing about the relay is throttled or
  blocked, and there is no per-relay limit to raise. Read it as a signal that something is repeating: open the
  grouped entry for the count and the time it started, and look at the entries logged before grouping began to
  find the underlying error. Turning on **Log Relay Usage?** temporarily captures the request and response detail
  behind those entries.

***

## Related

* [Sending Data to Webhooks](/embedding_using_analytics/data_manager/sending_data_to_webhooks) — how to connect
  an API relay to Data Manager for mark-commenting webhook submissions.
* [Dynamic Body Content in the API Relay](/embedding_using_analytics/data_manager/api_relay_dynamic_body_content) —
  letting an incoming request set or edit the outgoing request body.


# Overview
Source: https://docs.curator.interworks.com/creating_integrations/overview

Overview of creating and managing integrations with external platforms in Curator

## Overview

Integrations connect Curator to your business intelligence platforms, allowing
you to embed dashboards, synchronize users, and centralize analytics access.

### What are Integrations?

Integrations (also called "Connections") allow Curator to communicate with external BI platforms. Once configured,
these connections enable you to:

* **Embed visualizations**: Add dashboards and reports from your BI platforms directly to Curator
  by selecting dropdown options
* **Synchronize users**: Keep user access and permissions in sync between Curator and your BI platforms
* **Monitor health**: Automatically detect connection issues and receive email alerts when problems occur
* **Automate tasks**: Schedule data refreshes, run scripts, and execute platform-specific commands

### How Connections Work

Each connection stores the server details and authentication credentials needed to communicate with the external
platform. Curator securely encrypts sensitive information and continuously monitors connection health to ensure
reliable access to your analytics. Follow the platform-specific setup guides to create and configure the
connection to your BI tool.

### Backend User Permissions

When a backend user saves a new connection, Curator automatically grants that user the backend permissions
needed to access the integration. **Other backend users do not receive these permissions automatically** — they
must be granted access manually by a super-administrator.

If an integration does not appear in the backend navigation for a particular user after a connection has been
created, the most likely cause is that the user has not been granted the required permissions. To resolve this:

1. Log in to the Curator backend as a super-administrator.
2. Navigate to **Settings** > **Administrators**.
3. Click on the backend user who cannot see the integration.
4. Open the **Permissions** tab and locate the section for the relevant platform (e.g., **Sigma**, **PowerBI**,
   **Tableau**, or **ThoughtSpot**).
5. Enable the required permissions for that user and save.

### Supported Platforms

Curator supports integrations with the following platforms:

* [Tableau Cloud](/creating_integrations/tableau_connection/tableau_cloud_setup)
* [Tableau Server](/creating_integrations/tableau_connection/creating_a_connection)
* [Power BI](/creating_integrations/power_bi_connection/azure_app_setup)
* [ThoughtSpot](/creating_integrations/thoughtspot_connection/integrating_thoughtspot_with_curator)
* [Sigma Computing](/creating_integrations/sigma_connection/creating_a_sigma_connection)


# Azure Admin Registered App Setup
Source: https://docs.curator.interworks.com/creating_integrations/power_bi_connection/azure_admin_app_setup

Step-by-step guide to set up Azure application registration for Power BI's Admin API integration with Curator.

## Steps

<PowerBIConnectionSteps />

## Creating a registered app for the admin API within the Azure Portal

This will be a very similar process to creating the non-admin registered app in the previous step, but this registered app
will be used for authentication to the read-only Power BI **Admin API** for Curator to be able to check permissions, etc.
on behalf of Power BI users.

1. Log in to the [Azure Portal](https://portal.azure.com);
2. Search for “App Registrations” to start the process.  You may also find them inside the
   *Microsoft Entra ID* > *Manage* > *App Registrations*.
3. Click the button to register a new application.
4. Add a distinct and descriptive name. It's suggested to clarify that this is for the Admin API
   (e.g. "Curator Power BI Admin API App").
   * You should skip the "Redirect URI" step for this registered app as it will not be used.
     <Note>Make sure to create this app registration under the same Azure tenant as the non-admin registered app created previously.</Note>
5. Once the app is registered, make note of the following details from the “Overview” page as you will need them when
   setting up the configuration on Curator:
   * Application (client) ID - This will be used as the **Admin Client ID** in Curator.
   * Directory (tenant) ID - This should be the same as the tenant ID used for the registered app.

## API Permissions

<Warning>Do **not** add any API permissions to this registered app.  It does not need permissions assigned in order to access
the read-only admin APIs, and in fact adding them will actually prevent it from being able to access those APIs.</Warning>

## Create a Client Secret

<Note>
  Curator's Power BI integration supports client secret authentication only.  Do not use the *Certificates* tab to configure
  certificate-based authentication, as it is not supported.
</Note>

1. While still viewing the admin registered app, click on *Manage* > *Certificates & secrets* in the left navigation.
2. Click the button to add a new client secret.  This will be used as the **Admin Client Secret** in Curator.
3. Fill in the description and adjust the expiration date as desired, and click the save button.
4. Copy the client secret **value** and document it in a secure place.
   <Info>You will not be able to retrieve the value again once you leave this screen.</Info>
   <Warning>Do not confuse this with the *Secret ID*.  Curator must have the secret *value* to authenticate.</Warning>

<Warning>
  Until this Admin Registered App setup is complete and the credentials are saved in Curator, Power BI items in the
  **User Menu Access** tab will display amber warning icons and access previewing will be unavailable. Complete this
  setup and enter the credentials under **Settings** > **Power BI Settings** on the **Admin** tab to enable access
  previewing.
</Warning>


# Azure Registered App Setup
Source: https://docs.curator.interworks.com/creating_integrations/power_bi_connection/azure_app_setup

Step-by-step guide to set up Azure application registration for non-admin Power BI integration with Curator.

## Steps

<PowerBIConnectionSteps />

## Creating a Registered App within the Azure Portal

This registered app will be used for authentication to the Power BI non-admin APIs on behalf of users accessing
Power BI content within Curator.

1. Log in to the [Azure Portal](https://portal.azure.com);

2. Search for “App Registrations” to start the process.  You may also find them inside the
   *Microsoft Entra ID* > *Manage* > *App Registrations*.

3. Click the button to register a new application.

4. Give the app a distinct and descriptive name and provide a redirect URI during this process under the "Web"
   platform.  The redirect URI should follow
   this format:

   `https://curatorexample.com/powerbi`

   <Warning>
     If the redirect URI is not configured correctly, users will see an error like:

     `AADSTS50011: The redirect URI specified in the request does not match the redirect URIs configured for the application.`

     **To fix this:**

     1. Go to [Azure Portal](https://portal.azure.com)
     2. Find your app registration
     3. Click **Manage** > **Authentication (Preview)** in the left navigation
     4. Add a **Web** redirect URI using your Curator portal's domain with the `/powerbi` suffix (e.g., `https://curatorexample.com/powerbi`)
   </Warning>

5. Once the app is registered, make note of the following details from the “Overview” page as you will need them when
   setting up the configuration on Curator:
   * Application (client) ID
   * Directory (tenant) ID
   * Application ID URI

## API Permissions

Your InterWorks Curator Azure Registered App will need several delegated API permissions.  While still viewing the
registered app, click on *Manage* > *API permissions* in the left navigation.  Add the following permissions as delegated
permissions:

<Note>
  Curator uses the OAuth delegated permission flow, which requires each user to sign in with their own Microsoft account.
  Application-level (service principal) permissions are not compatible with this registered app. If you need to configure a
  service principal for the Admin API, see the
  [Azure Admin Registered App Setup](/creating_integrations/power_bi_connection/azure_admin_app_setup) page.
</Note>

* Microsoft Graph
  * User.Read
* Power BI Service
  * Dashboard.Read.All
  * Dataset.Read.All
  * Report.Read.All
  * Workspace.Read.All

If you intend to use **persistent filters** or other functionality that tracks user state, you'll also need to add:

* Power BI Service
  * UserState.ReadWrite.All

<Note>
  Depending on your level of access, you may need to ask Azure administrators to grant admin consent for these permissions.
</Note>

## Create a Client Secret

<Note>
  Curator's Power BI integration supports client secret authentication only.  Do not use the *Certificates* tab to configure
  certificate-based authentication, as it is not supported.
</Note>

1. While still viewing the registered app, click on *Manage* > *Certificates & secrets* in the left navigation.
2. Click the button to add a new client secret.
3. Fill in the description and adjust the expiration date as desired, and click the save button.
4. Copy the client secret **value** and document it in a secure place.
   <Info>You will not be able to retrieve the value again once you leave this screen.</Info>
   <Warning>Do not confuse this with the *Secret ID*.  Curator must have the secret *value* to authenticate.</Warning>


# Curator Connection
Source: https://docs.curator.interworks.com/creating_integrations/power_bi_connection/curator_connection

Final setup steps to create and configure the Power BI connection within Curator backend.

## Steps

<PowerBIConnectionSteps />

## Creating Curator Connection to Power BI

Note: You will need details from your non-admin registered app and your admin registered app.  See steps 1-3 above if you have not configured those yet.

If your Curator license allows you to connect to Power BI, you can connect to it by following this process:

1. <BackendNavPath />
2. Click the button at the top to create a new connection.
3. From here, fill out the details under the *Power BI Connection* section, then click save.  The first 3 fields need to be
   filled in, but the 2 admin fields are highly recommended because they will lead to a better overall experience.

   * **Cloud Environment**: Leave on *Commercial (default)* unless this tenant is hosted in a Microsoft US Government sovereign cloud (GCC, GCC High, or DoD). See [US Government Cloud (GCC) Setup](./us_government_cloud) for details.
   * **Client ID**: "Application (client) ID" from the non-admin registered app (see [Azure App Setup](/creating_integrations/power_bi_connection/azure_app_setup)).
   * **Tenant ID**: "Directory (tenant) ID" from the non-admin registered app (see [Azure App Setup](/creating_integrations/power_bi_connection/azure_app_setup)).
   * **Client Secret**: "Client secret" value (again, not the client secret ID) from the non-admin registered app (see [Azure App Setup](/creating_integrations/power_bi_connection/azure_app_setup)).
   * **Admin Client ID**: "Application (client) ID" from the *admin* registered app (see [Azure Admin App Setup](/creating_integrations/power_bi_connection/azure_admin_app_setup)).
   * **Admin Client Secret**: "Client secret" value (again, not the client secret ID) from the *admin* registered app (see [Azure Admin App Setup](/creating_integrations/power_bi_connection/azure_admin_app_setup)).
4. Refresh the page after saving and you should see a Power BI section show up in the left navigation.

### Authentication Groups (optional)

Under the *Authentication Groups* section on the Power BI connection, you can control which Frontend Groups are sent through the Microsoft authentication flow. This is useful when only a subset of your users actually need Power BI access -- skipping the Microsoft login for everyone else avoids unnecessary prompts for content they cannot view.

The **Authentication Group Mode** toggle determines how the *Frontend Groups* list below it is interpreted:

* **Exclude listed groups from Microsoft authentication** (default): Users in any listed group skip the Microsoft login flow. All other users go through it. Use this when most of your users need Power BI authentication and only a few groups should be excluded.
* **Only require Microsoft authentication for listed groups**: Only users in a listed group are sent through the Microsoft login flow. All other users bypass it. Use this when only a small subset of your users need Power BI authentication.

If the *Frontend Groups* list is empty, the toggle has no effect -- every user is sent through Microsoft authentication, matching the default Power BI behavior.

### Validate a successful connection

* The admin registered app connection was successful if the dropdowns in the backend under **Power BI** > **Reports** >
  **Create** a new report populate.
* The non-admin registered app connection was successful if reports load in the frontend.  Be sure to log out of the frontend and log back in fresh.

If you run into any issues, you can refer to the [Troubleshooting Power BI Access](./troubleshooting_power_bi_access) documentation for help.


# Power BI Workspace Access
Source: https://docs.curator.interworks.com/creating_integrations/power_bi_connection/power_bi_workspace_access

Configure workspace permissions for Power BI integration with Curator.

## Steps

<PowerBIConnectionSteps />

## A Note on Terminology

The terms "registered app", "service principal", and "client" are technically not the same thing, however, for the
purposes of this documentation you can think of them as the same thing.  Similarly, "Power BI" and "Fabric" can also be
considered the same things for the purposes of this documentation. If you already understand the differences, you
probably also understand how to adjust the steps outlined in this documentation to meet your own needs.

## Allow service principals to use Fabric APIs

The registered apps created in the previous steps need to be able to access Power BI APIs in order to query which
workspaces, Dashboard, reports, etc. exist in your environment when publishing content to Curator.

To enable the Power BI APIs:

1. Log in to the [Power BI portal](https://app.powerbi.com) with an account that has access to the admin portal.
2. Navigate to the [admin portal](https://app.powerbi.com/admin-portal) by clicking on the gear icon at the top right.
3. Select "Tenant Settings" on the left if not already selected.
4. Scroll to the "Developer settings" section and expand the "Allow service principals to use Fabric APIs" group.
5. Click the switch to enable.  If desired, restrict access to only specific security groups (make sure the registered
   apps that Curator will be using are included in a security group specified here).
   <Note>Enabling this setting may take \~15 minutes to take effect.</Note>

## Allow service principals to access read-only admin APIs

The admin registered app needs read-only access to the Power BI Admin APIs in order to query permissions, etc. on behalf of
Power BI users.

To enable the read-only admin APIs:

1. Log in to the [Power BI portal](https://app.powerbi.com) with an account that has access to the admin portal.
2. Navigate to the [admin portal](https://app.powerbi.com/admin-portal) by clicking on the gear icon at the top right.
3. Select "Tenant Settings" on the left if not already selected.
4. Scroll to the "Admin API settings" section and expand the "Service principals can access read-only admin APIs" group.
5. Click the switch to enable.  If desired, restrict access to only specific security groups (make sure the admin registered app that Curator will be using is included in a security group specified here).
   <Note>Enabling this setting may take \~15 minutes to take effect.</Note>

## Add Registered Apps to Power BI Workspace(s)

In order for the non-admin and admin registered apps to have access to your Power BI content, they must have
permissions to the Power BI workspace(s) you intend to use with Curator.

To add access to a workspace:

1. Log in to the [Power BI portal](https://app.powerbi.com).
2. In the left navigation, click on “Workspaces”.
3. Hover your mouse over one of the workspaces and click on the 3 dots that appear on the right.  Choose “Workspace access”.
4. Search for the non-admin registered app name and give it the "Admin" permission.  This ensures Curator will
   have access to add any content from Power BI that your Curator admins would like to add.
5. Repeat step 4 for the admin registered app name, also giving it "Admin" permission.
6. (optional) Repeat steps 2-5 for any remaining workspaces that need access.

<Note>
  There are other paths to get to the screens mentioned above, but there have been times when those paths
  don't work correctly. The steps above are the most reliable way to get to the correct screens.
</Note>


# Troubleshooting Power BI Access
Source: https://docs.curator.interworks.com/creating_integrations/power_bi_connection/troubleshooting_power_bi_access

Common issues and solutions for Power BI connection problems in both frontend and backend access scenarios.

Power BI connections have separate frontend and backend functionality, even though everything is configured from the
backend connection. When troubleshooting issues, it's important to test each area separately since one might work
perfectly while the other fails completely.

***

## Backend User Permissions

After a Power BI connection is saved, the **Power BI** section may not appear in the backend navigation for
some users. This is a permissions issue — the connection is valid, but the backend user has not been granted
access to the Power BI plugin.

Curator automatically grants backend permissions to the user who saves the connection. Other backend users must
be granted access manually:

1. Log in as a super-administrator.
2. Navigate to **Settings** > **Administrators**.
3. Open the affected user's record and click the **Permissions** tab.
4. Under the **PowerBI** section, enable **Power BI administrator**.
5. Save the user record.

***

## User Menu Access Warnings

When viewing the **User Menu Access** tab in the backend, Power BI items may display an amber warning icon
(⚠) next to the menu entry.

This icon means Curator cannot preview a user's access to that item because the **Admin Registered App** is not
configured. Without an Admin connection, Curator has no way to query Power BI's Admin API to determine which
workspaces and reports a user can see.

**How to resolve:**
Complete the [Azure Admin Registered App Setup](/creating_integrations/power_bi_connection/azure_admin_app_setup)
and enter the resulting credentials under
<BackendNavPath /> on the **Admin** tab.

Once the Admin connection is saved, the warning icons will disappear and User Menu Access will correctly reflect
each user's Power BI permissions.

***

## Backend Troubleshooting

The backend integration with Power BI is straightforward - there's one reliable way to test it and only a few common
failure points.

### Test if Backend is Working

Follow these steps to verify your backend connection:

1. <BackendNavPath />

2. Click the **Clear Cache** button (top right) to ensure fresh data.

3. Click the **New Report** button to navigate to the "Create Report" page.

4. Use the dropdown menus to select a workspace and report

   * **Success:** If you can select both workspace and report, your backend is working! Skip to the
     [Frontend section](#frontend-troubleshooting)
   * **Problem:** If either dropdown is empty when it shouldn't be, continue to the troubleshooting steps below

<img alt="Power BI Backend Success" />

### Debug Backend Issues

When the backend isn't working, you need to see what Power BI is actually telling Curator.

#### Enable Debug Mode

1. <BackendNavPath /> Click on the **Advanced** tab.

2. **Enable debugging**
   Toggle on **Debug Mode for Power BI** and click save

   <Warning>
     Debug mode increases logging and can fill up your server. Set a reasonable **Debug Mode Expiration**
     (default: 24 hours).
   </Warning>

3. **Repeat the steps to recreate the issue**
   Follow the steps in [Test if Backend is Working](#test-if-backend-is-working) again to recreate the issue while
   debug logging is enabled.

4. **Check the logs:**
   1. <BackendNavPath />

   2. **Find Power BI calls**
      Filter for `Power BI API Call` using the search box (top right)

   3. **Review responses**
      Click on entries to see Power BI's detailed responses

For more information about Curator's logging systems, see the [Logging Overview](/site_administration/logging/logging_overview).

#### Common Solutions

**If you see error messages:**
The solution depends on the specific error. Contact Curator support if the fix isn't obvious.

Some errors may be prefixed with `POWER BI ERROR` or `ERROR during powerbi flow`, but others may have different text.

**If responses are blank:**
This means Curator can connect to Power BI, but the admin registered app (or non-admin registered app if not using admin)
lacks workspace access. Try these fixes:

##### 1. Grant workspace access

Follow the [Add Registered App to Power BI Workspace(s)](/creating_integrations/power_bi_connection/power_bi_workspace_access)
instructions

##### 2. Enable Fabric APIs

Follow the [Allow service principals to use Fabric APIs](/creating_integrations/power_bi_connection/power_bi_workspace_access)
instructions
*(Note: This change can take time to take effect in Power BI)*

##### 3. Check security groups

If Fabric APIs are restricted to specific security groups, ensure your registered apps are a member of one of those
groups.

### Expired or Rotated Client Secret

Azure client secrets have a finite lifetime. When you create a client secret in Azure, you choose an expiration
period (commonly 6, 12, or 24 months). Once the secret expires, Power BI will reject Curator's authentication
requests and all Power BI content will stop loading until a new secret value is generated in Azure and saved in
Curator's Power BI settings.

**Symptoms:**

* Power BI dashboards and reports that previously worked stop loading for all users at once.
* Backend test pages (such as **Power BI** > **Reports**) return authentication errors when fetching workspaces or reports.
* Event logs show errors mentioning `AADSTS7000222`, `Invalid client secret provided`, or `client secret has expired`.
* The **Admin** and **Non-Admin** tabs under <BackendNavPath /> may
  still display the previously saved secret, but Azure no longer accepts it.

<Note>
  Curator authenticates to Power BI using a client secret only. Certificate-based authentication is not currently
  supported, so rotating the client secret is the only way to restore access once the existing secret has expired.
</Note>

To rotate the client secret, follow the [Create a Client Secret](/creating_integrations/power_bi_connection/azure_app_setup#create-a-client-secret)
steps in the Azure App Setup guide for the non-admin registered app (and the matching
[Create a Client Secret](/creating_integrations/power_bi_connection/azure_admin_app_setup#create-a-client-secret)
steps in the Azure Admin App Setup guide if you have configured an Admin Registered App). Then enter the new secret
value in Curator as described in the [Curator Connection](/creating_integrations/power_bi_connection/curator_connection)
guide.

### Admin Permissions Appear Then Disappear

Sometimes the Admin Registered App works right after you save its credentials, then stops working within hours or
days. The pattern can repeat: access comes back, then disappears again. This pattern is different from an expired
secret, which fails once and stays failed until you rotate it.

**Symptoms:**

* The workspace and report dropdowns under **Power BI** > **Reports** > **New Report** populate at first, then come
  back empty. These dropdowns use the non-admin registered app, so this symptom points at that app.
* Users see Power BI items in navigation after they log in, then lose them later in the same day. Navigation uses
  the admin registered app, so this symptom points at that app.
* Event log entries for `Power BI API Call` alternate between full responses and blank or `401`/`403` responses.

<Note>
  Curator caches the result of each Power BI permission check for up to 60 minutes, so a change in Power BI or Azure
  can take up to an hour to show in the backend. Click the **Clear Cache** button in the top right of the backend to
  drop that cache. Frontend navigation works differently. When an Admin Registered App is configured, Curator downloads
  the list of reports each user can see at the moment that user logs in to Power BI, and stores that list in the
  Curator database. Clear Cache does not download the list again. A user must log in to Power BI again, for example by
  logging out of Curator and back in, before a change in Power BI or Azure shows in their navigation.
</Note>

There are three common causes. Check them in this order.

#### 1. Tenant setting has not propagated or was turned off

The Admin Registered App depends on two Power BI tenant settings: **Service principals can call Fabric public APIs**
under *Developer settings*, and **Service principals can access read-only admin APIs** under *Admin API settings*.
Older tenants show the first setting as **Allow service principals to use Fabric APIs** or **Allow service
principals to use Power BI APIs**.
Both settings can take up to 15 minutes to propagate across your organization after you enable them. During that
window, some requests succeed and others fail. If another admin later turns a setting off, or removes the admin app
from the security group that the setting allows, access stops as soon as the cached permission checks expire.

1. Log in to the [Power BI admin portal](https://app.powerbi.com/admin-portal) and select **Tenant settings**.
2. Confirm that **Service principals can call Fabric public APIs** is enabled.
3. Confirm that **Service principals can access read-only admin APIs** is enabled.
4. If either setting is restricted to specific security groups, confirm that the admin registered app is still a
   member of one of those groups.
5. If you changed a setting, wait 15 minutes before you test again.

See [Power BI Workspace Access](/creating_integrations/power_bi_connection/power_bi_workspace_access) for the full
steps to enable each setting.

#### 2. Registered app was removed from a workspace

You manage workspace membership in Power BI, not in Curator. If another admin removes the registered app from a
workspace, or lowers its role, Curator loses access to that workspace once the cached permission checks expire.
Reports in other workspaces keep working, so the problem can look intermittent.

1. Log in to the [Power BI portal](https://app.powerbi.com) and click **Workspaces** in the left navigation.
2. Hover over a workspace that Curator uses, click the three dots, and choose **Workspace access**.
3. Confirm that both the non-admin and admin registered apps are listed with the **Admin** role.
4. Repeat for each workspace that Curator uses.

If an app is missing, follow the
[Add Registered Apps to Power BI Workspace(s)](/creating_integrations/power_bi_connection/power_bi_workspace_access#add-registered-apps-to-power-bi-workspaces)
steps to add it back.

#### 3. Client secret was created with a short expiry

Azure lets you choose a custom expiry date when you create a client secret. A secret created with an expiry of hours
or days works during setup and then fails as soon as the date passes. If an admin then creates another short-lived
secret, the cycle repeats.

1. Log in to the [Azure Portal](https://portal.azure.com) and open **App registrations**.
2. Open the admin registered app and click **Manage** > **Certificates & secrets**.
3. Check the **Expires** column for the secret that Curator uses.
4. If the secret has expired or expires soon, create a new one with an expiry of months rather than days.
5. Repeat steps 2 through 4 for the non-admin registered app.
6. Follow the [Expired or Rotated Client Secret](#expired-or-rotated-client-secret) steps to save the new value in
   Curator.

After you correct any of these causes, click the **Clear Cache** button in the top right of the backend and repeat
the steps in [Test if Backend is Working](#test-if-backend-is-working). Then ask an affected user to log out of
Curator and log back in, so that Curator downloads their Power BI report list again, and confirm that the Power BI
items return to their navigation.

***

## Frontend Troubleshooting

Once your backend connection works and you've published Power BI content to Curator's navigation, users should be able
to access it seamlessly.

### Expected User Flow

When everything is configured correctly (following [setup steps 1-4](/creating_integrations/power_bi_connection/azure_app_setup)),
users should experience:

1. **Log in to Curator**
   Using the method configured in your [Authentication Settings](/setup/authentication/overview).

2. **Authenticate with Power BI**
   *(This may happen automatically with SSO)*

3. **Access content**
   Curator displays all accessible content based on platform permissions:

   * Tableau content: controlled by Tableau
   * ThoughtSpot content: controlled by ThoughtSpot
   * Power BI content: controlled by Power BI

   <Note>
     Curator can add additional restrictions but cannot expand access beyond what the source platform allows.
   </Note>

### Content Loads But Displays Blank

If Power BI content appears in Curator's navigation and the page itself loads, but the report area renders as a
blank space with no visible error, the failure is happening inside the Power BI JavaScript SDK after Curator has
already handed off the embed.

Curator embeds Power BI content using *user-owns-data* embedding: the report is loaded with the signed-in user's own
Microsoft Entra ID (Azure AD) access token, and Power BI then decides what that individual user is allowed to see.
This means Curator's server-side work can succeed completely — the content is published, the user passes Curator's
own permission checks, and the embed URL is retrieved — while Power BI still declines to render the report for that
particular user.

Because this failure happens in the browser, it is not recorded in
<BackendNavPath />, and enabling **Debug Mode for
Power BI** will not capture it. The error is reported to the browser console instead:

1. Open the blank report page in Curator.
2. Open your browser's developer tools (**F12**) and select the **Console** tab.
3. Reload the page and look for an entry beginning with `onerror called`. Expand it to read the error message
   returned by Power BI.

This is most common the first time a newly onboarded group of users logs in, and it is usually caused by the user's
Power BI setup rather than by Curator:

* The user does not have a **Power BI Pro** or **Premium Per User (PPU)** license assigned.
* The user has not been granted access to the workspace, the report, or the report's underlying dataset.
* The report uses **Row-Level Security (RLS)** and the user has not been assigned to an RLS role.

To confirm where the problem lies, have the affected user open the same report directly in the Power BI service at
[app.powerbi.com](https://app.powerbi.com). If it does not render there either, the access must be corrected in
Power BI before Curator can display it.

Newly granted access can also take a short while to show up. Microsoft can take a few minutes to finish applying new
licenses, group memberships, or workspace roles, and when Power BI declines a report for a user, Curator briefly
remembers that result (30 seconds by default) before checking again. If a report is still blank right after access
was corrected, wait a moment and reload the page, or have the user fully sign out of Curator and sign back in —
completing the Microsoft sign-in prompt re-checks the user's access immediately. If your portal intentionally
restricts many reports and you would rather Curator re-check declined access less often, raise the **Failed
Permission Re-Check Interval** in Power BI Settings (up to one hour).

<Note>
  Expired access tokens are handled separately. Curator detects a `TokenExpired` error and requests a fresh token
  automatically, so an expired token is not a typical cause of a permanently blank report.
</Note>

### Debug Frontend Issues

If users see other Curator content but Power BI content is missing from navigation, follow these steps:

#### Verify Power BI Authentication

1. **Enable frontend debug mode**
   Follow the steps to [enable frontend debug mode](/site_administration/performance/troubleshooting_load_times).

   <Tip>Remember to disable this after troubleshooting.</Tip>

2. **Add debug parameter**
   In your browser, add `?debug=1` to the URL
   * Example: `https://curator.yourcompany.com/` becomes `https://curator.yourcompany.com/?debug=1`
     <Note>If URL already has a `?` character in it, use `&debug=1` instead</Note>

3. **Check session data**
   * Look for the debug bar at the bottom of the screen
   * Click **Session** tab
   * Look for a **`powerbi`** > **`user`** entry to ensure it has an "accessToken" value.

4. **Interpret results**
   * **Missing entry:** Authentication failed → Log out and log back into Curator
   * **Valid entry:** Authentication succeeded but Power BI reports no accessible content → Continue to next section

#### Check Power BI API Responses

1. <BackendNavPath /> Click on the **Advanced** tab.  Enable the
   **Debug Mode for Power BI** toggle and click save.

   <Warning>
     This increases logging significantly. Set a reasonable **Debug Mode Expiration** (default: 24 hours).
   </Warning>

2. **Clear cache:**
   Click **Clear Cache** button (top right) to force fresh API calls.

3. **Refresh frontend:**
   Go back to Curator's frontend and refresh the page.

4. **Check API logs:**
   If Power BI content still doesn't appear:
   * <BackendNavPath />
   * Look for Power BI API calls
   * Click entries to view detailed responses

5. **Get support:**
   API responses can be complex. Send the details to Curator support for analysis. Meanwhile, verify the user has
   proper access to the Power BI workspace and content in question.

### Redirect URI Mismatch

If you see an error containing `AADSTS50011: The redirect URI specified in the request does not match the redirect URIs
configured for the application`, the Azure app registration is missing the correct redirect URI.

**To fix this:**

1. Go to the [Azure Portal](https://portal.azure.com) and find your app registration
2. Click **Manage** > **Authentication (Preview)** in the left navigation
3. Under the **Web** platform, add a redirect URI using your Curator portal's domain with the `/powerbi` suffix
   * Example: `https://curatorexample.com/powerbi`
4. Save the changes
5. Log out and log back in to Curator to verify the fix

### SSL Certificate Errors

If you encounter an error like this when testing Power BI connections:

```txt theme={null}
GuzzleHttp\Exception\RequestException: cURL error 60: SSL certificate problem: unable to get local issuer certificate
```

This occurs when PHP cannot verify SSL certificates for HTTPS connections to Power BI API and Azure AD OAuth endpoints.
This is most common on Windows servers where the CA certificate bundle is not properly configured.

Curator provides three ways to configure SSL certificate verification through the `POWER_BI_SSL_VERIFY` environment variable:

* **Default**: Standard SSL verification (works on properly configured servers)
* **CA Bundle**: Download and configure a certificate bundle for secure verification
* **Off (*not recommended*)**: Turn off verification entirely (development only)

#### Enabling SSL CA Bundle

This is the most secure solution. You'll download a trusted certificate bundle and configure Curator to use it.

1. **Download the CA bundle:**
   Visit [https://curl.se/ca/cacert.pem](https://curl.se/ca/cacert.pem) and save the file to your server in a location
   readable by your web server.

   <Tip>
     On Windows, a good location is `C:\InterWorks\cacert.pem` or in your Curator installation directory.
     On Linux, consider `/etc/ssl/certs/cacert.pem` or `/var/www/curator/cacert.pem`
   </Tip>

2. **Configure the environment variable:**
   Add or update the following line in your `.env` file with the full path to your downloaded CA bundle:

   ```env theme={null}
   POWER_BI_SSL_VERIFY="C:\InterWorks\cacert.pem"
   ```

3. **Test the connection:**
   Follow the steps in [Test if Backend is Working](#test-if-backend-is-working) to verify the error is resolved.

#### Disable SSL Verification

You can disable SSL verification entirely, but this creates serious security risks.

<Warning>
  Disabling SSL verification exposes your application to man-in-the-middle attacks where an attacker could intercept
  credentials and data. **NEVER use this in production environments.** This should only be used temporarily in isolated
  development environments.
</Warning>

1. **Set the environment variable:**
   Add or update the following line in your `.env` file:

   ```env theme={null}
   POWER_BI_SSL_VERIFY=false
   ```

2. **Test the connection:**
   Follow the steps in [Test if Backend is Working](#test-if-backend-is-working) to verify the error is resolved.


# US Government Cloud (GCC) Setup
Source: https://docs.curator.interworks.com/creating_integrations/power_bi_connection/us_government_cloud

Configure Curator to connect to Power BI tenants hosted in Microsoft US Government sovereign clouds (GCC, GCC High, DoD).

Power BI tenants on Microsoft US Government licenses (GCC, GCC High, or DoD) live in
sovereign clouds with different REST API and authentication endpoints than the commercial
Power BI service. Curator supports these sovereign clouds, but the connection must be
configured to route requests to the correct endpoints. This page covers the differences
from the standard commercial setup.

If your Power BI tenant is on a standard commercial Microsoft license, you do not need this
page. Follow the standard [Curator Connection](./curator_connection) flow instead.

## Selecting the Cloud Environment

When configuring the Curator Power BI connection (under **Integrations** > **Connections**),
the **Cloud Environment** dropdown at the top of the Power BI Connection section determines
which Microsoft cloud Curator targets for all API and authentication calls.

| Option                                                     | When to use it                                              |
| ---------------------------------------------------------- | ----------------------------------------------------------- |
| **Commercial (default)**                                   | Standard Power BI tenants on commercial Microsoft licenses. |
| **US Government Community Cloud (GCC)**                    | Power BI tenants on a GCC license.                          |
| **US Government Community Cloud High (GCC High / DoDCON)** | Power BI tenants on a GCC High license.                     |
| **US Department of Defense (DoD)**                         | Power BI tenants on a DoD license.                          |

Existing Power BI connections that predate this setting continue to use the Commercial cloud
without any change in behavior.

## Differences When Registering Azure Apps for GCC

Most of the [Azure App Setup](./azure_app_setup) steps still apply, with two specific
differences for sovereign cloud tenants:

### 1. Use the Government Power BI Service API

When adding API permissions to the registered app, the **"Power BI Service"** API listed by
default in Azure is the commercial version and will not work for sovereign cloud tenants.
Instead, search under **APIs my organization uses** for:

> **Microsoft Power BI Government Community Cloud**
> Application (client) ID: `fc4979e5-0aa5-429f-b13a-5d1365be5566`

Grant the same delegated permissions described in the standard setup, but on this
government-specific API.

### 2. The "Allow service principals to use Fabric APIs" Tenant Setting Does Not Exist

Microsoft Fabric is not deployed in US Government sovereign clouds. The Power BI Admin
portal in a GCC tenant therefore does not surface the **"Allow service principals to use
Fabric APIs"** tenant setting referenced in commercial documentation.

The equivalent setting for sovereign cloud tenants is:

> **Allow service principals to use Power BI APIs**

Enable this setting and apply it to the security group containing your Curator non-admin and
admin registered apps. The **"Apply to entire organization"** toggle is typically locked in
GCC-hardened tenants, so you must use the security group approach:

1. In **Microsoft Entra**, create a security group (for example, `Curator Power BI Apps`).
2. Add both the non-admin and admin registered apps as members of that group.
3. In the **Power BI Admin portal** > **Tenant settings** > **Developer settings**, scope
   the **"Allow service principals to use Power BI APIs"** setting to that security group.
4. Apply the same scoping to any other developer settings Curator needs (for example,
   **Embed content in apps**).

## Capacity Licensing in Sovereign Clouds

Power BI capacity licensing differs in US Government clouds. Specifically, **F SKU** (Azure
Embedded) and **A SKU** capacities are not available in GCC. Only EM, P, and Premium Per User
(PPU) licensing are supported. This does not affect Curator configuration directly, but it
may affect how you license capacity for embedded reports.

## Endpoints Curator Uses Per Cloud Environment

For reference, the following endpoints are used by Curator depending on the selected cloud
environment. You do not need to configure these manually — they are derived automatically
from the Cloud Environment selection.

| Endpoint                           | Commercial                         | GCC                                      | GCC High (DoDCON)                             | DoD                                          |
| ---------------------------------- | ---------------------------------- | ---------------------------------------- | --------------------------------------------- | -------------------------------------------- |
| Power BI API base                  | `api.powerbi.com`                  | `api.powerbigov.us`                      | `api.high.powerbigov.us`                      | `api.mil.powerbigov.us`                      |
| Microsoft Entra authority          | `login.microsoftonline.com`        | `login.microsoftonline.com`              | `login.microsoftonline.us`                    | `login.microsoftonline.us`                   |
| Power BI resource (OAuth audience) | `analysis.windows.net/powerbi/api` | `analysis.usgovcloudapi.net/powerbi/api` | `high.analysis.usgovcloudapi.net/powerbi/api` | `mil.analysis.usgovcloudapi.net/powerbi/api` |
| Web application host               | `app.powerbi.com`                  | `app.powerbigov.us`                      | `app.high.powerbigov.us`                      | `app.mil.powerbigov.us`                      |

## References

* [Power BI embedding for national/government clouds](https://learn.microsoft.com/en-us/power-bi/developer/embedded/embed-sample-for-customers-national-clouds)
* [Power BI for US Government — endpoint reference](https://learn.microsoft.com/en-us/fabric/enterprise/powerbi/service-government-us-overview)
* [Microsoft Entra authentication for national clouds](https://learn.microsoft.com/en-us/entra/identity-platform/authentication-national-cloud)
* [Enable service principal authentication for admin APIs](https://learn.microsoft.com/en-us/fabric/admin/enable-service-principal-admin-apis)


# Creating a Sigma Connection
Source: https://docs.curator.interworks.com/creating_integrations/sigma_connection/creating_a_sigma_connection

Set up and configure a connection to your Sigma analytics platform

You can follow this guide to connect to your Sigma instance to Curator.

## Preparing Sigma

1. Obtain your Sigma API URL. To determine which URL to use, see Sigma's
   [documentation](https://help.sigmacomputing.com/reference/get-started-sigma-api#identify-your-api-request-url).
2. Generate embed client credentials (Client ID and Client Secret) in your Sigma instance. See Sigma's
   [documentation](https://help.sigmacomputing.com/docs/generate-embed-client-credentials) for detailed instructions.

## Connect to Curator

1. Go to the backend of your Curator instance. Navigate to **Integrations** > **Connections** using the
   left-hand menu.
2. Click the **New Connection** button at the top of the page.
3. Enter a name for the connection (something like "Sigma" is sufficient) and edit the slug if you'd like (but
   you don't need to).
4. Choose "Sigma" in the Platform dropdown. If the option is disabled then you already have a Sigma Connection created.
5. Fill out the form that appears below the Platform dropdown:
   * **Sigma API URL**: Select your Sigma API URL from the dropdown, or choose "Manual Entry" to enter a
     custom URL.
   * **Custom Sigma API URL**: If you selected "Manual Entry" above, enter your custom Sigma API URL here.
   * **Sigma Client ID**: The client ID generated from your Sigma embed client credentials.
   * **Sigma Client Secret**: The client secret generated from your Sigma embed client credentials.
6. Hit **Save** at the top of the page.

## Validate Connection

After saving, the connection form will show an authentication check section that verifies your credentials are
working properly with the Sigma API.

## Troubleshooting

### Sigma Does Not Appear in the Backend Navigation

After saving a Sigma connection, the **Sigma** section may not appear in the backend navigation for some users.
This is a permissions issue, not a connection issue — the connection itself is valid, but the backend user has
not been granted access to the Sigma plugin.

When a connection is saved, Curator automatically grants permissions to the user who saved it. Other backend
users must be granted access manually:

1. Log in as a super-administrator.
2. Navigate to **Settings** > **Administrators**.
3. Open the affected user's record and click the **Permissions** tab.
4. Under the **Sigma** section, enable **Sigma administrator**.
5. Save the user record.

The Sigma navigation items will appear for that user on their next page load.

### Workbooks List Is Empty

If the Sigma connection validates successfully but no workbooks appear when creating Sigma content in Curator,
the embed client credentials (Client ID and Client Secret) may not have access to those workbooks within Sigma.

The Sigma API authenticates successfully with valid credentials but only returns workbooks the embed client can
access. To resolve this, ensure the embed client credentials used in the connection have been granted access to
the relevant workbooks or folders inside your Sigma instance. Refer to Sigma's
[documentation on embed client credentials](https://help.sigmacomputing.com/docs/generate-embed-client-credentials)
for details on managing permissions.

## Next Steps

Once your Sigma connection is validated, the **Sigma Workbook** page builder element will still appear grayed
out until at least one Sigma Workbook record exists in Curator. To make the element selectable:

1. Navigate to **Content** > **Sigma Workbooks** in the backend menu.
2. Create one or more Sigma Workbook records pointing at the workbooks you want to embed.
3. Once at least one workbook exists, you can add the **Sigma Workbook** element to any page via the page
   builder and select the workbook to embed.


# Alternative URL Routing
Source: https://docs.curator.interworks.com/creating_integrations/tableau_connection/alternative_url_routing

Configure URL routing for Tableau Server connections when using reverse proxies or alternative network configurations.

Curator connects to Tableau Server to verify a user's access and permissions.

Sometimes, Tableau Server is configured to live behind a "Reverse Proxy".
There are many reasons why this configuration may be preferable.

Often, though, Reverse Proxy setups with Tableau are misconfigured.
This can lead to trusted ticket whitelisting issues.

Since the Tableau Server whitelisting for issuing a trusted ticket is based on an IP address, when proxies are
misconfigured, Tableau Server sees the proxy/load balancer, instead of Curator and rejects the ticket request.

Tableau Server requires
[tsm configuration options, gateway whitelisting and several headers](https://help.tableau.com/current/server/en-us/proxy.htm#configure-the-reverse-proxy-server)
for these API calls to work correctly.

## Working Around Reverse Proxy Setups

Usually, instead of fixing Tableau Server Reverse Proxy setups, routing Curator around them is quicker and easier.

Of course, end users should continue to be routed over the reverse proxy/load balancer.

**To configure alternative routing:**

* Go to **Integrations** > **Connections** and click on your Tableau Server connection.
* Place the *internal route* to Tableau Server in *Tableau Server URL*.
* Place the user-facing route to Tableau Server in *Alternate Tableau Server URL*.

<img alt="Reverse Proxy Alt URL" />


# Creating a Tableau Connection
Source: https://docs.curator.interworks.com/creating_integrations/tableau_connection/creating_a_connection

Learn how to connect Curator to your Tableau Server or Tableau Cloud site using REST API for seamless dashboard integration.

Curator leverages Tableau’s REST API to communicate with your Tableau Server or Tableau Cloud Site to retrieve data
related to your dashboards and users, so it can display the right information to the right people. To connect Curator to
your Tableau Server/Tableau Cloud Site:

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Integration** > **Connections** section from the left-hand menu.
3. Click on the **New Connection** button at the top of the page.
4. Fill out the form, and select *Tableau* from the platform dropdown to reveal the connection details form below.
5. Expand the *Tableau Connection* section, select whether *Tableau Server* or *Tableau Cloud*, and enter in your
   Tableau Server URL or select your Tableau Cloud host, respectively.  Once the server check has been confirmed, you can
   begin filling out the authentication details using **either** a username + password or a Personal Access Token (PAT)
   using the steps below:

### Tableau Cloud: Finding Your Host and Site Content URL

When connecting to Tableau Cloud, both the **host** and the **site content URL** are derived from the URL you see in
your browser after signing in to Tableau Cloud. Split that URL into two pieces: the host (the pod, selected from the
dropdown) and the site content URL (the value entered into the *Tableau Server Site (Custom)* field).

| Browser URL                                                         | Host (dropdown)                | Site content URL |
| ------------------------------------------------------------------- | ------------------------------ | ---------------- |
| `https://us-east-1.online.tableau.com/#/site/CuratorDemo/home`      | `us-east-1.online.tableau.com` | `CuratorDemo`    |
| `https://10ax.online.tableau.com/#/site/Marketing/workbooks`        | `10ax.online.tableau.com`      | `Marketing`      |
| `https://prod-uk-a.online.tableau.com/#/site/SalesReports/projects` | `prod-uk-a.online.tableau.com` | `SalesReports`   |

**The Server URL must be the origin only** -- the scheme plus the host, with no `/#/site/...` path appended. Pasting
the full browser URL (including `/#/site/CuratorDemo`) into the Server URL field is the most common cause of a failed
server check for Tableau Cloud.

If your pod does not appear in the host dropdown, select **Custom** and enter the host portion of your browser URL
(everything between `https://` and the next `/`). Then enter your site content URL into the
*Tableau Server Site (Custom)* field as shown above.

If the server check still fails after confirming both values, see
[Tableau Connection Troubleshooting](./tableau_connection_troubleshooting) for next steps.

*Note: Only 1 connection to a specific Tableau Server URL or Tableau Cloud host can be made at a time.*

## Tableau Connections

### Tableau Server / Tableau Cloud: Personal Access Token (PAT)

**This connection-type is more stable and preferred over username and password due to changes in Tableau's APIs.**

1. Enable the toggle for *Use Personal Access Token for REST API Connection* in the "Tableau Connection" section
2. Ensure you have
   [created up Personal Access token on Tableau Server](https://help.tableau.com/current/pro/desktop/en-us/useracct.htm#create-and-revoke-personal-access-tokens),
   with at least a site administrator role and that you have the name and token.
3. Fill out the fields below, and once the confirmation check has been successful, save your settings:
   * **Personal Access Token Name** PAT Token Name
   * **Personal Access Token** PAT Token
   * **Tableau Server Site** Tableau Server Site\*
   * **Tableau Server Site (Custom)** Manually entered Tableau Server site\*

### Username & Password connection (not recommended - Tableau Server only)

**This connection type is not recommended and should only be used when absolutely required.**

Fill out the fields below, and once the confirmation check has been successful, save your settings:

* **Service Username** Tableau Server Admin Username
* **Service Password** Tableau Server Admin Password
* **Tableau Server Site** Tableau Server Site\*
* **Tableau Server Site (Custom)** Manually entered Tableau Server site\*

## Tableau Server Site (Custom)

Before saving your Tableau Connection settings for the the first time, when switching Tableau Servers, or when
connecting to Tableau Cloud you may need to use the "Tableau Server Site (Custom)" field.

1. Select "Custom" in the *Tableau Server Site* dropdown to enable the *Tableau Server Site (Custom)* field.

2. Manually enter the name of the site you wish to connect to

   **Tableau Server Site (Custom)** The value is derived from the url on Tableau Server.  For example: using
   `https://tableau.interworks.com/#/site/CuratorDemo`, you would enter **CuratorDemo**.

3. Save your settings.

*Note:* If you try to connect to a Custom Site with a Server Administrator account and get an error, make sure the user
account is specifically added to the Tableau Site you are trying to connect to. Even though it is a Server Administrator
and has frontend access to everything, it needs to be added to the site to get REST API access.

## Supported Tableau Server Versions

Curator supports Tableau Server version 2019.1 and on. This includes the latest version of Tableau Server as well.
Due to the fact that each new version of Tableau Server includes the older versions of the APIs we can support the
latest version.

In some cases people confuse support of a Tableau Server version with inclusion of new Tableau features. We strive to
integrate many of these new features when possible. Many times this is dependent on the API support. If there is a
feature you are interested in, or would like us to integrate, please reach out to our support team.


# Embed Authentication
Source: https://docs.curator.interworks.com/creating_integrations/tableau_connection/embed_authentication

Configure secure authentication methods for embedding Tableau dashboards in Curator with single sign-on options.

Embedded Authentication is how we securely connect users on the frontend to their Tableau Dashboards. Depending
on your selected method it automatically establishes a single sign-on experience or requires additional configuration
outside of Curator to avoid a second login screen to authenticate to Tableau.

Different authentication methods are available, including:

* [Connected Apps (Recommended)](#connected-apps-recommended)
* [Tableau Default Authentication](#tableau-default-authentication)
* [Trusted Tickets (Deprecated - End of Life in October 2025)](#trusted-tickets-deprecated---end-of-life-in-october-2025)

This article will guide you through setting up Embed Authentication using these methods.

## Connected Apps (Recommended)

Connected Apps establish a trusted relationship between Curator and Tableau, enabling secure authentication for
embedded Tableau content and REST API access. Unlike Trusted Tickets and Tableau Default Authentication, Connected
Apps do not depend on third-party cookies, which are increasingly being blocked by modern web browsers.

### Requirements

* Connected Apps are supported on
  * **Tableau Cloud**
  * **Tableau Server version 2022.4 and higher**.
* The Service Account User must be a
  * **Site Admin** on Tableau Cloud and
  * **Server Admin** on Tableau Server (Site Admin cannot manage Connected Apps on Tableau Server!)
* Both **Tableau Server and Curator must use SSL** to establish a trusted relationship.

*Note:* You can set up Connected Apps with either Service Username and Password or Personal Access Token.

### Service Account Best Practices

The service account used for Connected Apps is the identity Curator uses to create and manage Connected Apps and to
generate embed tokens for your users. Choosing the right account and credential type helps prevent integration
failures caused by staff turnover, credential revocations, or accidental role changes.

#### Use a Dedicated, Non-Personal Service Account

Create a dedicated service account (e.g., `curator-service@yourorg.com`) rather than using an individual employee's
Tableau account. A personal account is tied to a specific person; if that person leaves the organization, changes
roles, or has their account suspended, Curator loses access to the Connected App and all embedded dashboards stop
loading. A dedicated service account remains stable through staffing changes and makes it clear that the account
exists solely for Curator's integration.

#### Personal Access Token Considerations

Personal Access Tokens (PATs) expire on a fixed schedule and are revoked automatically when the issuing user's
password changes or their account is deactivated. If a PAT expires or is revoked without being replaced, Curator
cannot authenticate and embedded dashboards will fail to load. Tableau Cloud connections require a PAT for
authentication, so set a calendar reminder well before the expiration date to rotate the token. For Tableau Server
connections, username and password credentials are also available and do not carry an automatic expiration date.

#### Retain the Required Tableau Role

The service account must keep the required role at all times:

* **Tableau Cloud**: Site Admin
* **Tableau Server**: Server Admin

If the role is downgraded, Curator will no longer be able to manage Connected Apps or generate embed tokens.
Dashboards will fail to load for all users until the role is restored.

#### Recovery Steps After a Role Change or Credential Failure

If the service account's role is changed or its credentials become invalid, follow these steps to restore the integration:

1. Restore the service account to the required role (Site Admin on Tableau Cloud or Server Admin on Tableau Server).
2. If using a PAT, generate a new token and update it in the Curator connection settings.
3. Navigate to Integrations > Connections in the Curator backend and open the affected Tableau connection.
4. Verify the Connected App details are displayed and save the connection.
5. Clear the Curator backend cache to remove any stale session data.
6. Test by loading an embedded Dashboard in the frontend to confirm the connection is working.

### Setup

To set up Embed Authentication using Connected Apps you need to have an existing Connection to either Tableau Cloud or
Tableau Server. If not, follow our
[Tableau Connection setup guide](/creating_integrations/tableau_connection/creating_a_connection).

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to Integrations > Connections and select your Tableau connection that you want to set up Connected Apps for.
3. Scroll down to the ***Embed Authentication*** section and expand it.
4. Select **Connected Apps**.
5. Save the Connection.

After saving, Curator will create the Connected App and display following details:

* Primary Site Connected App
* Client ID & Secret - the secret is obfuscated, but a placeholder represents successful retrieval
* Creation Timestamps

If multiple Connected Apps are detected, you can select in the Primary Site Connected App dropdown which one to
use. All other fields are automatically populated and show information for troubleshooting purposes only.
If you are embedding Dashboards from multiple sites add each additional site you'd like to
connect Curator to under *Secondary Sites* ensuring each has its own Connected App.

### Authenticate with Active Directory Domain

Some Tableau Server instances using Active Directory authentication require the domain to be included with the username during Connected Apps authentication (e.g., `domain\username`).

If authentication fails and your Tableau Server logs show errors like "Could not find AD user based on username", enable the **Include AD Domain** toggle in the Connected App Settings section of your Tableau connection. The domain is automatically retrieved from Tableau's user API and applies to the backend REST username during authentication.

### Troubleshooting

The following scenarios have been encountered during the process of updating an existing connection to use Connected
Apps. We have added the steps to resolve here.

> * Trying to save my connection, I get an error message that contains:
>   `Missing Site <your site> from the list of secondary site.`

Curator detected that you are embedding Dashboards from multiple sites but not all the sites have been added to your
connection so far. Use the **Secondary Sites** section to add an item for each individual site. Curator requires
a separate Connected App for each individual site!

> * The details of the Connected App show blank.

If you are updating a Trusted Ticket connection, cached data may cause display issues. Clear the backend cache and
reload the Connection page.  If this issue persists, please reach out to Curator support.

> * Trying to save my connection, I get an error saying
>   `A syntax error was detected in <some fields.yaml> .. No such file or directory`

Clear the cache from the backend and apply the changes again. Hit save and the connection should be updated.

> * My Dashboards load indefinitely when trying to access them in the frontend.

The browser may be storing outdated settings or old Tableau session data. If you can log in and access the Dashboard
using an Incognito Window, then your users will need to hard-refresh their browsers, or clear
site site cookies.
If not, this issue generally resolves itself after 24 hours, so it's helpful to consider upgrading to connected apps
just prior to the weekend.

> * When accessing the Dashboard in the frontend, I get a 401.

Follow the steps in the *My Dashboards load indefinitely* section to resolve.

> * After updating my dev environment, my prod environment stopped working

If both Curator environments (test/dev and production) connect to the same Tableau Server, switching between Trusted
Tickets and Connected Apps can cause cookie conflicts when migrating one instance after the other. To prevent issues:

* Test each environment in a separate browser or incognito window.
* Ensure users testing Connected Apps clear their cookies before switching to the production environment again.

If further issues persist, reach out to your friendly Curator support team.

> * A Dashboard from a secondary site fails with a 401002 Unauthorized Access error that references the secondary
>   site's credentials.

If a secondary site's Content URL is missing or does not match the site exactly, or if either of its PAT fields
(PAT name or PAT secret) is left blank, Curator silently falls back to the primary site's credentials when
generating the embed token. Tableau then rejects the request with a 401002 Unauthorized Access error because the
primary site's credentials are not valid for the secondary site. To resolve:

1. Confirm the secondary site's Content URL matches the value shown in Tableau exactly (case-sensitive, no trailing
   slashes).
2. Populate both the PAT name and PAT secret fields for the secondary site.
3. Save the connection.
4. Clear the Curator backend cache and reload the Connection page.

### Allowed Domains - additional configuration option on Tableau Server/Cloud

Connected Apps can be configured to allow embedding from a specified domain only. You can find more details on
Tableau's Connected Apps in their
[Knowledge Base](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm).

## Tableau Default Authentication

Using Tableau Default Authentication for your Embed Authentication mechanism means that your users will either be
prompted with a Tableau login screen when accessing a Dashboard, or you need to configure your own SSO mechanism
(e.g. SAML, OAuth, Active Directory etc.) to enable seamless authentication.

For organizations that require an integrated authentication experience, we **strongly recommend** using
**Connected Apps** instead of relying on Tableau Default Authentication.

### Browser Security Behavior: OAuth Data Sources in Embedded Contexts

When a Tableau workbook uses an OAuth-authenticated data source (such as Databricks, Snowflake, or Google BigQuery),
some users may find the Dashboard stalls in an incomplete state, or in Safari may receive a downloaded file, rather
than loading data transparently. **This is not a defect in Curator or Tableau.** It is a consequence of how modern
browsers enforce cross-site security restrictions inside embedded iframes.

#### What happens

Curator loads Tableau inside an HTML `<iframe>`. When the workbook needs data from an OAuth-authenticated source,
Tableau contacts its internal `/auth/request_oauth` endpoint to exchange credentials. If the OAuth refresh token is
expired or has never been authorized, Tableau's session bootstrap returns a `BadOAuthCredentials` error and
responds with a redirect URL pointing to its re-authorization page, `embeddedVizAuthentication.html`.

This re-authorization page is loaded as a **nested cross-site iframe** served from Tableau's own backend cluster
hostname (e.g. `prod-useast-b.online.tableau.com`). This hostname is a third-party origin and the browser therefore applies
its cross-site restrictions to the nested iframe:

* **Firefox** with Enhanced Tracking Protection marks the nested iframe `Sec-Fetch-Storage-Access: none`,
  preventing it from reading or writing cookies or any other storage
* **Safari** with Intelligent Tracking Prevention applies the same restriction and may additionally trigger a file
  download of the OAuth token payload rather than passing it to the embed
* **Chrome and Edge** apply equivalent restrictions when third-party cookies are disabled

The result is that the OAuth re-authorization UI loads inside the nested iframe but cannot complete — it has no
storage access and cannot drive the user through the OAuth consent flow. The Dashboard remains stuck or shows a
sign-in prompt that cannot be resolved without leaving the embedded context. Tableau has confirmed this is expected
behavior in embedded contexts; the browser is the enforcing party, and there is no work-around implemented as of now.

#### Two distinct authentication layers are involved

Understanding which layer is affected helps avoid a common false fix:

* **Layer 1 — Curator to Tableau:** How Curator authenticates the end user to Tableau itself (Connected Apps,
  Tableau Default Authentication, or Trusted Tickets). Upgrading to Connected Apps addresses third-party cookie
  issues at this layer because Connected Apps use signed JWT embed tokens rather than cookie-dependent flows.
  Configuring a custom domain so that Curator and Tableau share the same registered domain also helps at this
  layer.
* **Layer 2 — Tableau to the OAuth data source:** Once Tableau loads, the workbook independently authenticates
  to its data source via the `embeddedVizAuthentication.html` flow described above. **Neither Connected Apps nor
  custom domain alignment address this layer** — the re-authorization page is always served from an internal
  Tableau hostname that cannot be made same-site with the Curator or Tableau embed domain.

#### Workarounds

Because the restriction is enforced by the browser's security model, no Curator configuration can eliminate it
entirely. The following options address the root cause at different levels:

* **Avoid OAuth for database authentication.** Where the data source supports it, use an alternative credential
  type (e.g. username and password, a service account, or Kerberos) for the Tableau data connection. This
  prevents the `/auth/request_oauth` flow from being triggered entirely, removing the condition that causes the
  browser restriction.
* **Pre-authorize OAuth credentials in Tableau Cloud directly.** Users must authorize their OAuth data source
  credentials in Tableau Cloud outside of any embedded context before loading the Dashboard in Curator. In
  Tableau Cloud, navigate to the workbook, open the data source connection, and complete the OAuth authorization
  flow. Once valid, non-expired OAuth refresh tokens are stored in Tableau Cloud for that user, the embedded
  Dashboard can load without triggering the re-authorization flow.

For background on third-party cookie restrictions and how to configure a user-facing notification, see
[Third Party Cookies](/site_administration/user_notifications/third_party_cookies).

## Trusted Tickets (Deprecated - End of Life in October 2025)

**IMPORTANT:** Trusted Tickets are deprecated and will be removed from Curator in October 2025. From that point,
Curator will no longer support issuing Trusted Tickets or using the associated JavaScript API.

For more information about Trusted Ticket authentication, please refer to our documentation article
[Creating Integrations: Tableau Connection - Trusted Authentication](/creating_integrations/tableau_connection/trusted_authentication).


# Tableau Cloud Setup
Source: https://docs.curator.interworks.com/creating_integrations/tableau_connection/tableau_cloud_setup

Configure Tableau Cloud with Curator using connected apps for secure authentication and seamless dashboard integration.

## Creating a new Connection

Follow the steps in the [Tableau Connection Setup](/creating_integrations/tableau_connection/creating_a_connection)
section to get connected to your Tableau Server.

## Connected Apps

As of the `01-04-23` Curator release, Tableau's connected apps are now supported as a method of authentication.
This means SSO is no longer required to support a seamless authentication experience for Tableau Cloud users.  All
Tableau Cloud connections in Curator utilize connected apps.  Curator will create a connected app on your Tableau Cloud
site if one doesn't already exist.  You may switch which connected app Curator uses if you need.

For more information and a troubleshooting guide, refer to our article about
[Creating Integrations: Tableau Connection - Connected Apps](/creating_integrations/tableau_connection/embed_authentication)

## Custom Domains

In the August 2025 release of Tableau Cloud, Tableau introduced the ability to use custom domains (also known as vanity
URLs). This feature primarily circumvents the need for users to modify their browser's cookie settings to allow
third-party cookies, creating a truly seamless authentication experience when accessing Tableau dashboards via Curator.
*This feature is only available in Curator versions `2025-10-02` and later.*

### Setting up a Custom Domain on Tableau Cloud

To set up a custom domain on Tableau Cloud, follow the [instructions provided by Tableau](https://help.tableau.com/current/online/en-us/custom_domain.htm).

### Adding your Custom Domain to Curator

Once your custom domain is set up and verified on Tableau Cloud, add your custom domain to Curator  to add it to Curator
to ensure seamless integration.  Begin by navigating to your Tableau Cloud connection in Curator.  Then, follow these
steps:

1. <BackendNavPath /> Click on the Tableau connection you'd like to modify.

2. In the **Tableau Connection** section, enter your custom domain URL in the **Custom Domain** field.

3. Confirm that Curator can reach the domain, and that there are no warnings:
   <img alt="Custom Domain Success" />

4. Click **Save** to apply your changes.

Now when users access embedded Tableau Cloud dashboards they will be loaded through your Custom Domain in Curator.

### Adding a Custom Domain to a Secondary Tableau Cloud Site

When your Tableau Cloud tenant hosts more than one site, Curator stores each additional site as a secondary site
under the primary Tableau Cloud connection. Tableau binds each Custom Domain to a single site, so secondary sites
must declare their own Custom Domain - they do **not** inherit the primary site's Custom Domain.

To add a Custom Domain for a secondary Tableau Cloud site, navigate to the same Tableau Cloud connection in Curator
and follow these steps:

1. Scroll to the **Secondary Sites** section of the connection form.
2. Locate the secondary site you want to configure (or add a new one).
3. Enter the secondary site's custom domain URL in its **Custom Domain** field.
4. Click **Save** to apply your changes.

If a secondary Tableau Cloud site does not have a Custom Domain configured, its embedded dashboards will load
through Tableau's tenant host (e.g. `https://10ax.online.tableau.com`) rather than the primary site's Custom
Domain. Pointing a secondary site's embed URL at the primary site's Custom Domain causes Tableau's embed signin
to fail, so leaving the secondary site's **Custom Domain** field empty is the correct configuration when no
vanity host has been set up for that site.


# Tableau Connection Troubleshooting
Source: https://docs.curator.interworks.com/creating_integrations/tableau_connection/tableau_connection_troubleshooting

Debug and resolve common Tableau connection issues including networking problems, authentication errors and API connectivity.

When setting up Curator's connection to Tableau, or dealing with unexpected networking or feature related issues, it's
beneficial to understand how to get details on the issues you're facing to help narrow down root-causes.  Whether you're
managing a Curator site need to understand how to enable Debug Mode to view the data returned from Tableau, or you're
a developer or system administrator working with Tableau Server and need to understand how to use Postman to make API
calls to ensure your Curator and Tableau Server can communicate with one another, you'll find all you need below.

## Backend User Permissions

After a Tableau connection is saved, the **Tableau** section may not appear in the backend navigation for some
users. This is a permissions issue — the connection is valid, but the backend user has not been granted access
to the Tableau plugin.

Curator automatically grants backend permissions to the user who saves the connection. Other backend users must
be granted access manually:

1. Log in as a super-administrator.
2. Navigate to **Settings** > **Administrators**.
3. Open the affected user's record and click the **Permissions** tab.
4. Under the **Tableau** section, enable the required permissions (**Manage Tableau Settings**,
   **Manage Tableau Dashboards**, etc.).
5. Save the user record.

***

## Dashboards Marked Not Found After a Connection Outage

Curator's daily Dashboard ID sync asks Tableau to resolve each Dashboard, and flags any Dashboard it cannot resolve
with a **Not Found on Tableau** callout in Backend > Tableau > Dashboards.  When a connection's credentials break
(an expired Personal Access Token, a changed password) or the Tableau Server is unreachable at the moment the sync
runs, every Dashboard on that connection can be flagged this way even though the content is still published and
perfectly healthy.

Curator clears these flags for you once the connection is working again, so no manual re-sync is needed in this
case.  Recovery happens through either of the following:

* **Saving the connection.**  Navigate to Backend > Integration > Connections, open the affected connection,
  correct the credentials and save.  Curator validates the connection before it saves, so a successful save proves
  the credentials work, and Curator immediately queues a Dashboard ID refresh for every Not Found Dashboard on
  that connection.
* **The automatic connection check.**  Curator re-checks the primary Tableau connection every five minutes, and
  re-checks any other connection the next time it successfully authenticates against it.  When a connection that
  was flagged as down starts responding again, for example because the server came back online on its own, the
  same Dashboard ID refresh is queued without anyone touching the backend.

The refresh runs through Curator's queue as `Tableau Dashboard: TableauID Update` processes, so allow a few
minutes for the queue to work through them before the Not Found callouts disappear.  Dashboards published under a
connection's Custom Domain, including the per-site Custom Domains configured for Tableau Cloud secondary sites,
are covered alongside those on the connection's primary URL.

If you would rather trigger the sync yourself, the
[Tableau API](/curator_api/api_docs/tableau_api#tableausynctableaudashboardids) exposes
`/Tableau/syncTableauDashboardIds` with a `not_found_only` parameter that limits the sync to Dashboards currently
marked as Not Found.

***

## Tableau API Debugging

Sometimes there are issues that are hard to diagnose without seeing exactly which API calls Curator is making to Tableau
and what responses Curator is getting back from Tableau.  To log all of those API calls, Curator provides a
**Debug Mode for Tableau Server**.

### Side Effects

A word of warning though, when this debug mode is enabled, the amount of logging that takes place is drastically
increased and may fill up your server if left on for long periods.  Be sure to turn it back off once you've logged
enough to diagnose the issue.

For more information about Curator's logging systems, see the [Logging Overview](/site_administration/logging/logging_overview).

### How to Enable Debug Mode

To turn on Curator's **Debug Mode for Tableau Server**:

1. Navigate to Backend > Settings > Tableau > Tableau Server Settings > Advanced tab.
2. Toggle on the switch labeled Debug Mode for Tableau Server.
3. Save the settings by using the button in the upper right.

### Using Debug Mode to Troubleshoot

Once Curator's Debug Mode for Tableau Server is enabled, you'll want to recreate the scenario that led to the
troublesome behavior and then view the debug logs by navigating to Backend > Settings > Logs > Event log.

If you don't see the applicable API calls in the logs, you may need to clear Curator's cache by using the Clear Cache
button in the upper right portion of the Backend, and then repeat the steps to recreate the troublesome scenario.

## Using Postman to Test Connection

Sometimes, it's difficult to establish a connection to Tableau and the reason why isn't clear.  One method to help rule
out bugs in Curator is to use the Postman application to directly make the API call.  This document will guide you
through using Postman to authenticate to Tableau's REST API like Curator does behind the scenes.

### Install Postman

The first step is to download and install Postman.  You can get it from:
[https://www.postman.com/downloads/](https://www.postman.com/downloads/)

### Make API Call

Follow these steps to configure a new API call against Tableau's REST API.

1. Open Postman and start a new tab.

2. Enter your Tableau Server/Cloud URL into the URL bar.  Append `/api/3.4/auth/signin`.  Update the API version if
   needed based on [this page](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm#tableau-server-versions-and-rest-api-versions1).

3. Change the request type from `GET` to `POST`.

4. Click on the **Body** tab.

5. Select **raw**.

6. In the text box, copy and paste the following XML:

   Username/Password:

   ```xml theme={null}
   <?xml version="1.0" encoding="utf-8"?><tsRequest><credentials name="" password=""><site contentUrl=""/></credentials></tsRequest>
   ```

   Personal Access Token (PAT):

   ```xml theme={null}
   <?xml version="1.0" encoding="utf-8"?><tsRequest><credentials personalAccessTokenName="" personalAccessTokenSecret=""><site contentUrl=""/></credentials></tsRequest>
   ```

7. Fill in the username/password or PAT name/secret, and site content URL details within the above XML.

8. Click the **Send** button.

You should get back XML with a credentials session token and the site and user IDs.

<img alt="Postman Screenshot" />

If needed, use the credentials session token from this response to make subsequent API calls to Tableau.  Open the
headers tab for the request and add an entry where the key is `X-Tableau-Auth` and the value is your credentials session
token.  If this token expires, you'll need to make a new request to the signin end point to get a new token.

## Admin Account Login with Multiple Connections

When Curator is configured with multiple Tableau connections (for example, a production server and a test server), only
one connection can be designated as the **primary connection**.  The primary connection controls which Tableau Server's
user accounts are synced into Curator and, therefore, which accounts can log in to the portal.

### Symptom

An admin account that exists on one Tableau Server can log in to the portal, while an admin account that exists on a
different Tableau Server cannot.  The login attempt may fail silently or return an authentication error, even though the
credentials are correct on their respective Tableau Server.

### Cause

Curator's Tableau Sync only pulls user accounts from the primary connection.  If your admin account exists on a
non-primary connection, that account is never synced into Curator and cannot be used to log in to the portal.  This
limitation also applies when the connection uses the `Tableau Server` authentication type — users must exist on the
primary site of the primary server, not merely be synced from elsewhere, in order to authenticate against the portal.

### Resolution

There are two paths forward depending on your requirements.

#### Option 1: Consolidate Users on the Primary Connection

If you want to keep all Tableau connections under a single Curator instance, you need to ensure all users who must log
in to the portal exist on the primary site of the primary Tableau Server.  There are two ways to approach this:

* **Add users directly to the primary site** — Create the accounts on the primary Tableau Server's primary site so
  they are picked up by Tableau Sync.  Note that usernames must match exactly across Tableau Servers so that Curator
  can correctly associate a portal login with the right account on each server.  Also be aware that users who exist on
  both Tableau Servers will require a license on each, which can significantly increase licensing costs if there is
  little overlap between the two user populations.
* **Create a dedicated authentication site** — Set up a separate site on the primary Tableau Server that contains no
  content and exists solely to hold user accounts for Curator's sync.  Configure that site as the primary site in
  Curator's connection settings.  Users must still exist on this site with usernames that match their accounts on the
  other Tableau Server, and the same per-server licensing considerations apply.  However, this approach keeps content
  permissions and access concerns separate from portal authentication while still allowing a single Curator instance
  to serve all users.

To verify or change which connection is set as the primary:

1. Navigate to Backend > Integration > Connections.
2. Locate the connection that contains the admin account you want to use for portal login.
3. Click to edit that connection and check whether the **Primary** toggle is enabled.
4. If it is not the primary connection, enable the **Primary** toggle.  Only one connection can be primary at a time,
   so enabling it on this connection will automatically disable it on the previous primary connection.
5. Save the connection settings.
6. Run a Tableau Sync to pull the updated user accounts from the new primary connection.
7. Verify that the admin account can now log in to the portal.

> **Note:** You do not have to reassign the **Primary** flag before disabling a connection that currently holds it.
> When you turn a primary connection's **Enabled** toggle off and save, Curator automatically releases its Primary
> flag and promotes another active connection to primary, then shows a flash message naming the connection that is
> now primary.  If no other active connection remains to take over, Curator instead shows a warning that no primary
> is set, in which case you should enable a connection and mark it primary using the steps above.

#### Option 2: Deploy Separate Curator Instances

If you have two distinct user populations that each require ongoing access to their own Tableau Server — for example,
an internal team that must always reach the production server and an external partner team that must always reach a
separate partner server — deploy separate Curator instances, one per Tableau Server.  Each instance is configured with
only one Tableau connection, so its primary connection is unambiguous and each user population has its own portal
backed by the correct server.

Note that licensing varies depending on your use case:

* **Two production Curator instances** — Each production-level Curator portal requires its own Curator license, so if
  each Tableau Server/Curator pair has a different purpose for their respective users, then this will require
  separate Curator licenses for each.
* **Separating test and production environments** — If one instance is a production portal and the other is a
  matching test environment for a separate, but equivalent test Tableau Server, this is covered under the existing
  Curator license. Contact InterWorks if you have questions about your specific licensing situation.

## Migrating Between Tableau Cloud Sites

When a Tableau Cloud tenant is migrated from one site to another (for example, moving from a legacy site to a newly
provisioned one), Curator will continue to reference the old site until its connection settings are updated.  After
migration, users will commonly report permission errors such as dashboards failing to load, thumbnails disappearing,
or content that was previously visible no longer appearing in listings.  These errors are almost always caused by
stale cached permission data and outdated connection credentials pointing at the previous site.

Work through the following checklist on the Curator backend to point the connection at the new Tableau Cloud site:

1. Navigate to Backend > Settings > Tableau > Tableau Server Settings.
2. Update the **Tableau Server URL** to match the new Tableau Cloud host (for example, `https://10ax.online.tableau.com`).
3. Update the **Site Content URL** to the content URL of the new site.  This is the value that appears in the Tableau
   Cloud browser URL immediately after `/site/` when you are signed in.
4. Regenerate the **Personal Access Token (PAT)** on the new Tableau Cloud site and update both the *Personal Access
   Token Name* and *Personal Access Token* fields in Curator.  PATs are site-specific and will not carry over from the
   old site.
5. Verify the **Connected App** configuration in the new site.  The Client ID, Secret ID, and Secret Value must all be
   regenerated on the new site and updated in Curator.  See
   [Creating Integrations: Tableau Connection - Connected Apps](/creating_integrations/tableau_connection/embed_authentication)
   for full details.
6. Update any entries under **Secondary Sites** so that each one points at its equivalent site on the new Tableau Cloud
   host, including the Site Content URL, PAT credentials, and Connected App details for each secondary site.
7. Save the connection settings using the button in the upper right of the backend.
8. Clear the backend cache using the **Clear Cache** button in the upper right of the backend.  This step is required
   \-- skipping it will cause the permission errors described below to persist.
9. Test the connection by loading a Dashboard as an end user and confirming that content, thumbnails, and permissions
   all resolve correctly.

### Why Permission Errors Persist After Migration

Curator caches the result of permission checks against Tableau for **60 minutes** to avoid making a REST API call every
time a user views a Dashboard or browses content.  When a site migration occurs, these cached permission results still
reference the old site and will continue to be served to users until either the cache entries expire or the cache is
manually cleared.  This is why permission errors can appear to "stick" after migration even when the connection
settings in Curator have already been updated -- the new settings are in place, but cached answers from the old site
are still being returned.  Clearing the backend cache immediately after saving the updated connection settings
invalidates these entries and forces Curator to re-check permissions against the new site on the next request.

If errors continue to occur after completing the checklist and clearing the cache, enable
[Debug Mode for Tableau Server](#tableau-api-debugging) to capture the exact API calls Curator is making and the
responses it is receiving from the new site.  You can also use the [Postman steps](#using-postman-to-test-connection)
above to confirm directly that the new PAT and Site Content URL authenticate successfully against the new Tableau Cloud
site independently of Curator.


# Tableau Server Repository
Source: https://docs.curator.interworks.com/creating_integrations/tableau_connection/tableau_server_repository

Connect directly to Tableau Server repository database for high-volume deployments

Sometimes (but very rarely) you may need to connect directly to Tableau Server's repository.  Generally this is
recommended when your user-count is very high (5000+ users), your Tableau Server connection is dealing with severe
latency that cannot be overcome (making the REST API responses very slow), or you need to enable the password reset
feature.  In these instances you will need to make sure your Tableau Server repository is enabled on Tableau Server first.

## Configuring Tableau Server's Readonly Account

By default, access to the Tableau Server repository is disabled.  To enable it, as well as set the password, you need to
issue a TSM command like the following against your Tableau Server:

```bash theme={null}
tsm data-access repository-access enable –repository-username readonly –repository-password "YOUR PASSWORD HERE"
```

Refer to Tableau’s [documentation](https://help.tableau.com/current/server/en-us/perf_collect_server_repo.htm) if you
would like a little more information about this.  Also, if your IT security has locked ports down on your Tableau
Server, make sure they open up port 8060 to Curator.

## Connecting Curator to the Repository

Once you have enabled access to the repository and set its password, you can configure the connection on Curator:

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Integrations** > **Connections** section from the left-hand menu.
3. Click on the Tableau Server connection you want to edit.
4. Expand the "Tableau Server Repository Connection" near the bottom of the page.
5. Enable the toggle for *Connect to Tableau Server's Repository Database* in the "Primary Tableau Connection" section.
6. Enabling the toggle will display a new section: "Tableau Server Repository Connection".
7. Check for any errors shown in this section.  They must be addressed before the connection can be established.
8. Expand the "Tableau Server Repository Connection" section and fill out the connection fields.  For information on how
   to find the default connection information on your Tableau Server, see:

   * **Repository Host** Tableau Server host url

   * **Repository Port** This value is *8060* by default.

   * **Repository User** *readonly* (recommended user)

   * **Repository Password** Password you set up in Step #1 on Tableau Server
9. Once properly filled out, click the "Save" button.

***

## Troubleshooting

### TABLEAU REPOSITORY CONNECTION FAILURE

If Curator logs the message `ERROR: TABLEAU REPOSITORY CONNECTION FAILURE`, Curator attempted to open a direct
PostgreSQL connection to Tableau Server's repository database and was refused or timed out.  Work through the
following checks:

1. **Confirm repository access is enabled on Tableau Server.**  Re-run the TSM command from
   [Configuring Tableau Server's Readonly Account](#configuring-tableau-servers-readonly-account) if you are unsure
   whether repository access was ever activated.  It is disabled by default on Tableau Server and must be explicitly
   enabled before Curator can connect.

2. **Verify port 8060 is open.**  Curator connects to Tableau Server's repository database on TCP port 8060 by
   default.  Confirm that the firewall on your Tableau Server allows inbound TCP connections from the Curator server
   on port 8060.  If the port is blocked, ask your IT or network team to open it from the Curator server's IP address
   to the Tableau Server.

3. **Check the credentials in Curator.**  In Backend > Integration > Connections, open the affected connection and
   expand the **Tableau Server Repository Connection** section.  Confirm that the **Repository Host**, **Repository
   Port** (default `8060`), **Repository User** (typically `readonly`), and **Repository Password** all match what you
   configured in the TSM command.

4. **Read the underlying PostgreSQL error in the Event log.**  Curator logs the full error every time the repository
   connection fails, so no debug toggle is required.  Navigate to Backend > Settings > Logs > Event log and open the
   `ERROR: TABLEAU REPOSITORY CONNECTION FAILURE` entry.  The complete error — including the underlying PostgreSQL
   error returned by Tableau Server's repository database — is recorded there and will tell you whether the failure
   was a refused connection, a timeout, an authentication error, or something else.

> **Note:** Curator's general **Cron Debug Mode** (Backend > Portal Settings) logs cron job scheduling activity and is
> unrelated to repository connection failures.  You do not need to enable it — or any other debug mode — for this
> flow, because the connection error is always written to the Event log.


# Trusted Authentication (Unavailable)
Source: https://docs.curator.interworks.com/creating_integrations/tableau_connection/trusted_authentication

Legacy trusted authentication method for Tableau Server (deprecated)

<Danger>
  This authentication method is deprecated and no longer supported in Curator. Please migrate to Connected Apps or another
  SSO method as soon as possible.
</Danger>

Curator no longer supports Embed Authentication using Trusted Tickets.
**Versions released in October 2025 or later, Trusted Tickets will no longer be supported**.
To ensure uninterrupted Dashboard access, you must migrate to Connected Apps or another SSO method before upgrading to
those versions.

For guidance on transitioning, refer to our [guide on how to setup Connected Apps](/creating_integrations/tableau_connection/embed_authentication).

***

By default, if the Tableau Server workbook views which are embedded in dashboards require a login, the user will be
prompted for their username and password the first time they view any Dashboard.  With trusted ticket authentication
enabled on the system and on the associated Tableau Server, the system will authenticate on behalf of the user.

One drawback to using trusted tickets is that there is a little more overhead to authenticate on behalf of the user
before showing the Dashboard.  Since trusted tickets are one-time use, this authentication takes place before each and
every Dashboard is shown.

This functionality requires that the Tableau Server REST API is enabled which you can
[establish by creating a Tableau Connection](/creating_integrations/tableau_connection/creating_a_connection).

## Enabling Trusted Tickets (Unavailable)

<Warning>
  This feature is no longer supported in Curator as of October 1, 2025, and is for reference purposes only.
</Warning>

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Integrations** > **Connections** from the left-hand menu.
3. Click on your Tableau Server from the list view.
4. Expand the *Embed Authentication* Section.
5. Select **Trusted Ticket Authentication** in the drop-down selection box for *Which authentication type will embedded
   dashboards use*.
6. If you have not set up Curator as a trusted host on your Tableau Server, follow the instructions in the dialog box
   that appears below the enabled button.
7. Save the Connection.

**Note:** The dialog box lists out a couple of different trusted hosts to add to Tableau Server. Those include the
server address (Outbound IP), local address, server name and hostname.  These are Curator's best guess at which hosts
requests originating from Curator will be seen by Tableau Server.  Depending on your network configuration, these may
not be correct by the time the request reaches Tableau Server.  Adjust as needed.

**Note:** If you use a reverse proxy or load balancer on the network between Curator and Tableau Server, ***DO NOT***
configure the reverse proxy or load balancer as a *trusted host*.  Reverse proxies or load balancers can be configured
instead as a *trusted gateway* if needed.  However, it's likely that you'll need to configure the reverse proxy or load
balancer to pass through specific headers so Tableau Server can tell that the request comes from Curator.  Instructions
for these headers can be found in [Tableau's documentation](https://help.tableau.com/current/server/en-us/proxy.htm#configure-the-reverse-proxy-server)


# Integrating ThoughtSpot with Curator
Source: https://docs.curator.interworks.com/creating_integrations/thoughtspot_connection/integrating_thoughtspot_with_curator

Connect and integrate your ThoughtSpot instance with Curator for unified analytics access

You can follow this guide to connect to your ThoughtSpot instance to Curator.

## Preparing ThoughtSpot

1. Verify your ThoughtSpot admin has enabled either [SAML SSO](https://developers.thoughtspot.com/docs/saml-sso) or
   [trusted authentication](https://developers.thoughtspot.com/docs/trusted-auth).  If you are using trusted
   authentication, have the *secret\_key* ready to add to the Curator configuration.
2. Verify your ThoughtSpot admin has configured your Curator domain to be
   [whitelisted for CORS and CSP](https://developers.thoughtspot.com/docs/security-settings).
3. Have the credentials for a user with administrator access on the intended Org ready to add to the Curator configuration.

Note: The user with administrator access to the intended Org must also exist on the "Primary" Org. This is due to a
limitation in the ThoughtSpot REST API where we can only query user details when we know the Org ID the user exists
on. The "Primary" Org ID is always the same so we can confidently pull the user details when they exist there, but
other Orgs have randomly generated ID's that aren't available in the ThoughtSpot UI anywhere. While the user must
exist on the "Primary" Org for Curator to be able to pull its details, it doesn't need to be an admin there, only
on the intended Org.

## Connect to Curator

1. Go to the backend of your Curator instance.  Navigate to Integrations > Connections using the left-hand menu.
2. Click the new New Connection button on the top of the page.
3. Enter a name for the connection (something like "ThoughtSpot" is sufficient) and edit the slug if you'd like (but
   you don't need to).
4. Choose "ThoughtSpot in the Platform dropdown.  If the option is disabled then you already have a ThoughtSpot
   Connection  created.
5. Fill out the form that appears below the Platform dropdown:
   * **ThoughtSpot URL**: The full URL to for your ThoughtSpot instance.
     e.g. [https://example.thoughtspot.cloud](https://example.thoughtspot.cloud)
   * **REST Connection Username**: The username for a ThoughtSpot administrator.
   * **REST Connection Password**: The password for a ThoughtSpot administrator.
   * **Use Trusted Authentication?**: If you ***don't*** have SAML enabled for your ThoughtSpot environment you need
     to use trusted authentication.  Flip this switch on to enable it.
   * **Trusted Authentication Secret Key**: Enter the secret key your ThoughtSpot admin received when enabling
     trusted authentication.
6. Hit "Save" at the top of the page.

## Troubleshooting

### ThoughtSpot Does Not Appear in the Backend Navigation

After saving a ThoughtSpot connection, the **ThoughtSpot** section may not appear in the backend navigation for
some users. This is a permissions issue — the connection is valid, but the backend user has not been granted
access to the ThoughtSpot plugin.

Curator automatically grants backend permissions to the user who saves the connection. Other backend users must
be granted access manually:

1. Log in as a super-administrator.
2. Navigate to **Settings** > **Administrators**.
3. Open the affected user's record and click the **Permissions** tab.
4. Under the **ThoughtSpot** section, enable **ThoughtSpot administrator**.
5. Save the user record.


# Replace Dashboard URLs
Source: https://docs.curator.interworks.com/creating_integrations/updating_connections/replace_dashboard_urls

Bulk find and replace dashboard URLs when updating Tableau Server connections

You can find/replace URLs in bulk.  If you are modifying your overall Tableau Server Connection settings you may need to
[update the URL in Tableau integration or update the credentials associated](/creating_integrations/tableau_connection/creating_a_connection).

## To replace Dashboard URLs

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Dashboards** in the dropdown.
4. Select the dashboards you'd like to replace the URL for using the checkboxes on the left
5. Click the "Replace Dashboard URLs" button with the hyperlink logo.
6. Enter the text you'd like the Portal to FIND in the field "Look for this text in the Dashboard URLs"
7. Enter the text you'd like the Portal to REPLACE in the field "Replace with"
8. Click the "Replace" button


# Temporarily Disabling Connections
Source: https://docs.curator.interworks.com/creating_integrations/updating_connections/temporarily_disabling_connections

Temporarily disable integration connections without removing configuration settings

If you need to temporarily turn off a connection, you can toggle off the **Enabled** switch when editing the connection
(Backend > Integrations > Connections > click a connection).

To re-enable the connection, just toggle the **Enabled** switch back on and save.

***Important* Note:** If your Curator licensing limits how many connections you can have in a single portal,
disabled/inactive connections are still counted toward those limits.  If you need to remove a connection from that count,
you'll need to fully delete the connection instead of disabling it.


# Activity
Source: https://docs.curator.interworks.com/curator_api/api_docs/activity

Activity API endpoints that return the same figures as the Activity page, as JSON or CSV

Every endpoint below returns one panel from the [Activity page](/site_administration/activity/activity_overview)
and accepts the same filters. The Activity page's **API** button copies a ready-made URL for the panel you are
looking at, with the current filters applied; add your API key as the `apikey` parameter before you use it.

Example:

```text theme={null}
https://your-curator-site/api/v1/activity/topContent?start=2026-08-01&end=2026-08-31&apikey=YOUR_KEY
```

## Common parameters

All parameters are optional.

* `start`: first day of the range as `YYYY-MM-DD`. Defaults to 29 days before today.
* `end`: last day of the range as `YYYY-MM-DD`. Defaults to today. An end before the start is moved to the
  start day. A range longer than 731 days is trimmed to the 731 days ending on `end`.
* `range`: one of `7d`, `30d`, `90d`, or `12m`. A shortcut for a range that ends today; it overrides `start`
  and `end`.
* `content_type`: a content model class name, for example `InterWorks\TableauViz\Models\Dashboard` or
  `InterWorks\Content\Models\Page`. Narrows the figures to that platform.
* `content`: a single item as `ClassName|id`, for example `InterWorks\Content\Models\Page|7`. Takes
  precedence over `content_type`.
* `user_id`: a frontend user id. Narrows the figures to that person.
* `format`: `csv` to receive the table as a CSV download. Omit it to receive JSON.

## Response

A JSON response carries the panel key, its title, the filters that reproduce the request, the column names,
and one object per row keyed by column name:

```json theme={null}
{
    "result": "Success",
    "panel": "topContent",
    "title": "Most viewed content",
    "filters": { "start": "2026-08-01", "end": "2026-08-31" },
    "columns": ["Content", "Type", "Views"],
    "rows": [
        { "Content": "Sales Overview", "Type": "Tableau Dashboard", "Views": 412 }
    ]
}
```

A CSV response has the column names on the first line and one line per row.

## /activity/summary

Views, viewers, logins, and access denied counts for the range and the previous period of the same length,
with the percent change. Logins and access denied ignore `content_type` and `content`.

## /activity/trend

Views per period for the range and for the previous period, aligned day for day. Accepts **aggregation**:
`daily` (default), `weekly`, or `monthly`.

## /activity/heatmap

Raw view totals for every weekday and hour slot, one row per weekday (Sunday first) and one column per hour.

## /activity/topContent

The 25 most viewed content items with their type and view count.

## /activity/contentTypes

View counts grouped by content type.

## /activity/unviewed

Content items that received no views in the range, with the last time each was ever viewed. Honors
`content_type` only.

## /activity/topUsers

The 10 most active signed-in viewers. Ignores `user_id`.

## /activity/viewsPerViewer

Signed-in viewers grouped by how many views they made, with each group's share of all signed-in views.
Ignores `user_id`.

## /activity/audience

New, returning, dormant, and never viewed account counts, the eligible account count, the active share, and
the number of accounts created in the range. Ignores `user_id`.

## /activity/denialsTrend

Access denied events per day. Ignores `content_type` and `content`.

## /activity/topDenials

The 10 most frequent requested path and user pairs that were sent to the Access Denied page. Ignores
`content_type` and `content`.


# Authentication
Source: https://docs.curator.interworks.com/curator_api/api_docs/authentication

API authentication methods and user verification processes for external applications integrating with Curator.

## Introduction

Occasionally, various external applications need to rely on Curator to authenticate users for them.
Curator provides a simple interface to determine which user is currently authenticated to Curator,
and provide information to your external application about that user.

This is particularly helpful for applications that need to keep user authentication in sync with Curator,
such as custom applications embedded within Curator.

Retrieving information about the currently authenticated user requires two API calls to Curator:

1. First, your application must forward the user to Curator's /fetchUser endpoint,
   with a `redirect_url` parameter. Curator returns the user to the redirect\_url with a `payload`
   GET parameter containing a JSON wad containing an identifier token.
2. Next, use the `token` value from this JSON wad to call Curator's `/user/getUser` endpoint to retrieve the user's information.

## Important Setup

In order for the redirect to work, you must whitelist your domain in the Curator Portal Settings.
Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
Under the **General** tab, expand the **Security** section.

### Whitelisted Redirect Hosts

The **Whitelisted Redirect Hosts** setting lists the external hosts Curator is allowed to send users to.
Curator compares the target host against that list before issuing a redirect, and refuses any host the
list does not cover.

Each row of the repeater holds one **Host** value, entered as the host portion of the URL, for example
`https://www.example.com`. Add a row for every domain you send users back to.

<Warning>
  Delete any repeater row you are not using. A saved row with a blank **Host** permits every host, which
  turns the whitelist off.
</Warning>

Curator permits some hosts without any configuration:

* The host of the current request.
* The **Forced Curator Domain** setting, when one is set.
* The root URL Curator has stored for itself.
* `localhost` and `127.0.0.1`.
* The `APP_URL` value from the server environment. On-Prem administrators set this value, and InterWorks
  manages it on SaaS.
* Tableau Server URLs and their alternate URLs, from each active Tableau connection.
* `https://login.microsoftonline.com`, when Power BI is configured.
* The SAML sign-on, alternate sign-on, logout, and ACS URLs, when SAML authentication is in use.
* The OAuth domain, when OAuth authentication is in use. Curator also permits the identity provider's
  end-session endpoint while signing a user out.

Matching follows these rules:

* Both `http://` and `https://` are allowed for every row, so one row covers both protocols.
* The `www` form and the bare domain are paired in both directions. Adding `example.com` also permits
  `www.example.com`, and adding `www.example.com` also permits `example.com`.
* Subdomains are not included. `example.com` does not permit `reports.example.com`, which needs a row of
  its own.
* Only the host is compared. A port in a row is ignored, so `example.com` is permitted on any port.

A blocked redirect raises an error instead of sending the user on, and Curator records a
`Blocked redirect to <URL>` warning. Read it in the backend
[Event Log](/site_administration/logging/database_logs#event-log), or on disk in the System Log at
`storage/logs/system-YYYY-MM-DD.log` *(On-Prem only)*. See
[Server Logs](/site_administration/logging/file_based_logs) for the path on each operating system.

## /fetchUser

`HTTP REDIRECT [your_domain]/fetchUser?redirect_url=[group_name_here]`

## /user/getUser

Returns the currently logged in user's information.
`POST [your_domain]/api/v1/User/getUser?apikey=[your_api_key_here]&token=[token_here]`

**Returns:**
array

## Example Authentication Script

```PHP theme={null}
<?php
/**
 * This is a basic example of how to authenticate a user with Curator.
 *
 * From a flow perspective, this is what happens:
 *     1. The user is redirected to the Curator authentication system. (/fetchUser)
 *     2. The authenticated user is redirected back to this page with a JSON wad in the "payload" GET variable.
 *     3. The JSON wad contains a "token".
 *     4. The token is used against the Curator REST API to get the user's details.
 *
 * NOTE: VERY IMPORTANT:
 *     In order for the redirect to work, you must whitelist your domain in the Curator Portal Settings.
 *     Go to Settings->Curator->Portal Settings to add your domain. (Look under "security")
 *
 **/

/**
 * API Key: You can get this from the Curator backend.
 * Go to Settings->Curator->API Keys to retrieve and/or create a key.
 */
$api_key = 'YOUR_API_KEY';

/**
 * Curator Domain. This is the domain of your Curator instance.
 * For example: https://curator.example.com
 */
$curator_domain = 'YOUR_CURATOR_DOMAIN';

/**
 * This part is just a very basic session example.
 * You will likely want to customize it.
 */
session_start();

/**
 * If the user is returning from the Curator system, process their token.
 **/
if (!empty($_GET['payload'])) {
    processSessionPayload($_GET['payload'], $api_key, $curator_domain);

/**
 * Otherwise, if we need to start a NEW session, redirect to Curator.
 **/
} elseif (!isset($_SESSION['username'])) {
    // Where to return the user after the redirect.
    $returnURL = 'https://' . $_SERVER['HTTP_HOST'];

    // Redirect the unauthenticated user to the authentication system.
    header('Location: ' . $curator_domain . '/fetchUser?redirect_url=' . $returnURL);
    exit;
}

/**
 * If the user is authenticated, show them their information.
 **/
echo 'Hello, ' . $_SESSION['display_name'] . '!</br><pre>';
print_r($_SESSION);
echo '</pre>';

/**
 * Exchange the redirect session payload for user information.
 *
 * @param string $payload The JSON wad from the redirect.
 * @param string $api_key The API key for the Curator instance.
 * @param string $curator_domain The domain of the Curator instance.
 *
 * @return void
 */
function processSessionPayload($payload, $api_key, $curator_domain)
{
    $payload = json_decode($payload);
    if (isset($payload->token)) {
        // This is a 1-time use token returned from the /fetchUser endpoint.
        $token = $payload->token;

        // This is the REST API endpoint to exchange the token for user information.
        $url = $curator_domain . '/api/v1/user/getUser?apikey=' . $api_key . '&token=' . $token;

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $response = curl_exec($ch);
        curl_close($ch);

        $response = json_decode($response);
        $user = $response->user;

        /**
         * Uncomment the code below to see the user information available.
         *
         * echo "<pre>";
         * print_r($user);
         * echo "</pre>";
        */

        // Store the user information in the session.
        $_SESSION['username']     = $user->name;
        $_SESSION['email']        = $user->email;
        $_SESSION['display_name'] = $user->full_name;

        // The "SAML Attributes" are stored in the "custom_attributes" field.
        if (!empty($user->custom_attributes)) {
            $_SESSION['custom_attributes'] = $user->custom_attributes;
        }
    }
}
```

## API Rate Limiting

Curator rate limits every API request that includes an `apikey` parameter. Requests that do not send an
`apikey` parameter are not rate limited.

When a request is refused, Curator responds with HTTP `429 Too Many Requests` and this body:

```json theme={null}
{
    "result": "Failure",
    "msg": "API rate limit exceeded. Please try again later."
}
```

The same message is returned no matter which limit was reached, so the response never reveals whether the
API key that was supplied is a valid one.

### Two limits apply

Curator tracks two separate counters, and a request must pass both:

| Counter         | What it counts                                                         |
| --------------- | ---------------------------------------------------------------------- |
| **Global**      | Every API request made to the site, added together across all API keys |
| **Per-API key** | Only the requests made with one specific API key                       |

The global counter is checked first, on every request. It is incremented even when the API key turns out to
be invalid, so repeated calls with a bad key still consume the site-wide allowance.

<Note>
  The global counter is shared by the whole site rather than tracked separately per caller. A single busy
  integration can therefore use up the allowance that every other API consumer depends on.
</Note>

### Global settings

To customize the global limit, navigate to **Backend** > **Settings** > **Security** >
**Authentication Settings** > **Customization** section.

| Setting                                  | Description                                         | Default |
| ---------------------------------------- | --------------------------------------------------- | ------- |
| **API Rate Limit - Max Calls**           | How many API calls are allowed within the timeframe | 500     |
| **API Rate Limit - Timeframe (minutes)** | The length of the window used to track those calls  | 1       |

With the default values, Curator allows 500 API calls per minute across the whole site.

### Per-API key override

An individual API key can use its own limits instead of the global ones. Navigate to **Settings** >
**Curator** > **API Keys**, edit a key, and find the **Rate Limiting** section:

* **Rate Limit - Max Calls (override global)**
* **Rate Limit - Timeframe (minutes, override global)**

Leave either field blank and that key falls back to the matching global value. Because both counters are
enforced, the lower of the two limits is the one a caller reaches first. Raising a key's limit above the
global limit does not allow it to exceed the global allowance.

### When a counter resets

A counter resets once a full timeframe passes with no calls counted against it. Continuous traffic does not
roll the count back, so a caller that keeps making requests keeps accumulating until it reaches the limit.

Once a limit is reached, further calls are refused until the timeframe has elapsed since the limit was hit.


# Content
Source: https://docs.curator.interworks.com/curator_api/api_docs/content

Content API endpoints for creating and managing files and content within Curator

## /content/createFile

Creates a file model

Example Usage:

[Python Script](https://curator.interworks.com/file/api-example-createfile)

**Parameters:**
**file**

The file to attach, sent as a multipart upload. Required unless `file_location` is provided.

**file\_location**

A URL the Curator server should download the file from. Required unless `file` is provided.

**slug**

The unique identifier to use for the file in the URL. Required.

**title**

The title/name of the file. Optional, defaults to the slug.

**description**

A short description of the file. Optional.

**restrict\_access**

Whether the file should be restricted to certain groups. Optional, `true` or `false`.

**groups**

Comma-separated list of group names the file should be restricted to. Optional.

**hidden**

Hides the file from all views: search results, tiles, and explorer. Optional, `1` or `0`.

**hidden\_from\_search**

Hides the file from search results only. Optional, `1` or `0`.

**favoritable**

Whether users may favorite the file. Optional, `1` or `0`.

**allow\_browser\_cache**

Whether browsers may cache the file. Optional, `1` or `0`.

**download\_only**

Forces browsers to download the file instead of opening it. Optional, `1` or `0`.

**keywords**

Comma-separated list of existing keyword IDs (see `/content/listKeywords`) to classify the file with.
Unknown IDs are ignored. Optional.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Successfully created file",
        "id": 42
    }
```

When `groups` was provided and at least one name did not match an existing frontend group, the response also
includes a `groups_not_found` array listing those names. The file is created with the remaining groups only.

## /content/createNavMenu

Creates a nav menu model

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

When `groups` was provided and at least one name did not match an existing frontend group, the response also
includes a `groups_not_found` array listing those names. The menu link is created with the remaining groups only.

## /content/createPage

Creates a page containing a single full-page embed built from a URL, embed code, or a raw HTML document.
The page renders inside the normal Curator navigation with its title hidden, so the embedded content takes
up the whole page area. Exactly one of `url`, `embed_code`, or `html` must be provided.

**Parameters:**
**title**

The title of the new page. Required.

**url**

A URL to embed in the page.

**embed\_code**

Embed code (HTML) to render in the page as-is. The code is not compiled as a server-side template, but
unlike the `html` parameter it is also not sandboxed: scripts inside it run in the page in the viewing
user's browser session, so only publish embed code from trusted sources.

**html**

A full HTML document to display. The document is stored as a hidden, download-only Curator file and
rendered inside a sandboxed frame isolated from the viewer's Curator session. Because the file is
download-only, visiting its direct `/file/{slug}` link downloads the document rather than rendering it in
the browser.

**slug**

The unique identifier to use for the page in the URL. Optional, generated from the title when omitted. An
error is returned if a provided slug is already in use.

**add\_to\_nav**

Adds the new page to the main navigation. Optional, `1` or `0`.

**nav\_parent\_id**

The ID of the menu item to nest the new navigation entry under. Takes effect only when `add_to_nav` is
`1`. Optional, defaults to the main menu so the entry is added at the top level. Use
`/content/listNavMenus` to find the available menu IDs. An error is returned whenever the ID is supplied
and does not match an existing menu item, whether or not `add_to_nav` is set.

**hidden**

Hides the page from all views: search results, tiles, and explorer. Optional, `1` or `0`.

**hidden\_from\_search**

Hides the page from search results only. The page stays visible in tiles and the explorer. Optional, `1` or
`0`.

**keywords**

Comma-separated list of existing keyword IDs (see `/content/listKeywords`) to classify the page with.
Unknown IDs are ignored. Optional.

**restrict\_access**

Whether the page should be restricted to certain frontend groups, the same as turning on **Restrict Access**
in the page's settings. Optional, `1` or `0`. Any other value returns an error and no page is created. See
[Restricting a Page to Groups](/site_content_design/pages/pages_overview#restricting-a-page-to-groups).

**groups**

Comma-separated list of frontend group names the page should be restricted to. Only applied when
`restrict_access` is `1` (or **Restrict Access is Always Enabled** is on); ignored otherwise. Names that do not
match an existing group are skipped and returned in `groups_not_found`. A restricted page with no matching
groups is visible to nobody, so check that key. Optional.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Successfully created page",
        "id": 42,
        "slug": "sales-report",
        "url": "https://curator.example.com/page/sales-report",
        "edit_url": "https://curator.example.com/backend/interworks/content/page/update/42",
        "file_id": 17,
        "groups_not_found": ["Regional Managers"]
    }
```

The `file_id` key is only present when the page was created from the `html` parameter. It can be passed to
`/content/updateFile` later to replace the page's HTML in place.

The `groups_not_found` key is only present when `groups` was provided and at least one name did not match an
existing frontend group. In the example above, no group named `Regional Managers` exists, so the page was
created without it.

## /content/deleteFile

deletes a file model by ID

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /content/listFiles

Lists file content types.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    [
        {
            "id": 1,
            "title": "HexTileAlt",
            "description": "",
            "slug": "hex-tile-alt",
            "restrict_group_access": 0,
            "created_at": "2017-09-12 16:11:10",
            "updated_at": "2017-09-12 16:11:10"
        },
        {
            "id": 2,
            "title": "Logo 196",
            "description": "",
            "slug": "logo-196",
            "restrict_group_access": 0,
            "created_at": "2017-12-15 17:15:07",
            "updated_at": "2017-12-15 17:15:07"
        }
    ]
```

## /content/listDashboards

Lists Tableau dashboard content types with associated keywords.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    [
        {
            "id": 1,
            "title": "Sales Dashboard",
            "description": "Dashboard showing sales metrics",
            "slug": "sales-dashboard",
            "url": "https://tableau.example.com/#/views/Sales/Dashboard",
            "server": "https://tableau.example.com",
            "site": "Default",
            "restrict_group_access": 0,
            "created_at": "2023-01-15 10:30:00",
            "updated_at": "2024-01-10 14:22:00",
            "keywords": [
                {
                    "id": 2,
                    "title": "Scorecard",
                    "created_at": "2023-08-15T10:24:49.000000Z",
                    "created_by": "admin (backend)",
                    "updated_at": "2023-08-21T07:53:26.000000Z",
                    "updated_by": "admin (backend)",
                    "favoritable": 1,
                    "pivot": {
                        "dashboard_id": 1,
                        "keyword_id": 2
                    }
                },
                {
                    "id": 4,
                    "title": "Pink Cards",
                    "created_at": "2023-08-23T07:28:05.000000Z",
                    "created_by": "admin (backend)",
                    "updated_at": "2023-08-23T07:28:05.000000Z",
                    "updated_by": "admin (backend)",
                    "favoritable": 1,
                    "pivot": {
                        "dashboard_id": 1,
                        "keyword_id": 4
                    }
                }
            ]
        },
        {
            "id": 2,
            "title": "Marketing Dashboard",
            "description": "",
            "slug": "marketing-dashboard",
            "url": "https://tableau.example.com/#/views/Marketing/Overview",
            "server": "https://tableau.example.com",
            "site": "Default",
            "restrict_group_access": 0,
            "created_at": "2023-02-20 09:15:00",
            "updated_at": "2023-12-05 11:45:00"
        }
    ]
```

## /content/listNavMenus

Lists nav menu links with associated keywords.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    [
        {
            "id": 1,
            "parent_id": null,
            "title": "Main Menu",
            "description": "The main menu items",
            "url": null,
            "enabled": 1,
            "parameters": null,
            "query_string": null,
            "is_external": 0,
            "link_target": "_self",
            "created_at": {
                "date": "2017-10-08 14:51:28.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "updated_at": {
                "date": "2018-03-08 19:41:42.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "link_type": "custom_url",
            "notice_id": null,
            "restrict_group_access": 0,
            "keywords": [
                {
                    "id": 2,
                    "title": "Scorecard",
                    "created_at": "2023-08-15T10:24:49.000000Z",
                    "created_by": "admin (backend)",
                    "updated_at": "2023-08-21T07:53:26.000000Z",
                    "updated_by": "admin (backend)",
                    "favoritable": 1,
                    "pivot": {
                        "menu_id": 1,
                        "keyword_id": 2
                    }
                },
                {
                    "id": 4,
                    "title": "Pink Cards",
                    "created_at": "2023-08-23T07:28:05.000000Z",
                    "created_by": "admin (backend)",
                    "updated_at": "2023-08-23T07:28:05.000000Z",
                    "updated_by": "admin (backend)",
                    "favoritable": 1,
                    "pivot": {
                        "menu_id": 1,
                        "keyword_id": 4
                    }
                }
            ]
        },
        {
            "id": 2,
            "parent_id": 1,
            "title": "Home",
            "description": "Website Home Page",
            "url": "home",
            "enabled": 1,
            "parameters": null,
            "query_string": null,
            "is_external": 0,
            "link_target": "_self",
            "created_at": {
                "date": "2017-10-08 14:51:28.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "updated_at": {
                "date": "2018-01-16 15:24:38.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "link_type": "custom_url",
            "notice_id": null,
            "restrict_group_access": 0,
            "keywords": []
        }
    ]
```

Every nav menu link includes a `keywords` array. Links with no keywords assigned return an empty array
rather than omitting the field.

## /content/updateFile

Updates a file model's details and can replace its attachment in place, keeping the same file ID, slug, and
links.

**Parameters:**
**id**

The ID of the file to update. Required.

**file**

A replacement file, sent as a multipart upload. Optional.

**file\_location**

A URL the Curator server should download a replacement file from. Optional.

**slug**, **title**, **description**

Updated values for the file's details. Optional.

**restrict\_access**, **groups**

Group restriction settings, matching `/content/createFile`. `groups` replaces the file's current groups.
Optional.

**hidden**, **hidden\_from\_search**, **favoritable**, **allow\_browser\_cache**, **download\_only**

File flags, matching `/content/createFile`. Optional, `1` or `0`.

**keywords**

Comma-separated list of existing keyword IDs (see `/content/listKeywords`). Replaces the file's current
keywords; pass an empty value to clear them. Optional.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Successfully updated file",
        "id": 42
    }
```

When `groups` was provided and at least one name did not match an existing frontend group, the response also
includes a `groups_not_found` array listing those names. The file's groups are replaced with the matching names
only.


# Curator API
Source: https://docs.curator.interworks.com/curator_api/api_docs/curator_api

Complete API reference for Curator including portal information, user management and system endpoints.

## /portal/info

Returns all information about Curator.

**Parameters:**

**boolean**
ini Shows PHP ini settings
**boolean**
extensions Shows loaded PHP extensions

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "version": "2020.09.17-01",
        "kernel_build": 446,
        "key": "[YOUR KEY HERE]",
        "php_version": "7.2.11",
        "os": "Linux ip-XX-XX-XX-XXXus-west.compute.internal 4.14.77-86.82.amzn2.x86_64 #1 SMP Tue Dec 1 20:40:13 UTC 2018 x86_64",
        "user": "apache",
        "server_addr": "ip-XXX-XX-XX-XXX.us-west-2.compute.internal",
        "server_ips": [
            "XX.XXX.XXX.X,
            "XXX.XX.XX.XXX",
            "curatordemo.interworks.com",
            "ip-XX-XX-XX-XXX.us-west.compute.internal"
        ],
        "database": "mysql",
        "display_errors": "Off",
        "max_execution_time": "60",
        "cache": "memcached",
        "gd": true,
        "fileinfo": true,
        "zip": true,
        "zlib": true,
        "curl": true,
        "openssl": true,
        "memcached": true,
        "php_ini_path": "\/etc\/php.ini",
        "tableau_version": "2018.1",
        "php_location": "\/usr\/bin\/php",
        "is_windows": false,
        "post_max_size": "250M",
        "upload_max_filesize": "250M",
        "memory_limit": "1024M",
        "webroot": "\/var\/www\/html",
        "cron_timestamp": "2019-01-08T21:01:02+00:00",
        "writeable": true,
        "upload_max_filesize_bytes": 262144000,
        "post_max_size_bytes": 262144000,
        "memory_limit_bytes": 1073741824,
        "install_files": false,
        "cron_check": true
    }
```

## /portal/version

Returns version information about the Curator portal.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "version": "2017.08.10-01"
    }
```

## /portal/key

Returns key for the Curator portal.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "key": "1234-5678-9101-1112-1314"
    }
```

## /portal/setKey

Sets the Curator's portal key.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /portal/upgrade

Upgrades Curator to the latest version.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /portal/cron

Runs the Curator Schedules.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /portal/queueBackup

Queues a full backup (database plus web root), the same as the **Take New Backup** button on the backend
**Settings** > **Curator** > **Backups** page. The backup itself runs the next time Curator's scheduled tasks
run. Poll `/portal/listBackups` until the new archive appears with `complete` set to `true` and a `status` of
`Ready`. While the backup runs, the queued row on `/portal/listBackups` shows the in-progress step in its
`status`; the row is removed when the job ends. If the queued row disappears and no new archive appears, the
backup failed; check the system log under `storage/logs/` for the error. Pair this with `/portal/export` when
automating a test environment refresh.

Full backups are not available on Curator SaaS, where InterWorks manages backups. There the endpoint returns
a `Failure` result.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Queued",
        "id": 42
    }
```

## /portal/listBackups

Lists the same rows the backend **Backups** page shows: completed full backup archives in the backup
location, plus queued backup and restoration processes that are pending, running, or errored. Rows are sorted
newest first. A completed archive has `complete` set to `true` and, when it includes a database dump, a
`status` of `Ready`. An archive whose database dump failed is named `full_backup_<timestamp>_NO_DATABASE.zip`
and reports `Does not include a database export!` instead. A queued process has `complete` set to `false` and
carries the queued process status (for example `Pending`). The `link` value is a backend download URL and
needs a backend session.

Full backups are not available on Curator SaaS, where InterWorks manages backups. There the endpoint returns
a `Failure` result.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": [
            {
                "complete": false,
                "name": "Queued Curator Backup at 2026-09-09 18:02:11",
                "path": "",
                "link": "#",
                "status": "Pending",
                "size": "N/A",
                "timestamp": "2026-09-09 18:02:11",
                "date": 1788976931
            },
            {
                "complete": true,
                "name": "full_backup_20260908_020000.zip",
                "path": "/var/www/html/storage/temp/full_backup_20260908_020000.zip",
                "link": "https://curatorexample.com/backend/interworks/portal/backups/downloadBackup/full_backup_20260908_020000.zip",
                "status": "Ready",
                "size": "1.2 GB",
                "timestamp": "2026-09-08 02:00:00",
                "date": 1788832800
            }
        ]
    }
```

## /portal/migrations

Runs database migrations.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /portal/clearCache

Clears Curator cache.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /portal/flushAllCache

Flushes all Curator cache. Unlike `/portal/clearCache` and the backend **Clear Cache** button, this also
releases the lock that stops two queue workers from running at once, so it can free a lock left behind by a
queue worker that was killed. See
[Queued Processes](/site_administration/performance/queued_processes#step-3-wait-out-the-queue-lock).

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Cache flushed successfully."
    }
```

## /portal/phpinfo

Returns the PHP Information Page

**Returns:**

array

## /portal/setPortalName

Sets the Curator portal name.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /portal/octoberUpgrade

Upgrades the underlying OctoberCMS.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /portal/export

Exports Curator portal data.

**Parameters:**

**string**
models (optional) Comma separated list of models to export. Default: everything.  Options include:

* `api_keys`
* `attributes`
* `commands`
* `connections`
* `dashboards`
* `favorites`
* `files`
* `filter_categories`
* `filters`
* `fonts`
* `frontend_groups`
* `frontend_group_overrides`
* `groups`
* `items`
* `interworks_authentication_settings`
* `interworks_integration_settings`
* `interworks_portal_settings`
* `interworks_tableauviz_settings`
* `interworks_usermgmt_samlsettings`
* `keywords`
* `loading_screens`
* `navigation`
* `notices`
* `pages`
* `parameters`
* `powerbi_dashboards`
* `powerbi_reports`
* `scheduledreport`
* `scripts`
* `slideshows`
* `themes`
* `tos`
* `tutorials`
* `user_comments  `

**boolean**
thumbnails (optional) Whether to include thumbnails in the export. Default: false.

**boolean**
tiles (optional) Whether the output data should use the tile information instead of export. Default: false.

**Returns:**

array

## /portal/cacheInfo

Returns all cache information about Curator

**Parameters:**
**boolean**
ini Shows PHP ini settings
**boolean**
extensions Shows loaded PHP extensions

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": {
            "cms_cache_path": "5.7 KB",
            "cms_combiner_path": "964.04 KB",
            "twig_cache": "529.57 KB",
            "framework_cache": "1.05 MB",
            "thumbnails": "28.95 MB"
        }
    }
```

## /portal/setAnalyticsSettings

Sets the analytics tracking settings.

**Returns:**

array

## /portal/setParameter

Sets a system parameter.

**Parameters:**
**Returns:**

array

## /portal/cleanSettings

Cleans up settings data, if there are duplicates.

**Returns:**

array

## /portal/fixMenuNestedSet

Repairs corrupted nested-set values on the menu tree, then clears the framework cache so refreshed menu data is picked up immediately.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Menu nested set values repaired and framework cache cleared."
    }
```

## /portal/fixStoragePerms

Attempts to fix storage file permissions, recursively.

**Returns:**

array

## /portal/checkSettings

Check settings items.

**Returns:**

array

## /portal/downloadLog

Exports Curator's system log data.

**Returns:**

array

## /portal/cleanUploadDir

Cleans out old uploaded files.

**Returns:**

array

## /portal/features

Returns information on features in use.

**Returns:**

array

## /portal/stats

Returns stats on Curator.

**Returns:**

array

## /portal/styles

Returns head insert and custom stylesheet from Portal Settings.

**Returns:**

array

## /portal/reindexSearch

Triggers a Scout search index rebuild for one or all WinterSearchable models. Only relevant when
using an external search engine (Typesense); the database driver queries live data and does
not require a manual index rebuild.

**Parameters:**

* `model` (string, required) — Fully-qualified model class name to reindex (e.g.
  `InterWorks\TableauViz\Models\Dashboard`), or `ALL` to reindex every registered
  WinterSearchable model.
* `chunk_size` (integer, optional, default: `100`) — Number of records processed per batch.
  Must be between 1 and 1000.

**Returns:**

```json theme={null}
{
  "result": "Success",
  "msg": "Reindex complete for Dashboard: 42 records indexed, 0 errors.",
  "data": {
    "model": "Dashboard",
    "count": 42,
    "errors": []
  }
}
```


# Data Manager
Source: https://docs.curator.interworks.com/curator_api/api_docs/data_manager

Data Manager API endpoints for reading Curator tables and managing data groups, attributes, and items.

The Data Manager API covers two separate jobs. `getDataTables` and `getData` read supported Curator
tables directly, which is how you export content, activity, and configuration data from a portal. The
remaining endpoints create and maintain Data Manager groups, attributes, and items.

Every endpoint follows the standard Curator API pattern and requires an API key:

```
[your_domain]/api/v1/datamanager/[endpoint]?apikey=[your_api_key_here]
```

<Note>
  API keys can be restricted per endpoint. A key that is otherwise valid returns
  `This key is restricted from using this end point` when it has not been granted access to the
  endpoint you are calling. See [Authentication](/curator_api/api_docs/authentication) for how keys are
  issued and rate limited.
</Note>

## /datamanager/getDataTables

Lists the tables that `getData` will serve on this portal. Call this first. The list is assembled at
runtime from the plugins that are installed and enabled, so it differs between portals and between
Curator versions. Reading it is more reliable than assuming a fixed set of tables.

**Parameters:**

None.

**Returns:**

array

Keys are table names to pass to `getData`. Values are the display names shown in the backend.

**Example Response:**

```JSON theme={null}
    {
        "interworks_content_files": "Curator Files",
        "interworks_content_keywords": "Curator Keywords",
        "interworks_content_pages": "Curator Pages",
        "interworks_tableauviz_dashboards": "Curator Tableau Dashboards",
        "interworks_usermgmt_content_view": "Curator Content Views",
        "interworks_usermgmt_content_view_summary": "Curator Content Views Summary",
        "page_keyword": "Curator Page / Keyword Relationships"
    }
```

## /datamanager/getData

Returns rows from one of the tables listed by `getDataTables`. Any other table is rejected, so this
endpoint cannot be used to read arbitrary tables.

**Parameters:**

**table**

The table to read. Required. Must be one of the keys returned by `getDataTables`.

**limit**

Number of records to return. Optional, defaults to `1000`.

**offset**

Number of records to skip, for pagination. Optional.

**sort\_column**

Column to sort by. Optional. A column that does not exist on the table is ignored rather than fatal, and
the response carries a `warning` explaining that the sort was skipped.

**sort\_direction**

Sort direction, either `asc` or `desc`. Optional, defaults to `asc`.

**Returns:**

array

**Example Usage:**

```
[your_domain]/api/v1/datamanager/getData?apikey=[your_api_key_here]&table=interworks_content_pages&limit=2
```

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "data": [
            {
                "id": 1,
                "title": "Company Handbook",
                "slug": "company-handbook",
                "created_at": "2025-02-19 16:11:10",
                "updated_at": "2025-02-19 16:11:10"
            },
            {
                "id": 2,
                "title": "Quarterly Review",
                "slug": "quarterly-review",
                "created_at": "2025-02-20 09:04:55",
                "updated_at": "2025-02-20 09:04:55"
            }
        ]
    }
```

### Paging through a large table

Requests that carry an `apikey` are rate limited, and the default `limit` is 1000 rows. Page through
larger tables with `limit` and `offset` rather than requesting everything at once:

```
[your_domain]/api/v1/datamanager/getData?apikey=[your_api_key_here]&table=interworks_usermgmt_content_view&limit=1000&offset=0
[your_domain]/api/v1/datamanager/getData?apikey=[your_api_key_here]&table=interworks_usermgmt_content_view&limit=1000&offset=1000
```

Sorting on an indexed column such as `created_at` keeps paging stable while new rows are being written.

### Errors

`getData` returns `"result": "Error"` with one of these messages:

| Message                                       | Cause                                                                                                                             |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Missing table argument`                      | The `table` parameter was not supplied.                                                                                           |
| `Table not found in list of supported tables` | The table is not one of the keys from `getDataTables`.                                                                            |
| `Table not found: [table]`                    | The table is supported but does not exist on this portal, usually because the plugin that provides it has not run its migrations. |

## /datamanager/listGroups

Lists Data Manager groups.

**Returns:**

array

## /datamanager/listAttributes

Lists Data Manager attributes.

**Returns:**

array

## /datamanager/listItems

Lists Data Manager items.

**Parameters:**

**group\_id**

Filter results to those within a specific group. Optional.

**limit**

Number of records to limit the result to. Optional.

**offset**

Number of records to skip for pagination purposes. Optional.

**Returns:**

array

## /datamanager/createGroup

Creates a Data Manager group.

**Parameters:**

**name**

Name of the group.

**slug**

Unique URL identifier for this group on the frontend.

**captcha**

Which type of captcha is required to submit.

**options**

Various options for field option filtering. Optional.

**frontend\_accessible**

Whether this group is accessible from the frontend. Pass the string `true` to enable it. Any other value,
including `1`, is treated as false. Optional, defaults to false.

**dashboard\_id**

ID of the Dashboard to display on the frontend. Optional.

**batch\_import**

Whether to allow batch importing on the frontend. Pass the string `true` to enable it. Any other value,
including `1`, is treated as false. Optional, defaults to false.

**enable\_data\_ajax**

Whether to allow data to be retrieved from an Ajax call. Pass the string `true` to enable it. Any other
value, including `1`, is treated as false. Optional, defaults to false.

**email\_submissions**

Whether to send copies of submissions to an email. Pass the string `true` to enable it. Any other value,
including `1`, is treated as false. Optional, defaults to false.

**email\_address**

Which email address to send to. Optional unless using `email_submissions`.

**recaptcha\_site\_key**

reCaptcha site key. Optional unless using reCaptcha.

**recaptcha\_secret\_key**

reCaptcha secret. Optional unless using reCaptcha.

**revision\_history**

Whether to track revision history. Pass the string `true` to enable it. Any other value, including `1`, is
treated as false. Optional, defaults to false.

**Returns:**

array

## /datamanager/createAttribute

Creates a Data Manager attribute.

**Parameters:**

**name**

Name of the attribute.

**type**

Data type of the attribute, for example `text`, `number`, or `dropdown`.

**multi\_select**

Whether a dropdown is multi-select. Pass the string `true` to enable it. Any other value, including `1`,
is treated as false. Optional, defaults to false.

**required**

Whether the attribute is required. Pass the string `true` to enable it. Any other value, including `1`, is
treated as false. Optional, defaults to false.

**searchable**

Whether the attribute is searchable. Pass the string `true` to enable it. Any other value, including `1`,
is treated as false. Optional, defaults to false.

**editable**

Whether the attribute is editable on the frontend. Pass the string `true` to enable it. Any other value,
including `1`, is treated as false. Optional, defaults to false.

**options**

Options for the attribute, used for dropdowns and validation. Optional.

**description**

Description of the attribute. Optional.

**sort\_order**

Sort order when listing attributes. Optional.

**Returns:**

array

## /datamanager/addAttributeToGroup

Adds a Data Manager attribute to a Data Manager group.

**Parameters:**

**attribute\_id**

ID of the attribute to add to the group.

**group\_id**

ID of the group to add the attribute to.

**Returns:**

array

## /datamanager/removeAttributeFromGroup

Removes a Data Manager attribute from a Data Manager group.

**Parameters:**

**attribute\_id**

ID of the attribute to remove from the group.

**group\_id**

ID of the group to remove the attribute from.

**Returns:**

array

## /datamanager/createItem

Creates a Data Manager item, also called a data record.

**Parameters:**

**group\_id**

ID of the Data Manager group. Required.

**attribute\_\[id]**

The value of each attribute within the group, where `[id]` is the attribute ID.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Successfully created item in group",
        "group_id": 3,
        "item_id": 47
    }
```

## /datamanager/updateItem

Updates a Data Manager item.

**Parameters:**

**item\_id**

ID of the Data Manager item being updated.

**group\_id**

ID of the Data Manager group.

**attribute\_\[id]**

The value of each attribute within the group, where `[id]` is the attribute ID. Optional.

**Returns:**

array

## /datamanager/deleteItem

Deletes a Data Manager item by ID.

**Parameters:**

**item\_id**

The ID of the item to delete.

**Returns:**

array

## /datamanager/deleteItemsByGroup

Deletes all Data Manager items associated with a specified group.

**Parameters:**

**group\_id**

The ID of the group to delete all items from.

**Returns:**

array


# Integration
Source: https://docs.curator.interworks.com/curator_api/api_docs/integration

Integration API endpoints for managing commands and custom integrations

## /integration/commands

Returns a list of all commands

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": [
            {
                "id": 1,
                "name": "Test Command",
                "description": "This command refreshes extracts",
                "type": "tabcmd",
                "arguments": "",
                "schedule": "",
                "created": {
                    "date": "2017-08-17 21:08:02.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                },
                "updated": {
                    "date": "2017-08-17 21:08:02.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                }
            }
        ]
    }
```

## /integration/runCommand

Runs the specified command and returns its output.

**Parameters:**

**id**
Identifier of the command to run.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Status not provided by command"
    }
```

## /integration/runScript

Runs the specified script and returns its output.

**Parameters:**

**id**
Identifier of the script to run.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Status not provided by script"
    }
```

## /integration/scripts

Returns a list of all scripts

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": [
            {
                "id": 1,
                "name": "Test Script",
                "description": "This Script Does a Thing",
                "language": "python",
                "arguments": "",
                "schedule": "",
                "created": {
                    "date": "2017-08-17 21:11:44.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                },
                "updated": {
                    "date": "2017-08-17 21:11:44.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                }
            }
        ]
    }
```

## /integration/apiRelay

Kicks off an API relay request

**Returns:**

array


# MCP
Source: https://docs.curator.interworks.com/curator_api/api_docs/mcp

Connect an AI client such as Claude Code to Curator with a personal MCP token and the tools it can call.

## Introduction

Curator exposes a Model Context Protocol (MCP) endpoint. An MCP client such as Claude Code or Claude Desktop
connects to it with a personal token and can then call a set of read-only and administrative tools.

A token belongs to the backend user who generated it, and it can do nothing that user cannot do. Every tool
call checks the owner's backend permissions when it runs, and every call is recorded in the Usage Log with
the owner's login and the token's prefix.

## Generate a Token

1. Sign in to the backend and open the username dropdown at the top right.
2. Click **MCP Tokens**, then **Generate Token**.
3. Enter a **Name** that says where the token will be used, for example "Laptop Claude Code".
4. Choose when the token **Expires**. The default is 90 days. Choose **Never** only for unattended service
   accounts.
5. Under **Allowed tools**, leave every tool checked, or clear the tools this token must not call. A token
   with every tool checked also gains tools added in later releases.
6. Click **Generate**.

The next page shows the full token once. Copy it now: Curator stores only a hash, so the token cannot be
shown again. If you lose it, revoke it and generate a new one.

The same page has a **Connect a client** panel with the endpoint URL and a ready-to-run Claude Code setup
command. After you leave the page, the command shows `<token>` in place of the token.

## Connect a Client

The endpoint is `POST /curator/mcp` on your Curator site, and the token travels as a bearer credential:

```text theme={null}
Authorization: Bearer cmcp_...
```

For Claude Code, run the setup command from the token page in a terminal. It has this form:

```bash theme={null}
claude mcp add --transport http curator https://your-site.example.com/curator/mcp \
  --header "Authorization: Bearer cmcp_..."
```

Any client that speaks the MCP Streamable HTTP transport works the same way: point it at the endpoint URL
and send the token in the `Authorization` header. The endpoint accepts JSON-RPC 2.0 over POST and answers
with JSON. It does not open sessions or server-sent event streams.

## Manage Tokens

**MCP Tokens** lists your tokens with their prefix, allowed tools, expiry, and last use. Open a token to
edit its name or allowed tools; the owner, expiry, and token itself cannot change after generation. Tick one
or more tokens and click **Delete selected** to revoke them. A revoked token stops working at once.

You only see your own tokens. Tokens also stop working when their owner is banned, suspended, deleted, or
past their password expiry.

## Tools

Each tool runs with the owner's permissions. A tool the owner cannot use is not offered to the client.

| Tool                          | What it does                                                           | Permission                  |
| ----------------------------- | ---------------------------------------------------------------------- | --------------------------- |
| `get_status`                  | Curator build, PHP version, environment, and the configured drivers.   | Same as the **Status** page |
| `get_info`                    | The full `/portal/info` report with secrets removed.                   | Same as the **Status** page |
| `clear_cache`                 | Clears every Curator cache, like the toolbar's **Clear Cache** button. | Any backend user            |
| `list_pages`                  | Lists Curator pages.                                                   | Any Content permission      |
| `list_files`                  | Lists files.                                                           | Any Content permission      |
| `list_keywords`               | Lists content keywords.                                                | Any Content permission      |
| `list_menus`                  | Lists the navigation menu flat, with parent ids, link types, and URLs. | Any Content permission      |
| `list_dashboards`             | Lists Tableau dashboards.                                              | Any Tableau permission      |
| `list_powerbi_reports`        | Lists Power BI reports.                                                | Any Power BI permission     |
| `list_powerbi_dashboards`     | Lists Power BI dashboards.                                             | Any Power BI permission     |
| `list_thoughtspot_liveboards` | Lists ThoughtSpot liveboards.                                          | Any ThoughtSpot permission  |
| `list_sigma_workbooks`        | Lists Sigma workbooks.                                                 | Any Sigma permission        |

"Same as the **Status** page" means any Portal permission: a user who holds any one Portal permission, such
as managing URL redirects, can call `get_status` and `get_info`, exactly as they can open the Status page.
`get_info` reports server, database, and hosting details, so review who holds a Portal permission before
issuing tokens broadly.

A list tool only appears when its plugin is installed. Every list tool takes the same optional arguments and
returns the same shape:

**Arguments:**

**search**

Text to match against the title, case-insensitive. Optional.

**limit**

The maximum number of items to return. Optional, defaults to 100, maximum 500.

**offset**

The number of items to skip, for paging. Optional, defaults to 0.

**Returns:**

```JSON theme={null}
    {
        "total": 42,
        "offset": 0,
        "count": 2,
        "items": [
            {
                "id": 7,
                "title": "Sales Overview",
                "slug": "sales-overview",
                "url": "https://your-site.example.com/dashboard/sales-overview",
                "updated_at": "2026-09-01 14:02:11",
                "project_name": "Finance"
            }
        ]
    }
```

Some tools add a few columns of their own: pages include `content_type`, files include `file_type` and
`hidden`, Tableau dashboards include `project_name` and `featured`, and Power BI items include `group_name`.

## Limits and Logging

* Requests are rate limited per client address using the same limits as the REST API, set under
  **Settings** > **Security** > **Authentication Settings**.
* Every tool call writes a Usage Log row of type `interworks.portal.mcp.call` with the tool, its arguments,
  the owner, the token prefix, and the outcome.
* Rejected sign-ins are written to the Curator log with the reason and the token prefix. The full token is
  never logged.


# Tableau API
Source: https://docs.curator.interworks.com/curator_api/api_docs/tableau_api

Tableau API endpoints for dashboard creation and management through Curator

## /Tableau/createDashboard

Creates a Dashboard record

**Common Parameters:**

* **title** *required*
  The title of your Dashboard

* **url** *required*
  This is the url of the Dashboard on the Tableau Server environment.

* **slug**
  This is the url of the Dashboard on the Curator environment.

* **preloaded\_filters\_params**
  An array of objects defining filters or parameters to apply when the Dashboard loads.
  Each object accepts the following fields:
  * **name** *required*
    The name of the filter or parameter. Must match the name in the data source.
  * **value**
    The value to apply on Dashboard load. Multiple values can be separated with
    `|||` (three pipes, no spaces). Null and empty string values are allowed.
  * **type** *required*
    Must be `filter` or `parameter`.
  * **load\_domain\_values** *required*
    Must be `0` (Off) or `1` (On). When enabled for filters, all possible filter values
    remain available in Curator Filters even after preloading specific values.

***Note:** Other optional parameters, such as keywords, featured, etc. are supported but not listed here.*

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Created dashboard record",
        "dashboard": {...},
    }
```

## /Tableau/updateDashboard

Updates an existing Dashboard record.

**Common Parameters:**

* **id** *required*
  The ID of the Dashboard to update.
* **slug**
  The url of the Dashboard on the Curator environment.
* **preloaded\_filters\_params**
  An array of objects defining filters or parameters to apply when the Dashboard loads.
  Each object accepts the following fields:
  * **name** *required*
    The name of the filter or parameter. Must match the name in the data source.
  * **value**
    The value to apply on Dashboard load. Multiple values can be separated with
    `|||` (three pipes, no spaces). Null and empty string values are allowed.
  * **type** *required*
    Must be `filter` or `parameter`.
  * **load\_domain\_values** *required*
    Must be `0` (Off) or `1` (On). When enabled for filters, all possible filter values
    remain available in Curator Filters even after preloading specific values.

***Note:** Other optional parameters, such as title, url, featured, etc. are supported but not listed here.*

**Returns:**

array

**Example Request Body:**

```JSON theme={null}
    {
        "id": 1,
        "slug": "my-dashboard",
        "preloaded_filters_params": [
            {
                "name": "Region",
                "value": "West|||East",
                "type": "filter",
                "load_domain_values": 1
            },
            {
                "name": "Year",
                "value": "2023",
                "type": "parameter",
                "load_domain_values": 0
            }
        ]
    }
```

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Updated dashboard record",
        "dashboard": {...}
    }
```

## /Tableau/syncTags

Kicks off tag schedule which synchronizes tags from Tableau Server

**Returns:**

string

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Tag sync is complete"
    }
```

## /Tableau/syncGroups

Kicks off a schedule which synchronizes groups from Tableau Server.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Group sync is complete"
    }
```

## /Tableau/listUsers

Lists users and groups.

**Returns:**

array

**Example Response:**

```JSON theme={null}
    [
        {
            "tableau_user_id": "21342134-236a-49f9-88e9-224272ab312c",
            "name": "CuratorDemo",
            "full_name": "Curator Demo",
            "site_role": "SiteAdministrator",
            "skip_sync": null,
            "groups": []
        },
        {
            "tableau_user_id": "12341234-89a3-4fde-acd9-a3b806995d69",
            "name": "admin",
            "full_name": "Administrator",
            "site_role": "ServerAdministrator",
            "skip_sync": null,
            "groups": []
        }
    ]
```

## /Tableau/setAuthentication

Sets the authentication type.

**Returns:**

array

## Tableau/setRest

Sets the REST credentials for Tableau Server Settings.

**Returns:**

array

## /Tableau/syncTableauDashboardIds

Kicks off schedule which synchronizes Dashboard IDs from the Tableau Server.

**Common Parameters:**

* **not\_found\_only**
  When set to `true`, only dashboards currently marked as Not Found on Tableau will be synced.
  Defaults to `false`, which syncs all dashboards.

**Returns:**

string

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Dashboard Id sync is complete"
    }
```

## /Tableau/resetViews

Kicks off a schedule task which clears out the Dashboard views

**Returns:**

string

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /Tableau/refreshGroups

Kicks off tag schedule which clears the old groups and adds in new groups

**Returns:**

string

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": 0
    }
```

## /Tableau/refreshThumbnails

Kicks off task which refreshes all thumbnails.

**Returns:**

string

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Dashboard thumbnails are refreshed."
    }
```


# User API
Source: https://docs.curator.interworks.com/curator_api/api_docs/user_api

User management API endpoints for creating and managing backend users

## /user/createBackendUser

Creates a backend user

**Returns:**

array

## /user/createFrontendGroup

Creates a Frontend Group.

*Note: To add members to your Frontend Group, use the addUserToGroup API endpoint.*

**Example Request:**

`POST [your_domain]/api/v1/User/createFrontendGroup?apikey=[your_api_key_here]&name=[group_name_here]`

```JSON theme={null}
    {
        "platforms": {
            "tableau":[
                {
                    "server":"tableau us", // Name of your Tableau Server Connection
                    "site":"__DEFAULT__",
                    "group":"Alligator Admins" // Display Name of your Tableau Server Group
                }
            ],
            "thoughtspot":[
                "Europe Sales" // Display Name of your ThoughSpot Group
            ]
        },
        "custom_attributes": {
            "color": "blue"
        }
    }
```

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Successfully added platform groups to frontend group 30 and added syncing to the queue",
        "metadata": [
            {
                "tableau_server": "tableau us|||https://tableau.your-domain.com",
                "tableau_site": "__DEFAULT__",
                "tableau_group": "Alligator Admins|||[tableau_group_id_here]"
            },
            {
                "thoughtspot_group": "Europe Sales|||[thoughtspot_group_id_here]"
            }
        ],
        "tableauGroupsNotFound": "",
        "thoughtspotGroupsNotFound": ""
    }
```

## /user/createFrontendUser

Creates a single frontend (i.e. Curator) user. This does not create any platform-specific users, and there is no
bulk/CSV equivalent -- to create many frontend users at once, script repeated calls to this endpoint or to the
[`usermgmt:frontendusercreate`](/curator_api/artisan_commands/frontendusercreate) artisan command.

<Note>
  If Curator authenticates against an external identity provider (SAML, OIDC/OAuth, Tableau Server, or Power BI), you
  most likely do not need this endpoint at all. Frontend User accounts are created automatically the first time each
  user signs in -- see [Just-in-time (JIT) Provisioning](/users_groups/user_management/just_in_time_jit_provisioning).
  Creating users in advance is only necessary when JIT provisioning has been turned off (**Settings** > **Security** >
  **Authentication Settings** > **Customization** > *Disable Just-in-time Provisioning of Curator Users*), or when the
  authentication type is Curator Users.
</Note>

**Parameters:**

* `full_name` (string, required) - The full name for the new Curator user.
* `username` (string, required) - The username for the new Curator user.
* `email` (string, required) - The email address for the new Curator user.
* `password` (string, required) - The desired password for the new Curator user.
* `domain` (string, optional) - Domain of the user, e.g. `domain\username` or `username@domain`. If omitted, Curator
  derives the domain from the username or email address where possible.
* `send_user_created_curator_email` (bool, optional) - Send the Curator signup email to the new user. `1` = send,
  `0` = suppress. Defaults to `0`.

**Example Request:**

The query string below is shown wrapped for readability; send it as a single URL.

```
POST [your_domain]/api/v1/User/createFrontendUser
    ?apikey=[your_api_key_here]
    &full_name=[full_name_here]
    &username=[username_here]
    &email=[email_here]
    &password=[password_here]
```

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Successfully created frontend user: [username_here]",
        "id": 42
    }
```

## /user/fetchUser

Returns the currently logged in user's information.

**Returns:**

array

## /user/getManageablePermissions

Gets a listing of available manageable permissions

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "status": "Success",
        "permissions": [
            "InterWorks.datamanager.data_structure",
            "InterWorks.datamanager.data",
            "InterWorks.tableauviz.access_tableau_settings",
            "InterWorks.tableauviz.access_dashboards",
            "InterWorks.integration.manage_scripts",
            "InterWorks.integration.run_scripts",
            "InterWorks.integration.manage_commands",
            "InterWorks.integration.run_commands",
            "InterWorks.integration.manage_api_relay",
            "InterWorks.usermgmt.manage_backend_users",
            "InterWorks.usermgmt.manage_frontend_users",
            "InterWorks.content.access_content",
            "InterWorks.portal.access_portal_settings",
            "InterWorks.portal.manage_upgrade",
            "InterWorks.portal.api_keys"
        ]
    }
```

## /user/addUserToGroup

Adds a user to a group (syncs with Tableau if possible)

**Returns:**

array

## /user/listGroups

Lists groups.

**Returns:**

array

## /user/listUsers

Lists users and the groups they belong to.

**Parameters:**

* `num` (integer, optional) - Number of users to return per page. Defaults to `50`.
* `pg` (integer, optional) - Page number. Defaults to `1`.
* `site` (string, optional) - Tableau Site content URL to filter by; only users with a connected Tableau user on that
  site are returned.

**Example Request:**

`GET [your_domain]/api/v1/User/listUsers?apikey=[your_api_key_here]&num=50&pg=1`

**Returns:**

array

Each user object includes `frontend_user_id`, `name`, `full_name`, `email`, `analytics_id`, `last_login_at` (the time
the user last signed in, or `null` if they never have), and a `groups` array.

**Example Response:**

```JSON theme={null}
    [
        {
            "frontend_user_id": 42,
            "name": "jane.smith",
            "full_name": "Jane Smith",
            "email": "jane.smith@example.com",
            "analytics_id": "jane.smith@example.com",
            "last_login_at": "2026-08-18 14:54:34",
            "groups": [
                {
                    "frontend_group_id": 3,
                    "name": "Sales",
                    "source": "manual"
                }
            ]
        }
    ]
```

## /user/removeUserFromGroup

Removes a user from a group (syncs with Tableau if possible)

**Returns:**

array

## /User/syncGroup

Kicks off a schedule which synchronizes a single Frontend Group's membership. Specify the Group's `groupName` OR the
Group's `id` (the `id` is used if both are provided).

**Parameters:**

* `groupName` (string, optional) - The name of the Frontend Group as shown on the backend under
  **Settings** > **Users** > **Frontend Groups**.
* `id` (integer, optional) - The ID of the Frontend Group. One of `groupName` or `id` is required.

**Example Request:**

`GET [your_domain]/api/v1/User/syncGroup?apikey=[your_api_key_here]&groupName=[group_name_here]`

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "[group_name_here] sync is queued."
    }
```

## /User/syncGroups

Kicks off a schedule which synchronizes platform group memberships to all configured Frontend Groups. Internally this
calls `FrontendGroup::syncSchedule` to enqueue a sync for every Frontend Group.

**Example Request:**

`GET [your_domain]/api/v1/User/syncGroups?apikey=[your_api_key_here]`

**Returns:**

array

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "msg": "Group syncs are queued."
    }
```

***Note:*** Both `/User/syncGroup` and `/User/syncGroups` enqueue jobs asynchronously - the API call returns as soon as
the sync is queued. The actual membership sync runs through the queued process scheduler (`curator:runschedule`), so
the work is not complete the moment the response is received.


# curator:addapikey
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/addapikey

Add an API key for Curator

Adds an API key for Curator.

**Arguments:**

| Argument | Required | Description        |
| -------- | -------- | ------------------ |
| `key`    | Yes      | The API key to add |

**Example:**

```bash theme={null}
php artisan curator:addapikey my-secret-api-key
```


# distributed:addnode
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/addnode

Add a node to a highly available Curator cluster

Adds a node to a highly available Curator cluster.

**Arguments:**

| Argument | Required | Description                        |
| -------- | -------- | ---------------------------------- |
| `node`   | Yes      | The IP address of the Curator node |

**Example:**

```bash theme={null}
php artisan distributed:addnode 192.168.1.100
```


# backenduser:create
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/backenduser_create

Create a backend user with all available permissions

Creates a backend user with all available permissions.

**Arguments:**

| Argument    | Required | Description                       |
| ----------- | -------- | --------------------------------- |
| `username`  | Yes      | Backend username                  |
| `password`  | Yes      | Initial password                  |
| `email`     | Yes      | Email address                     |
| `firstname` | No       | First name (defaults to username) |
| `lastname`  | No       | Last name (defaults to username)  |

**Example:**

```bash theme={null}
php artisan backenduser:create admin secretpass admin@example.com John Doe
```


# curator:clean
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/clean

Remove demo data from the Curator instance

Removes demo data from the Curator instance. This deletes seeded dashboards, filters, parameters, and menus, then
runs `winter:fresh --force` and removes installation files.

**Arguments:** None

**Example:**

```bash theme={null}
php artisan curator:clean
```


# curator:decrypt
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/decrypt

Decrypt cipher text using the portal encryption key

Uses the portal's encryption key to attempt to decrypt an arbitrary cipher text. If decryption fails, the original
text is returned.

**Arguments:**

| Argument | Required | Description                |
| -------- | -------- | -------------------------- |
| `cipher` | Yes      | The cipher text to decrypt |

**Example:**

```bash theme={null}
php artisan curator:decrypt "encrypted-cipher-text-here"
```


# curator:encrypt
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/encrypt

Encrypt text using the portal encryption key

Uses the portal's encryption key to encrypt arbitrary text.

**Arguments:**

| Argument    | Required | Description               |
| ----------- | -------- | ------------------------- |
| `cleartext` | Yes      | The plain text to encrypt |

**Example:**

```bash theme={null}
php artisan curator:encrypt "my secret value"
```


# curator:environment
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/environment

Set the environment Curator is running within

Sets the environment Curator is running within.

**Arguments:**

| Argument | Required | Description                                        |
| -------- | -------- | -------------------------------------------------- |
| `env`    | Yes      | One of: `production`, `development`, `QA`, `stage` |

**Example:**

```bash theme={null}
php artisan curator:environment production
```


# curator:forcefrontendloginforbackend
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/forcefrontendloginforbackend

Force backend users to authenticate through the frontend login flow

Forces backend users to authenticate through the frontend login flow.

**Arguments:**

| Argument      | Required | Description                                    |
| ------------- | -------- | ---------------------------------------------- |
| `force_login` | No       | `1` to enable or `0` to disable (default: `1`) |

**Options:**

| Option    | Shortcut | Description               |
| --------- | -------- | ------------------------- |
| `--force` | `-f`     | Skip confirmation prompts |

**Example:**

```bash theme={null}
php artisan curator:forcefrontendloginforbackend 1 --force
```


# usermgmt:frontendusercreate
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/frontendusercreate

Create a new frontend user with specified credentials

Creates a new frontend user with the specified credentials.

**Arguments:**

| Argument   | Required | Description       |
| ---------- | -------- | ----------------- |
| `username` | Yes      | The username      |
| `name`     | Yes      | The display name  |
| `email`    | Yes      | The email address |
| `password` | Yes      | The password      |

**Options:**

| Option    | Shortcut | Description               |
| --------- | -------- | ------------------------- |
| `--force` | `-f`     | Skip confirmation prompts |

**Example:**

```bash theme={null}
php artisan usermgmt:frontendusercreate jdoe "John Doe" jdoe@example.com secretpass
```


# curator:import
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/import

Import content from a local file or another Curator instance

Imports content to this Curator instance using a local file or another Curator instance via the API.

**Options:**

| Option     | Shortcut | Description                                    |
| ---------- | -------- | ---------------------------------------------- |
| `--file`   | `-f`     | Path to the import file (`.iwe` or `.iwgz`)    |
| `--url`    | `-u`     | URL of a Curator instance to pull content from |
| `--key`    | `-k`     | API key for the remote Curator instance        |
| `--latest` |          | Import the most recent automatic export        |

**Examples:**

```bash theme={null}
# Import from a local file
php artisan curator:import --file=/path/to/export.iwe

# Import from another Curator instance
php artisan curator:import --url=https://other-curator.example.com --key=my-api-key

# Import the latest automatic export
php artisan curator:import --latest
```


# curator:info
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/info

Display information about the Curator portal

Returns information about the Curator portal, including version, environment, and configuration details.

**Options:**

| Option         | Shortcut | Description                                 |
| -------------- | -------- | ------------------------------------------- |
| `--extensions` | `-e`     | Include loaded PHP extensions in the output |
| `--ini`        | `-i`     | Include PHP ini settings in the output      |

**Examples:**

```bash theme={null}
php artisan curator:info
php artisan curator:info --extensions --ini
```


# integration:create
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/integration_create

Create a new Connection from a JSON definition file

Creates a new Connection from a JSON definition file.

**Arguments:**

| Argument | Required | Description                                               |
| -------- | -------- | --------------------------------------------------------- |
| `path`   | Yes      | Path to a JSON file containing the Connection information |

**Example:**

```bash theme={null}
php artisan integration:create /path/to/connection.json
```


# curator:migrate
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/migrate

Run database and other migrations for Curator

Runs database and other migrations for Curator.

**Arguments:** None

**Example:**

```bash theme={null}
php artisan curator:migrate
```


# Artisan Commands
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/overview

Reference for all custom Curator artisan commands, including descriptions, arguments, options, and usage examples.

Curator registers a number of custom artisan commands for administration and configuration. Run any command with
`php artisan <command>` from the webroot of the Curator installation, regardless of platform (Linux or Windows).
You can also run `php artisan` by itself to see a full list of all available artisan commands.

<Note>
  Older versions of Curator use the `portal:` prefix instead of `curator:` for core commands (e.g., `portal:setkey`
  instead of `curator:setkey`). Either prefix works because they are aliased.
</Note>


# curator:parse-export
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/parse_export

Parse a Curator export file into individual content type files

Ingests a Curator export file and outputs multiple individual files based on the content types you select.

**Arguments:**

| Argument     | Required | Description                                 |
| ------------ | -------- | ------------------------------------------- |
| `filePath`   | Yes      | Path to the export file (`.iwe` or `.iwgz`) |
| `outputPath` | No       | Directory to write the output file to       |

**Options:**

| Option      | Description                                         |
| ----------- | --------------------------------------------------- |
| `--exclude` | Exclude the selected keys instead of including them |

**Examples:**

```bash theme={null}
# Include only selected content types
php artisan curator:parse-export /path/to/export.iwe /path/to/output

# Exclude selected content types
php artisan curator:parse-export /path/to/export.iwe /path/to/output --exclude
```


# curator:queuebackup
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/queuebackup

Queue a full backup of the Curator instance

Queues a full backup of the Curator instance.

**Arguments:** None

**Example:**

```bash theme={null}
php artisan curator:queuebackup
```


# curator:runschedule
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/runschedule

Run the scheduled commands as queuing or queued

Runs the scheduled commands as queuing or queued.

**Arguments:**

| Argument | Required | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| `type`   | Yes      | Schedule type: `combined`, `queued`, or `queuing` |

**Example:**

```bash theme={null}
php artisan curator:runschedule combined
```


# centraldispatch:setasmanaged
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/setasmanaged

Configure this Curator portal as a managed instance controlled by Central Dispatch

Configures this Curator portal as a managed instance controlled by a Central Dispatch dispatcher.

**Arguments:**

| Argument              | Required | Description                                   |
| --------------------- | -------- | --------------------------------------------- |
| `dispatcher_url`      | Yes      | URL of the managing dispatcher                |
| `dispatcher_api_key`  | Yes      | API key for communicating with the dispatcher |
| `managed_instance_id` | Yes      | The ID the dispatcher uses for this instance  |
| `upgrades_key`        | No       | The Curator license key for upgrades          |

**Example:**

```bash theme={null}
php artisan centraldispatch:setasmanaged \
  https://dispatch.example.com \
  dispatch-api-key \
  instance-42 \
  optional-license-key
```


# curator:setauth
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/setauth

Set the authentication type Curator uses

Sets the authentication type Curator uses.

**Arguments:**

| Argument | Required | Description                                                                                            |
| -------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `auth`   | Yes      | One of: `saml`, `oauth`, `portal`, `tableau_server`, `thoughtspot`, `active_directory`, `pass_through` |

**Example:**

```bash theme={null}
php artisan curator:setauth saml
```


# curator:setbackenduserpasswordduration
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/setbackenduserpasswordduration

Set the number of days before backend user passwords expire

Sets the number of days before backend user passwords expire.

**Arguments:**

| Argument   | Required | Description                                           |
| ---------- | -------- | ----------------------------------------------------- |
| `duration` | Yes      | Number of days until expiration (`0` disables expiry) |

**Example:**

```bash theme={null}
php artisan curator:setbackenduserpasswordduration 90
```


# curator:setdomain
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/setdomain

Set a forced domain for Curator users

Sets a forced domain for Curator users.

**Arguments:**

| Argument | Required | Description       |
| -------- | -------- | ----------------- |
| `domain` | Yes      | The domain to set |

**Example:**

```bash theme={null}
php artisan curator:setdomain curator.example.com
```


# curator:setforcessl
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/setforcessl

Set whether Curator should force SSL connections

Sets whether Curator should force SSL connections.

**Arguments:**

| Argument | Required | Description                        |
| -------- | -------- | ---------------------------------- |
| `force`  | Yes      | `1` to force SSL or `0` to disable |

**Example:**

```bash theme={null}
php artisan curator:setforcessl 1
```


# curator:setkey
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/setkey

Set the license key for Curator

Sets the license key for Curator.

**Arguments:**

| Argument | Required | Description             |
| -------- | -------- | ----------------------- |
| `key`    | Yes      | The Curator license key |

**Example:**

```bash theme={null}
php artisan curator:setkey your-license-key
```


# curator:setsmtp
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/setsmtp

Configure SMTP mail settings for Curator

Configures SMTP mail settings for Curator.

**Arguments:**

| Argument      | Required | Description             |
| ------------- | -------- | ----------------------- |
| `smtpAddress` | Yes      | The SMTP server address |

**Options:**

| Option            | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `--sender_name=`  | Display name for the email sender                      |
| `--sender_email=` | Email address for the sender                           |
| `--auth_required` | Flag indicating SMTP authorization is needed           |
| `--username=`     | SMTP username (required when `--auth_required` is set) |
| `--password=`     | SMTP password (required when `--auth_required` is set) |
| `--port=`         | SMTP port number                                       |
| `--encryption=`   | Encryption type (e.g., `tls`, `ssl`)                   |

**Example:**

```bash theme={null}
php artisan curator:setsmtp smtp.example.com \
  --sender_name="Curator" \
  --sender_email="noreply@example.com" \
  --auth_required \
  --username="user" \
  --password="pass" \
  --port=587 \
  --encryption=tls
```


# tableauviz:updatepreloadsettings
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/updatepreloadsettings

Update preload settings by checking Tableau Metadata API for filter/parameter types

Reaches out to Tableau's Metadata API to check whether each preload setting is a filter or parameter and updates the
database accordingly.

**Options:**

| Option    | Shortcut | Description               |
| --------- | -------- | ------------------------- |
| `--force` | `-f`     | Skip confirmation prompts |

**Example:**

```bash theme={null}
php artisan tableauviz:updatepreloadsettings --force
```


# curator:upgrade
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/upgrade

Update Curator to the latest or a specific version

Updates Curator to the latest version (or a specific version). This command downloads the upgrade package, validates
it, applies the update, clears caches, and runs migrations.

**Arguments:**

| Argument  | Required | Description                                         |
| --------- | -------- | --------------------------------------------------- |
| `version` | No       | Specific version to upgrade to (defaults to latest) |

**Options:**

| Option       | Description                          |
| ------------ | ------------------------------------ |
| `--theme`    | Upgrade the theme (default behavior) |
| `--no_theme` | Skip upgrading the theme             |

**Examples:**

```bash theme={null}
# Upgrade to the latest version
php artisan curator:upgrade

# Upgrade to a specific version
php artisan curator:upgrade 4.2.0

# Upgrade without updating the theme
php artisan curator:upgrade --no_theme
```


# usermgmt:warmcache
Source: https://docs.curator.interworks.com/curator_api/artisan_commands/warmcache

Warm the cache for frontend users

Warms the cache for frontend users. When no user is specified, warms the cache for the configured priority group.

**Arguments:**

| Argument | Required | Description                           |
| -------- | -------- | ------------------------------------- |
| `user`   | No       | Username or user ID to warm cache for |

**Options:**

| Option    | Shortcut | Description                    |
| --------- | -------- | ------------------------------ |
| `--reset` |          | Reset the cache before warming |
| `--force` | `-f`     | Skip confirmation prompts      |

**Examples:**

```bash theme={null}
# Warm cache for the priority group
php artisan usermgmt:warmcache

# Warm cache for a specific user
php artisan usermgmt:warmcache jdoe

# Reset and warm cache
php artisan usermgmt:warmcache --reset
```


# Commands
Source: https://docs.curator.interworks.com/curator_api/custom_integration/commands

Create and manage custom commands for scheduled or ad-hoc execution

You can set up custom commands to run by the site. This requires the "Integration" setting to be enabled. To
create a command to be run on a schedule or ad hoc:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the "Integration" link at the top.
4. Click on "Manage Commands" in the left navigation.
5. Click on the "New Command" button at the top of the main page content.
6. Enter the name, description, and command type, arguments, schedule, etc. as needed and click "Create".


# Scripts
Source: https://docs.curator.interworks.com/curator_api/custom_integration/scripts

Set up and manage custom scripts for scheduled or ad-hoc execution

You can set up custom scripts to run by the site. This requires the "Integration" setting to be enabled. To
create a custom script to be run on a schedule or ad hoc:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the "Integration" link at the top.
4. Click on "Manage Scripts" in the left navigation.
5. Click on the "New Script" button at the top of the main page content.
6. Enter the name, description, and schedule of execution of the script, and select the appropriate script language.
7. Enter the script details as appropriate
   * For EDT, the full path to the EDT console runner must be specified and the EDT plan must be uploaded.
   * For powershell and python, the script code must be typed or copy and pasted in.
   * If additional arguments need to be passed to the command which runs the script (i.e. powershell.exe,
     etc.), enter those in the arguments field.
8. Click on the "Create" button.


# Subscription Routing
Source: https://docs.curator.interworks.com/curator_api/custom_integration/subscription_routing

Configure subscription email routing to direct users through Curator instead of Tableau Server

Curator integrates nicely with Tableau's native subscription system.
When users receive a subscription email, however, you may not wish the users to be routed to Tableau Server.

If you would rather users be routed to the appropriate Dashboard on Curator, [update Tableau Server's "subscription url"](https://kb.tableau.com/articles/issue/subscription-link-in-email-broken).

Point this url to your Curator website with /subscription/ appended.
For example, `https://examplecurator.interworks.com/subscription`.

***Note:** At the time of this writing, updating this value in Tableau Server requires a Tableau Server reboot.*


# Curator API Overview
Source: https://docs.curator.interworks.com/curator_api/getting_started/curator_api_overview

Complete guide to the Curator API including metadata access, content management and integration command capabilities.

The Integration System gives you many options for interfacing programmatically with the backend. This API
gives you access to the metadata behind your portal content as well as the ability to update content and run
integration commands.
Before you do, though, you'll need an API Key and the endpoint!

## 1. Obtaining an API Key

To access the API, you will need an API key. You can create an API Key in the /backend area of your portal.
API Keys are managed in Settings -> API Keys

## 2. Accessing the API

Once you have an API Key, you can access the API through the "api" folder on your portal's URL.
For example: `https://yourportal.example.com/api/v1/portal/upgrade?apikey=my_api_key_here`

## 3. API Response

All of the Integration System's APIs return JSON. You can convert this easily to an array in most languages.
(json\_decode, for example, in PHP)

## Auto Generate API Links

You can also use Curator's backend to generate links to the various Curator API endpoints

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **API Keys** section from the left-hand menu.
3. Change the dropdowns in the REST API to the respective endpoint you would like to try.
4. Use the preview link generated below the dropdowns to start using the endpoint.  *Note: Some variables may
   be missing from these preview links.*


# Curator Integration Overview
Source: https://docs.curator.interworks.com/curator_api/getting_started/curator_integration_overview

Overview of Curator API integration capabilities including API calls, scripts and custom automation features.

You can relay API calls from Curator, make Curator run scripts and do other interesting things.


# Dynamic Body Content in the API Relay
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/api_relay_dynamic_body_content

Let an incoming request set or edit the body that the API Relay sends to your target API.

The API Relay normally sends a fixed request body to your target API. Dynamic Body Content lets a value
from the incoming request set or edit that body when the relay runs. You can send the value as
the whole body, or drop it into a placeholder inside a body you have already written.

## Before you start

1. Enable **Integration Automation**. Go to **Settings > Portal Settings > Features**, turn on
   "Integration Automation" in the Functionality section, then save and refresh.
2. Create an API Relay. Go to **Integrations > Automation > API Relay** and add a relay with your target
   API in the **URL** field.
3. In **Outgoing Request Content**, enter your default request in the **Body Content** field. This is the
   body the relay sends when no dynamic value arrives.

## Enable Dynamic Body Content

Open your relay and, in the Outgoing Request Content section, set the following fields.

* **Allow Dynamic Body Content.** Turn this on to reveal the rest of the dynamic fields.
* **Dynamic Body Content Variable.** Enter the name of the input field in the incoming request that
  carries the value you want to use. This name is required once the toggle is on. If the incoming request
  leaves this field out, the relay sends your static Body Content instead.
* **Perform Find/Replace of Body Content.** This switch chooses one of the two modes below.

### Mode 1: Replace the whole body

Leave **Perform Find/Replace of Body Content** turned off. The incoming value becomes the entire request
body. Use this when the caller already knows the exact body to send and you only want the relay to pass
it through.

### Mode 2: Drop the value into a placeholder

Turn **Perform Find/Replace of Body Content** on and set **Find/Replace Placeholder** to a marker you put
inside the Body Content field. When the relay runs, it swaps that marker for the incoming value and sends
the rest of the body as written. Use this when most of the body is fixed and only one part changes per
request.

For example, set Body Content to:

```json theme={null}
{ "report": "Quarterly Sales", "token": "__TOKEN__" }
```

Set the placeholder to `__TOKEN__` and the variable to `token`. A request that sends `token=abc123`
produces:

```json theme={null}
{ "report": "Quarterly Sales", "token": "abc123" }
```

## Adjust the value before it is sent

The **Dynamic Body Content Variable Advanced Processing** repeater edits the incoming value before the
relay uses it. Add one or more rules, and the relay applies them in order.

* **Remove Portion.** Enter the text to strip out of the value. For example, remove `Bearer ` so a value
  of `Bearer abc123` becomes `abc123`.
* **Find/Replace Portion.** Enter the text to find and the text to replace it with.

Each rule runs against the incoming value first. The placeholder swap in Mode 2 happens afterward, using
the adjusted value.

## Things to know

* **Browser calls must avoid a CORS preflight.** The relay endpoint does not return CORS headers, so a
  front-end `fetch` that triggers a preflight -- a custom header or a JSON content type -- is blocked by
  the browser. Call it as a "simple request" instead: GET or POST with form-encoded parameters and no
  custom headers (which is how Dynamic Body Content is meant to receive its value), or trigger it from
  your backend.
* **One variable per relay, but it can carry several values.** Dynamic Body Content maps a single
  incoming field into the body. That one value can still hold multiple pieces -- put a fragment of JSON
  in it and drop that fragment into the body with Mode 2. For example, set Body Content to
  `{"type":"widget",__EXTRA_KEY_VALUE_PAIRS__}` with the placeholder `__EXTRA_KEY_VALUE_PAIRS__` and the
  variable `dynamic-content`. A request sending `dynamic-content="token":"1234","name":"John Doe"`
  produces `{"type":"widget","token":"1234","name":"John Doe"}`. Depending on how the caller sends the
  request, a fragment like this may need to be URL-encoded on the way in and will arrive decoded, so
  account for encoding and decoding around any characters your fragment contains. To fill parts of the
  body from more than one incoming field, send a full body and use Mode 1, or set up separate relays.
* **A blank value clears the body.** If the incoming request includes the variable with an empty value,
  the relay treats that empty value as the body. To fall back to your static Body Content, leave the
  variable out of the request rather than sending it blank.
* **Body content applies to POST relays.** A GET relay sends its parameters on the URL and ignores the
  body.

## Related

* [Sending Data to Webhooks](/embedding_using_analytics/data_manager/sending_data_to_webhooks)


# Connecting to Data Manager
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/connecting_to_data_manager

Set up connections and integrate Data Manager with your analytics workflow for data collection and processing.

When using Data Manager you will likely need to connect to the underlying database that stores the data input from your
users.  You can find the connection information on the "Data Group" edit page, but first you'll need to create a
readonly user (if one does not exist in the info.txt/info.json file found in the root directory of the Curator install).

Note: This will allow your readonly user to connect from anywhere.  If you'd like to specify the IP address they can
connect from replace the '%' with your IP address in the examples below to limit where they can query from.

## Creating a Readonly MySQL User

### 1. Log into MySQL

#### Linux

Run the command below on your server to login to mysql:

```bash theme={null}
mysql -u root -p
```

#### Windows

Navigate into MariaDB/MySQL root directory and then login to MySQL:

```bash theme={null}
cd C:\InterWorks\Curator\libs\MariaDB\bin
mysql -u root -p
```

### 2. Create a new MySQL user

Run the command below to create a new user that can run a connection from *anywhere* (replacing 'USER' and 'PASSWORD'
with a username and password you'd like to use):

```SQL theme={null}
CREATE USER 'USER'@'%' IDENTIFIED BY 'PASSWORD';
```

### 3. Grant read-only permission to the MySQL user

Run the command below to create a new user that can read data from *anywhere* (again replacing 'USER' and 'PASSWORD'
with a username and password you'd like to use):

```SQL theme={null}
GRANT SELECT, SHOW VIEW ON curator.* TO 'USER'@'%' IDENTIFIED BY 'PASSWORD';
FLUSH PRIVILEGES;
```

**Important!** Be sure you keep these credentials secure, but also available for reference as they will be required to
connect to your data.

### Connecting to the Datamanager Database

1. Find the connection information for the table you would like to view in the top section of the edit "Data Group" page

   * Database Name: **Curator**
   * Host Name: **127.0.0.1**
   * Table Name: **a\_reports\_data\_group**

2. Use the connection details from the "Creating a Readonly MySQL User" and the database, hostname, and table name from
   the previous step to connect to your MySQL data source.

**Compatible clients:** Any tool that supports a MySQL connection can connect to the Data Manager database. This
includes Power BI (via its built-in MySQL connector), Tableau (via a MySQL data connection), and MySQL Workbench.

### Troubleshooting Connections

1. Ensure your firewall rules allow inbound traffic over port 3306 to allow remote connections to your database.
   If you are having trouble connecting, please contact your hosting team for further help.
2. By default, remote connections are not allowed on some operating systems (e.g. Ubuntu 20).  You can run the commands
   below to set up remote connections:

   Determine the location of your MySQL config file by running the command below:

   ```bash theme={null}
   mysql --help | grep "Default options" -A 1
   ```

   Open the file that is returned from these commands (i.e. `/etc/my.cnf`):
   Add the following line to the bottom of the file, where `xxx.ip.xxx` is replaced with your IP address, or you can use
   `0.0.0.0` to allow remote connections from anywhere:

   ```conf theme={null}
   bind-address= xxx.ip.xxx
   ```

   Now save your file and restart mysql to allow remote connections:

   ```bash theme={null}
   sudo systemctl restart mysql
   ```


# Creating a Form
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/creating_a_form

Build custom data collection forms using Data Manager to gather structured information from users.

First before you continue - take a look at our [Data Manager Basics](/embedding_using_analytics/data_manager/data_manager_basics)
to get familiar with terms and how Data Manager works generally.  Once you've perused that page, check out all the
flexible ways you can add forms and gather important feedback in your Curator site.

## Building your Form

To create a form, simply map all the Attributes you would like your Group to include.  If you're not sure which field
types you'd like your form to contain refer to the "Available Fields" section below.  Once you've created your
attributes, simply collect them into your Data Manager Group to begin placing your form throughout your site.  For
details on how to make your form accessible, refer to the "Accessing the Data Manager Form" section below.

## Available Fields

There are many ways to build a form using Curator's Data manager. Below, you'll find an outline of each field and what
it's used for.

### User-populated fields

There are many flexible options when building a form, and your users may want flexible free-text input or pre-selected
date or dropdown options:

* **Short Text**: A standard user-input text field, typically used for things like first name, last name, and email.

* **Long Text**: A free-form text entry allowing for lengthy input, primarily used when your users will be entering
  one or more sentences into the form.

* **Number**: Short Text input that limits entry to numbers (whole or decimal).

* **URL**: Short Text input that limits the format to a URL.

* **Dropdown**: Create a pre-set list of options for users to select from.

* **Date**: A calendar-date picker allowing users to select a given day.

* **Password**: Short Text input that hides the input for secure browsing (however, the password will not be encrypted
  in the database once stored).

* **Markdown**: A markdown field - renders a markdown text-editor on the backend when inputting new data.  This is
  primarily used when creating documentation.

### Fields populated from other sources

Some other sources within Curator may contain the data you want to populate your form with.  For these
more complex scenarios, you can leverage the following fields:

* **Lookup**: A dropdown that allows you to retrieve the selected options from another data manager group's input.

* **Read-only Field**: Short Text input that users cannot interact with - for use when populating an input using custom
  code.

### Fields populated from other sources: *Tableau mark-commenting only*

When selecting a data-point on a Tableau Dashboard, you can leverage that Dashboard's underlying data to pre-populate the
form that renders in the pop-up modal.  To learn ore about this, refer to the
[Mark Commenting](/embedding_using_analytics/data_manager/mark_commenting)
details.  To utilize the data that resides in your Dashboard to pre-fill dropdown options use these two fields:

* **Tableau Field**: A dropdown field that retrieves the data from the Tableau mark-selection for a given field name and
  populates the possible options when the form is rendered.

* **Tableau Parameter**: A dropdown field that retrieves the data from the Tableau mark-selection for a given parameter
  and populates the possible options when the form is rendered.

## Accessing the Data Manager Form

Once your Data Manager Group has been created, you will need to share the form so users can access it and start adding
their own data in to Curator's data manager storage.  There are four possible ways to access the form you've created
through your Group.

### Default Data Manager Form

Once a Data Manager Group has been created, Curator provides you with a templated page that contains your Data Manager
form - along with an option view of the data depending on the settings you've enabled for your group.

### Adding a Data Manager form to a page

Using Curator's page builder system, you can add a form - with a few different options for layout types - to a page.
Refer to the [Forms](/site_content_design/pages/forms) documentation on how to
add a form to a Page.

### Mark Commenting Pop-up Form

When interacting with a Dashboard, you can show your users a form after they click on a given Tableau data-point.
To learn ore about this, refer to the
[Mark Commenting](/embedding_using_analytics/data_manager/mark_commenting)
document.

### Dashboard Feedback

Curious what your users think about your dashboards?  You can add a single form to incorporate their feedback, gathering
the Dashboard URL automatically and tying it to their form-submission.  For details on Dashboard Feedback
[check out this outline](/embedding_using_analytics/data_manager/dashboard_feedback).


# Dashboard Feedback
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/dashboard_feedback

Enable user feedback collection on dashboards through Data Manager integration for improved user experience and insights.

In order to gather valuable insights from your audience about their experience using your Dashboards, Curator can
provide a simple and easy feedback mechanism for your users to submit their feedback, questions, and requests.  After
following the [Creating a Form](/embedding_using_analytics/data_manager/creating_a_form)
outline to build out your desired form, follow the guide below to integrate the Dashboard feedback in to your Dashboard
pages.

## Modifying your for to support the Dashboard URL

In order to gather the context of which Dashboard a user is providing feedback for, you'll need to add a new hidden
field that will store the Dashboard URL (the Curator URL).

### Adding a new Data Attribute

To add this attribute to your form:

1. Go to Data Manager > Data Attributes to set up the fields you want:
   <img alt="Create Data Attribute" />
2. In the Create Attribute page, set the name, description (optional), and the field type.
3. Make sure the field type is set to **Short Text**.
   <img alt="Select Short Text from Dropdown" />

Next, navigate to your Data Manager Group, and associate the Attribute you just created with your Group.

### Identifying the form to use in Portal Settings

There's one last step to set up your Dashboard Feedback.

1. Navigate to Settings > Tableau > Tableau Server Settings.
2. Find the Dashboard Feedback on the General tab.
3. For the **Feedback Form** select your Data Group.
4. For the **Dashboard URL** select the Short Text Data Attribute you created to store the the Dashboard URL.

<img alt="Settings" />


# Data Manager Basics
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/data_manager_basics

Introduction to Data Manager functionality for creating forms, capturing dashboard interactions and managing user-submitted data.

Data Manager allows you to create forms for users to fill out, and to store that data for retrieval later.  These forms
can even retrieve data-points that users click on in a Tableau Dashboard to be stored alongside the form they submit.
The data from these forms are then stored in Curator's database, where you can later retrieve that data for use in other
dashboards, or even for the same Dashboard itself, providing immediate feedback!

<Note>
  The built-in Documentation layout (Documentation Home / Documentation View) for Data Manager groups is deprecated
  and will be removed in a future release. If you are currently using this feature, please reach out to Curator support.
</Note>

## Data Manager Terminology

When starting with the data manger, it's important to understand core concepts, and thankfully we've made it pretty
simple for you.  Here's a quick mapping to understand the Data Manager components when building a form:

* Data Attribute = Individual Field/Input
* Data Group = Entire Form

or another way to view these is from how the data will be stored in the database:

* Data Attribute = Column
* Data Group = Table

## Enabling Data Manager

If you do not see "Data Manager" as a top-level menu option on the left-hand nav on the backend of Curator, you can
enable it by following these steps:

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the **Features** tab
4. In the "Functionality" section ensure the toggle for "Data Manager" is enabled and click the "Save" button.

That's it!  Curious what's under the "Manage Data" section on the left-hand nav?  That's where you can create or edit
existing rows in your Data Groups once they've already been added.

### Creating a Data Attribute

To create a data attribute, you can

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Data Manager** > **Data Attributes** section from the left-hand menu.
3. Click on the **New Attribute** button
4. Fill out the form keeping in mind how you'd like your end user to interact with this field, then click "Save".

#### Creating a Data Group

Once you have created all the data attributes you need for your user form, you can group them all together into a
Data Group for use with Data Manager features like
[Mark Commenting](/embedding_using_analytics/data_manager/mark_commenting).
To create a data group:

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Data Manager** > **Data Groups** section from the left-hand menu.
3. Click on the **New Group** button
4. Check all of the boxes next to the Data Attributes you wish to add to your Data Group then click "Create" or "Save".

## Migrating Data to another Database

If you would like to use a different database to store this data, we recommend using your preferred ETL process to
extract the data out of Curator's MySQL database.  Curator does not support any other databases beyond MySQL.

## Styling Data Manager Forms in Curator

If you would like to customize the background, text, or highlight colors for your data manager forms, you can do update
the colors in **Settings** > **Curator** > **Themes** section from the left-hand menu under the "Pages" tab.


# Exporting Data
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/exporting_data

Export data collected by Data Manager using various export options including CSV downloads for backend users.

You can export the data collected by the Data Manager by using the Data Manager Export options.

## Download as CSV - Backend Users Only

In the backend, you need an administrator account with Data Manager privileges.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Data Manager > Data Groups** section from the left-hand menu.
3. Click on the Data Group you want to export the data from.
4. Click **Download as CSV** to trigger the manual export.

## Download as CSV - Frontend Users

In the backend, you need an administrator account with Data Manager privileges.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Data Manager > Data Groups** section from the left-hand menu.
3. Click on the Data Group you want to export the data from.
4. Toggle on **Allow CSV Export on frontend** to enable the export feature on the front end.
5. Make sure the toggle **Hide List** is off.
6. Save.

Once the feature is enabled, as a frontend user:

1. Login to the front end (e.g. `http://curatorexample.com/`).
2. Navigate to the Data Group (aka form) that you want to export the data from
   (e.g. `https://www.curatorexample.com/data/your-data-group`).
3. Open the section Your Data Group List.
4. Click the **CSV** button to trigger the manual export.


# Field Calculations
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/field_calculations

Create calculated fields and formulas within Data Manager to transform and analyze collected data.

Performs some formula calculations on fields like addition, subtraction, multiplication, division, and concatenate with
a separator. For more on this check out our
[blog post](https://interworks.com/blog/morr/2018/11/14/portals-for-tableau-new-feature-spotlight-data-manager-calculated-fields/).

## Add a Field Calculation to a Data Manager Group

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Data Manager** > **Data Groups** in the left navigation.
4. Select the group you want to edit or click on the "New Group" button.
5. Click on the Field Calculation to add a new item.


# Importing Data
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/importing_data

Import external data into Data Manager from various sources for analysis and integration with existing datasets.

If you already have data collected somewhere else for your form and want to bring everything together in your Curator
table, use the Data Manager Batch Import option.

## Using Batch Import

In the backend, you need an administrator account with Data Manager privileges.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings > Data Manager > Manage Data** section from the left-hand menu.
3. Click on the Batch Import above the overview table.
4. Click on Schedule Import.
5. Select the Data Group for which the data should be imported.
6. Select the CSV file that holds your data.
7. Decide whether or not to trim white-spaces around the string values.
8. Click Import.

If you want to enable your frontend users to upload data:

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings > Data Manager > Data Groups** section from the left-hand menu.
3. Select the Data Group for which frontend users should be able to import data.
4. Enable **Batch Import** by using the toggle.
5. On the front end, a new section **Batch Import** appears. Click on it to expand the section.
6. Select the CSV file that holds the data.

### Format your CSV

* Add the headers of your table as the first row of your CSV file. Make sure it:
  1. Only has the Data Groups attributes' name in it.
  2. Uses the very same spelling.
  3. Has no spaces around the single attribute names.
* Have one row in the CSV for each row of data. Make sure it:
  1. Has as many attributes as defined in the Data Group.
  2. Has two consecutive commas, if you want to add a blank value.
  3. Do not add any quotes around the values.


# Mark Commenting
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/mark_commenting

Enable mark-based commenting functionality for data points and visualization elements to enhance collaborative analysis.

Curator can allow you to capture input from a user after they select a specific data point on your Dashboard.  Once you
associate a Data Group with a specific field/column from your Dashboard, any time a user clicks on a data-point that
contains that field, a pop-up will display asking the user to input information about that data-point.  This feature
allows you to capture comments on specific data points, projections or estimates, and even the ability to capture
feedback about the data itself.

This functionality requires that Data Manager management is enabled and at least one Data Group has been created.  See
the [Data Manager Basics](/embedding_using_analytics/data_manager/data_manager_basics)
section for more information on how to get things set up if you haven't already.

## Enable Mark-Commenting on a Dashboard

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Tableau** > **Dashboard** section from the left-hand menu.
3. From the list view, find the Dashboard you wish to add Mark Commenting to.
4. On the edit Dashboard page, click the "Mark Commenting" tab.
5. Select the Data Group you have created from the "Data Manager Group" dropdown you would like to display when the user
   clicks on your Dashboard.
6. In the "Mark Details" section, choose as many fields as you'd like from your Dashboard to trigger the
   "Mark Commenting" pop-up.  The logic here is that it must contain *all* fields you have chosen.
   * Alternatively, enable **Capture All Mark Fields** to automatically capture every field present on the
     selected mark, without needing to list them individually.  This is particularly useful when sending data
     to a webhook and you want the full mark context forwarded.
7. Click the "Save" button.

**Note:** Make sure the **dimension** name matches the spelling from your Dashboard. Measures or *Measure Names* cannot
be used as a connecting field.  This note does not apply when using **Capture All Mark Fields**, which captures
every field regardless of type.

Do you want a step-by-step guide with screenshots? Take a look [here](https://interworks.com/blog/jlyons/2018/10/01/portals-for-tableau-101-inline-commenting-on-dashboards/).

Once you've set up Mark Commenting on your Dashboard, you may want to connect to this data.  See the
[Connecting to Data Manager](/embedding_using_analytics/data_manager/connecting_to_data_manager)
section for more info on how to get started there.


# Sending Data to Webhooks
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/sending_data_to_webhooks

Configure Data Manager to automatically send collected data to external systems via webhook integrations.

When using mark commenting, you have the option to send the metadata to a webhook. This features allows you to send
mark commenting data to any webhook endpoint, instead of Data Manager.

To enable this feature,

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Portal Settings** > **Features** section from the left-hand menu.
3. Enable "Integration Automation" in the Functionality Section.
4. Save and refresh the page.
5. Navigate to **Integrations** > **Automation** > **API Relay** section from the left-hand menu.
6. Create a new API Relay. Use the webhook endpoint as the URL field.
7. "Outgoing Request Content" and "Incoming Request Validation" can be edited as needed for more complex webhook usage.
8. Once an API Relay is created, it needs to be selected for the necessary Data Group. For more information on Data
   Manager, take a look [here](/embedding_using_analytics/data_manager/data_manager_basics).
9. Visit **Data Manager** > **Data Groups** and select the necessary Data Group. Enable "Send to Webhook" and select
   the appropriate API Relay from the dropdown.
10. (Optional) Configure the **Allow Multiple Marks** toggle on the Data Group — see the section below for
    behavior details.
11. Visit **Tableau** > **Dashboards** and select the Dashboard you wish to enable. In the
    "Mark Commenting" tab, now select the Data Manager Group you wish to use (from step 9).
12. Data from the Data Manager Group form will now be sent to the webhook provided.

## Allow Multiple Marks

Each Data Group has an **Allow Multiple Marks** toggle (Data Manager > Data Groups > \[your group]) that
controls how the mark commenting form behaves when a viewer selects more than one mark on a Dashboard.

* **Default for all Data Groups: OFF.** Newly-created groups start with multiple-mark capture disabled, and
  Data Groups that existed before this feature was added are also OFF, so existing webhook integrations keep
  their original payload shape until an admin opts in.

When the toggle is **OFF**, only the most recently selected mark is captured — selecting additional marks
replaces the form contents rather than queuing them.

When the toggle is **ON** and a viewer selects multiple marks, the mark commenting modal becomes paginated: one
form per mark, with **Previous** / **Next** arrows and a `N of M` counter in the header. Each mark's form
fields are independent, so the viewer can enter different values per mark before submitting. Submitting
sends all marks in a single request.

## Webhook Payload Shape

The body sent to the webhook is the raw form submission (`Input::all()` from the request). Two fields drive
the integrator-facing shape: `metadata` and the per-attribute `attribute-{group_id}-{attribute_id}…` fields.

**Single mark** (or multi-mark toggle OFF):

* `metadata` is a JSON-encoded **object** — the captured Tableau field/value pairs for that one mark, plus
  `page_url`, `username`, `timestamp`.
* Each attribute is sent as `attribute-{group_id}-{attribute_id}` (no mark suffix).

**Multi-mark** (toggle ON, viewer selected more than one mark):

* `metadata` is a JSON-encoded **array** — one entry per selected mark, each entry shaped the same as the
  single-mark `metadata` object above (with an added `mark_index`).
* Each attribute is sent as `attribute-{group_id}-{attribute_id}-mark-N` where `N` is the zero-based mark
  index. Integrators consuming the webhook need to iterate the array (and/or the suffixed fields) rather
  than expecting a single object.

If you have an existing webhook endpoint and you enable **Allow Multiple Marks** on its Data Group, update
the endpoint to accept both shapes (or branch on whether `metadata` parses as an array vs. an object) before
turning the toggle on.


# Updating Data Groups
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/updating_data_groups

Modify existing Data Groups to add new fields and information requirements while preserving previously collected data.

If you have been using your Data Group and frontend users have input information diligently, you might find out that you
need extra pieces of information on top of what you are gathering to drive your analysis.

No problem, we have you covered by allowing you to simply add or remove the fields as required. Just follow these steps:

## Adding new Data Manager Attribute

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings > Data Manager > Data Group** section from the left-hand menu.
3. Click on the Data Group you want to alter.
4. Check more attributes (aka form fields) as required.
5. Click Save
6. Click on **Regenerate Summary Table** to reflect the changes in the respective database table.

Existing data entries will have an empty value in the newly added column.

## Remove an existing Data Manager Attribute

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings > Data Manager > Data Group** section from the left-hand menu.
3. Click on the Data Group you want to alter.
4. Uncheck attributes (aka form fields) as required.
5. Check **Permanently delete attribute data from items when unlinking from group?** underneath the Attributes selection
   section.
6. Check **Confirm permanently deleting attribute data from items** if you are sure you want to delete the attribute
   from your table.
7. Click Save
8. Click on **Regenerate Summary Table** to reflect the changes in the respective database table.

Existing data in the removed attributes will be lost after this process!


# User Commenting
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/user_commenting

Enable user commenting functionality on dashboards and pages through Data Manager integration for enhanced collaboration.

User Commenting provides the option to allow comments on individual dashboards, pages, and mixed content pages. The
Data Manager must be enabled to use the "User Commenting" feature. To enable for dashboards:

## Enable Curator-stored User Commenting

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Dashboards** in the left navigation.
4. Select the Dashboard you want to enable "User Commenting" on.
5. Click on the "Misc" tab.
6. Click to switch on the "Allow User Commenting" setting under the "Education" section and click the "Save" button.


# Web Data Connector (WDC)
Source: https://docs.curator.interworks.com/embedding_using_analytics/data_manager/web_data_connector_wdc

The Web Data Connector feature has been removed from Curator.

## Removed

The Web Data Connector (WDC) feature has been removed from Curator. Tableau deprecated Web Data Connectors
in Tableau Server version 2023.1, and the `/wdc` endpoint has been fully removed from the Curator codebase.

For more information on Tableau's deprecation, see
[Tableau's article on WDC deprecation](https://kb.Tableau.com/articles/Issue/web-data-connectors-deprecated-in-2023-1-release).

For data extraction from Curator, consider using the [Data Manager API](/embedding_using_analytics/data_manager/connecting_to_data_manager)
or [exporting data](/embedding_using_analytics/data_manager/exporting_data) instead.


# Caching Filter and Parameter Options
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/caching_filter_and_parameter_options

Optimize performance by configuring caching strategies for filter and parameter options to reduce load times.

Curator has the ability to populate the filter and parameter options from the Dashboard's data by using the
"Get Filter Options from data". This option is normally only enabled when you have a large number of options to
retrieve for the filter. The time to retrieve all these options can take a while if you have several hundred or several
thousands of options. While we can't speed up the initial time, we can make subsequent requests faster. To do this
enable "Cache filter/parameter options from data" after enabling "Get Filter options from data".

## To enable Cache Filter/Parameter Options

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on "Tableau" in the left-hand menu.
4. Click on the "Filters" or "Parameters" link on the left.
5. Click to switch on the "Cache filter options from data" under the Display Options section of a filter or parameter.
6. Select the desired cache time from the dropdown below the switch.
7. Click the "Save" button.


# Filter Apply Button
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/filter_apply_button

Configure apply buttons for filters to control when filter changes are applied to dashboard visualizations.

Each Filter and Parameter gets applied as soon as their values are changed. When you have many filters and parameters,
this can become time-consuming. To alleviate this issue we have created the "Apply" button. This button will not apply
any of your changes until you click on it.

## Enable the Filter Apply Button

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Tableau** > **Tableau Server Settings** in the left-hand menu.
4. Click the "General" tab at the top.
5. Expand the "Filters and Parameters" section.
6. Click to switch on the "Filters and Parameters Apply Button".
7. Click the "Save" button.

*Note*: Date Range Filters have their own apply button. As a result, they are applied
to the report immediately after this button is pressed. They do not respond to Curator's
Apply button.


# Filter Categories
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/filter_categories

Organize filters into logical categories for improved user experience and streamlined dashboard interaction.

Filter Categories can group filters/parameters together under a specific category. When the Dashboard filter pop out is
rendered on the right side, it will group all of the filters/parameters together under the filter category name. If
there are no filters displayed using the filter category, then it will not be rendered either.

## Enable Filter Categories

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left-hand menu.
4. Click on "Features" at the top of content page.
5. Expand the "Functionality" section and toggle on the "Filter Categories" button.
6. Click "Save" on the top right of the page.

## Create a filter category

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Filter Categories** in the left-hand menu.
4. Click the "New Filter Category" button.
5. Type in a display name in the "Name" field.
6. Click the "Save" button.


# Re-apply Filters on Tab-switch
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/filter_tab_switch

Control whether switching dashboard tabs carries active filters forward and reapplies them to the new tab, or lets each tab load independently.

When a Tableau workbook has multiple Dashboard tabs, the **Re-apply filters on tab-switch**
setting controls what happens to the active URL filter params when you switch between tabs.

***

## Where to find it

Navigate to **Settings** > **Tableau** > **Tableau Server Settings**, then open the **General**
tab and find the **Filters and Parameters** section.

The toggle is labeled **Re-apply filters on tab-switch** and is enabled by default.

***

## What it does

When the setting is on (default):

* The active URL filter params carry over when you switch tabs.
* All filters are reapplied to the destination tab's Tableau viz.
* If a filter was reset on the origin tab (set back to "All"), that reset also propagates
  to the destination tab so stale values do not persist.
* Filters you set on Tab A are still active when you switch to Tab B.

When the setting is off:

* On tab switch, the URL is corrected to reflect only the destination tab's previously
  set filters, with no filters sent to Tableau automatically.
* Each tab loads without active filter reapplication — the Tableau viz renders using its
  own default state.
* Filters set on Tab A do not reach Tab B.

***

## When to use it

Keep this setting on (the default) when filters should persist across all tabs in a workbook —
for example, a Region filter that applies meaningfully on every tab.

Turn this setting off when tabs cover different subject areas and should not inherit filters
from each other. For example, if an **Overview** tab is filtered by Region and a **Detail**
tab is filtered by Product Category, cross-tab carry-over may apply filters where they do not
belong and cause views to go blank.

Note that this is a global setting and affects all Tableau dashboards on the portal.

***

## Curator filter panel vs. Tableau filters

Filters from the **Curator filter panel** (sidebar or compact-container filters configured
in the Curator backend) and sticky filters are portal-level controls, so they are carried into
the URL on every tab whichever way this setting is configured. Whether they are also reapplied
to the destination tab's Tableau viz does depend on the setting.

| Filter origin                               | Setting on                   | Setting off           |
| ------------------------------------------- | ---------------------------- | --------------------- |
| Curator sidebar or compact-container filter | In URL, reapplied to the viz | In URL, not reapplied |
| Sticky filter                               | In URL, reapplied to the viz | In URL, not reapplied |
| Tableau click or sheet filter               | Carried over and reapplied   | Not carried over      |

With the setting off, no filters are sent to Tableau on tab switch. A sidebar or sticky filter
that appears in the URL will not be reflected in the destination tab's view until the page is
reloaded.

***

## Troubleshooting

### A filter I set on one tab is not appearing on another tab

This is expected when **Re-apply filters on tab-switch** is disabled. Each tab loads
independently and no filters are sent to Tableau on tab switch. If you need a filter to be
reapplied on every tab, enable the setting.

### My view is blank after switching tabs

If a view loads blank after switching tabs, a filter from a previous tab may be carrying over
and conflicting with the destination tab's data. Try disabling **Re-apply filters on
tab-switch** so that each tab loads without inheriting filters from others.

If the issue persists, check whether any
[Filter Blacklists](/embedding_using_analytics/filters_parameters/filters#filter-types)
are needed to prevent a specific filter from applying on a particular sheet.


# Filters
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/filters

Configure and implement filters to enable users to interactively control dashboard content and focus on specific data subsets.

Filters in Curator provide a powerful way to refine and control the data displayed in Dashboards, giving you expansive
capabilities beyond what is natively available with the tools you're embedding.  You can share filters across
multiple dashboards, placing your users back into their browsing context without having to constantly re-set filters,
even integrating filters across different BI platforms to unify this experience regardless of the tool you're embedding.

With this guide to Filters, we will explain how to configure and manage your filters, providing you with details on
which settings are best for all the scenarios you may encounter.

***

## To Create a filter

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Filters** in the left-hand menu.
4. Click the "New Filter" button.
5. Find the details of how to set up filters in the following [overview](#overview-of-filter-settings)

## Overview of Filter Settings

### Filter Fields

<img alt="Overview of the top section - Filter fields" />

* **Display Name**: The name visible to users when interacting with the filter.
* **Filter Type**: The type of filter (e.g. Single-select, Multi-select, Date) to control this field.
* **Filter Category** (optional): Allows you to group filters into sections in the filter pane. See the
  [Filter Categories Section](/embedding_using_analytics/filters_parameters/filter_categories)
  for more information.
* **Field Name Mapping**: Links the filter to a specific field in the analytics platform.
* Once your Field Name Mapping is verified, you will see a teal notice appear confirming the filter has been found
  on your BI platform. If your Field Name Mapping could not be verified, a yellow notice appears. Use the **Check
  All Tableau Site** button if you are certain that the field name exists on a different Site.

### Dashboards

* Assign filters en-masse to specific Dashboards. The filter will show as a Curator filter inside the Curator toolbar
  when you load a given Dashboard. You can also add filters to a specific Dashboard via the "Filters" tab on the edit
  Dashboard page.

### Secondary Data Source

In most cases, this toggle should remain **off**. It is only required in specific scenarios where filtering needs to
be applied to a field that is not part of the primary data source on your Tableau sheet but comes from a secondary
data source. You can identify secondary data source fields in Tableau by the orange check mark in editing mode.

If you need to filter on a field marked with this orange check mark:

1. Enable the **Specify a Secondary Data Source** toggle.
2. Enter the name of the secondary data source (as displayed in the workbook) into the input field that appears.
   The filter will then be sent to Tableau in the format of `datasource_name.filter_field_name`.
   This ensures that the filter is correctly applied across your data sources.

## Display Options

1. **Sticky Filter**
   * Saves filter selections per user for consistent filtering across Dashboards. This
     is using browser cookies which will be applied to any Dashboard that uses the specified
     field name from the specified field name mapping. I.e. it is not only applied to the
     Dashboards selected in the [Dashboards](#dashboards) section above.

2. **Add "All" Option**
   * Adds an "All" selection option for Single Select filters. If there is no "All" option for the single select
     filter, the first value of the field will be shown even if not yet selected. Once you started filtering you
     can only reset the filter by using the toolbar button "Reset".

3. **Get Filter Options from Data**
   * Pulls options directly from the data source to populate the filter options for a given dropdown. This will
     slow down the Dashboard's load time if the Dashboard contains a lot of data. This process can be
     sped up by enabling "Specify Filter Sheet" from a Dashboard's backend settings. See the
     [Specify Filter Sheet Section](/embedding_using_analytics/filters_parameters/specify_filter_sheet)
     for more information.  If this field is disabled, you must add items via the Options list (manually)
     otherwise the filter will contain no options for users to select and they will only see "No results found".

4. **Cache Filter Options**
   * This saves the dropdown options via Curator's cache on a user basis and will retrieve options in a more
     performant manner.  However, the list of options may be stale given the time you set the cache to. The cache
     begins the first time a user loads the options, and is not related to the underlying Dashboard's data-refresh
     schedule, so ensure you only enable this setting for dropdowns that rarely see new data.
   * **Cache Expiration Options**: 4 Hours, 1 Day, 1 Week

5. **Filter-Blacklist**
   * If you have a Filter Blacklist set up, it can be reused by toggling on **Use Filter-Blacklist Group**.
     Once enabled, you can select from you existing Blacklist Groups to be applied on this filter.
   * Note, if you either don't have a Filter Blacklist Group set up or only want specific sheets to be
     blacklisted, i.e. the filter to not be applied on this sheet, add the sheet names as individual items
     to the **Sheet Blacklist** list.
   * More information in Filter Blacklists can be found under [Hidden Sticky Filters
     and Parameters](/embedding_using_analytics/filters_parameters/hidden_sticky_filters_and_parameters)

## Filter Types

### Single Select

* Allows the frontend user to select only a single value for this filter.

### Multi-Select

* Allows the frontend user to select multiple values for this filter.

### Date

* Allows the frontend user to pick a date from the standard date picker widget. The date format
  is displayed based on the users locale settings. To successfully filter for dates make sure that the
  Tableau Dashboard is published with the correct specific locale settings or with automatic locale detection.

### Date Range

* Allows the frontend user to pick a start and an end date from the standard date picker widget. The date
  format is displayed based on the users locale settings. To successfully filter for dates make sure that the
  Tableau Dashboard is published with the correct specific locale settings or with automatic locale detection.

### Relative Date Filters

* Works similarly to Tableau's Relative Date Filters where you get a slider to dynamically update to show a
  time period relative to when you open the view, such as the current week, the year to date, or the past 10 days.
  Relative date filters make it easy to create views that always show the most recent data ([cf. Tableau Relative
  Date Filters](https://help.tableau.com/current/pro/desktop/en-us/qs_relative_dates.htm)).
* When you use a Relative Date Filter you will get more options to configure your filter:
* **Direction**: Filter by Past or Future.
* **Scale**: Choose Days, Months, Quarters, or Years.
* **Range**: Specify the maximum relative date range.

### Boolean

* Allows the frontend user to select between True and False.

## More on Filters

### URL Filters

* You can apply filters and parameters by appending `key=value` pairs to URLs to pre-filter Dashboards. E.g.
  my-Curator.com/Dashboard/superstore?region=North will pre-filter my Superstore Dashboard to only show the North region.
* Automatically applied when using Curator or Tableau filter UI.
* **Important**: Disabling "Ignore filter and parameter changes from Dashboard" prevents
  [Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder)
  from capturing filters.

### Evaluation of Filters

In this order, filters are evaluated:

* **URL filters** - Values that are appended to the Curator URL in your browser (e.g. `?Region=South`)
* **Preloaded sticky filters** - Filters identified via the Tableau Server Settings.
* **Cookie-based sticky filters** - Browser-session stored filters, also managed via Tableau Server Settings.
* **Published filter settings** - The default state of the Dashboard.

In case of any conflicting values, the first evaluation is considered the correct one.  For example, if one of your
users has been browsing around and setting their **Region** filter to *North* and that drops a *Cookie-based sticky
filter* in their browser, when they return to the page, the filter will be evaluated as `Region=North` by default.
However, if they are emailed a link from a colleague sharing an insight and the URL is sent over with `?Region=South`
when they click on the link, the Dashboard will be filtered to Region=South since *URL filters* are evaluated first
taking precedence over the *Cookie-based sticky filters*

***

## Troubleshooting Filters

### Filter Options are not visible

* Verify that either "Get Filter Options from Data" or the manual Options list is configured.

### I want to apply a filter across Dashboards but I do not want to show the Curator Filter UI

* Use [Hidden Sticky Filters](/embedding_using_analytics/filters_parameters/hidden_sticky_filters_and_parameters)
  instead

### My view is empty after I switched tabs on my dashboards

* If your view loads briefly and then suddenly turns blank, then a filter is probably being applied that should
  not be applied. That can happen if you either track filter and parameter changes in the url (a) or you have a
  sticky filter enabled (b) which should not be applied to this view.
  * a) Turn on **Ignore Filter and Parameter Changes from Dashboard** on the Dashboard level which
    will stop adding the changes to the url. When you switch tabs, the filter and parameter actions need to be
    defined in the Workbook itself. However please note, that turning this on will break Report Builder's functionality.
  * b) Apply Filter Blacklists to prevent filters being applied on specific sheets. However, this
    does not currently work with Hidden Sticky Filters and Parameters.
  * c) Enable **Re-apply filters on tab-switch** globally via **Settings → Tableau → Tableau
    Server Settings → General**. This setting is on by default. When enabled, filters and parameters applied during
    a session are carried over to other dashboards on tab switch. When disabled, each tab keeps its
    own isolated filter state: switching to a new tab restores only the filters that were applied on
    that tab. See [Re-apply Filters on Tab-switch](/embedding_using_analytics/filters_parameters/filter_tab_switch)
    for full details.

### My sticky filters stop applying after I am asked to log back in

* Sticky filters are stored in your browser, not in your Curator login session. A session timeout, or being asked
  to log back in, does not clear them by itself. Selecting the filter value again writes it back to the browser and
  applies on the next Dashboard load.
* They are stored as *browser-session* values, so they last until the browser is closed **completely** — closing a
  tab is not enough, but quitting and reopening the browser discards them. This is the most common reason sticky
  filters appear to reset "randomly" at around the same time as a login prompt: both are triggered by the same
  break in browsing, rather than one causing the other.
* Anything that discards site cookies discards sticky filters with them. Check for private/incognito windows,
  "clear cookies on exit" browser settings, strict tracking-protection modes, and device cleanup tools.
* The toolbar **Reset** button intentionally erases the stored sticky filter and parameter values for the
  Dashboard. If users report that filters stop sticking, confirm that Reset is not being clicked before reloading.
* Switching Tableau Site or Project is separate and *is* tied to the login session. The selected Site/Project
  controls which projects and workbooks are listed in your menus, and it reverts to showing all of them when the
  session expires. That changes which Dashboards you see listed, but it does not clear your sticky filter values.

### Date Filters show differently for my global users

* That is not necessarily an issue because Curator can handle locale date formats.
* Locale-specific formats (e.g., DD/MM/YYYY, MM/DD/YYYY) depend on:
  * Browser language settings.
  * Tableau User Language and Region settings.
* As long as your Workbook is flexible with date formats, Curator will handle dates for your different users and
  present them the format they are used to based on their settings.

### Date Filters do not filter properly

* This is mostly due to a locale mismatch: Ensure browser and Tableau settings align. You have three options:

1. When you have multiple regions that are working with your Dashboard, make sure that the Workbook's locale is
   set to automatic when published to Tableau. It will then adjust to your users location which Curator will also
   look pick up and then send the date in the expected format.
2. If you require a specific format you can also force the browser to use the specific locale date format instead
   which again Curator will pick up.
3. You can also use dates in YYYY-MM-DD format and it will ignore any browser or Workbook settings and just handle
   dates correctly in that format.


# Hidden Sticky Filters and Parameters
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/hidden_sticky_filters_and_parameters

Configure invisible persistent filters and parameters that remain active across user sessions and dashboard navigation.

Hidden sticky filters and parameters are used to remember the filter/parameter values a user selects across the system,
without showing up in the filters list on a Dashboard.

You can blacklist sheets for the Hidden Filter to not apply to. The name should match the sheets' name in Tableau.
You can also blacklist entire Dashboards by using the Dashboard name instead of individual sheet names. This is useful
when you have a Dashboard with many sheets and want to exclude all of them from a filter without having to list each
sheet individually, or when you want to prevent filters from applying to any part of a specific Dashboard.

## To create a hidden sticky filter/parameter

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Tableau** > **Tableau Server Settings** in the left-hand menu.
4. Click the "General" tab at the top.
5. Expand the "Sticky Filters and Parameters" section and toggle on "Use Hidden Sticky Filters".
6. Click to add a new item under hidden sticky filters or hidden sticky parameters section.
7. Enter the name of the filter/parameter.
8. Click the "Save" button.

## Filter Blacklists

If you have individual sheets or entire Dashboards that a filter should not be applied to, Curator's Filter Blacklists
can help here. Curator provides two types of filter blacklists to control where filters are applied within Tableau
Dashboards: filter-specific blacklists and global sheet-specific blacklists. Both types support blacklisting individual
sheets by sheet name or entire Dashboards by Dashboard name.

### Filter-Specific Blacklists

A filter-specific blacklist allows you to prevent a specific Curator filter from being applied to selected sheets or
entire Dashboards. This requires the Curator filter to be present in the front-end.

To configure a filter-specific blacklist:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Filter** > select the filter that should not be applied to all sheets.
4. In the **Display Options** section, add one item to the **Sheet Blacklist** per sheet or dashboard you want to
   exclude from the filter. To blacklist an entire dashboard, use the dashboard name as it appears in Tableau. To
   blacklist an individual sheet, use the sheet name.

If multiple filters need to be excluded from the same set of sheets or dashboards, you can create a reusable **Filter
Blacklist Group**:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backen`).
2. Log in if prompted.
3. Click on **Tableau** > **Filter Blacklists**.
4. Create a new blacklist group.
5. Name your blacklist group.
6. Add one item per sheet or dashboard you do not want the filter to be applied to to the Sheet Blacklist. Use the
   dashboard name to exclude an entire dashboard, or use individual sheet names to exclude specific sheets.
7. Navigate to your Filter to apply the Filter Blacklist Group. Click on **Tableau** > **Filter** > select the filter
   that should not be applied to all sheets.
8. In the **Display Options** section, toggle on **Use Filter Blacklist Group**.
9. Select the Filter Blacklist group that you created in steps 3-6.

### Global Filter Sheet Blacklists

If you need to exclude sheets or entire dashboards from a hidden sticky filter, a global filter blacklist must be used.
This applies to filters that are not explicitly present in the Curator UI but are set as sticky and therefore influence
the Dashboard on load with the last value set applied. Or because Hidden Sticky Filters or Parameters are enabled.

To configure a global filter blacklist:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backen`).
2. Log in if prompted.
3. Click on **Settings** > **Tableau** > **Tableau Server Settings**.
4. Open the Filters and Parameters section.
5. Add the respective sheets or dashboard names to the Global Filter Sheet Blacklist. To blacklist an entire dashboard,
   add the dashboard name as it appears in Tableau.

If you using Filter Blacklist is slowing down your Dashboard load performance, there is a workaround within
Tableau. Following the below steps is more performant on especially large Dashboards.

1. In Tableau Desktop (or Tableau Server Edit Mode), go to the sheet that the filter should not be applied on.
2. Duplicate the data source the filter field(s) comes from.
3. Replace the existing fields on your sheet with the fields from the duplicated data source.
4. **Rename the filter field**, regardless of whether used on your sheet or not. ***Note:*** If you are not using the
   filter field on your sheet, you may as well delete it from your duplicated data source. By renaming/deleting it, you
   ensure that the filter request will have no effect on this specific sheet.
5. Repeat for all other fields the sheet should not be filtered by.
6. Repeat for all sheets that should not listen to the filter(s).
7. Republish your Dashboard.


# Parameters
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/parameters

Set up parameters to control dashboard behavior and calculations, enabling dynamic user interactions with analytics content.

Parameters are used for various purposes within a Dashboard. The system provides a user-friendly way to enter and
change the parameter values for dashboards. Parameters can even be shared with more than one Dashboard.

## To create a parameter

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Parameters** in the left-hand menu.
4. Click the "New Parameter" button.
5. Enter the name of the parameter you want to be shown to your users in the "Display Name" field.
6. Enter the name of the parameter from the Dashboard in the "Parameter Name" field. This field text should be edited
   to match the field name in the data exactly. If there are any trailing white-spaces those will be removed on saving so
   you will need to remove them from the data name.
7. Select the parameter type.
8. Select the filter category if desired. See the [Filter Categories Section](/embedding_using_analytics/filters_parameters/filter_categories)
   for more
   information.
9. Select existing dashboards to add the parameter to them.
10. If you want to, enter a default value for the parameter to load the Dashboard with initially.
11. If you want the parameter value to be remembered from one Dashboard to the next, turn on the sticky parameter feature.
12. If you want to get the parameter options from the Dashboard's allowable values list, turn on that feature.
13. If you want to get the parameter options from the Dashboard's data, turn on the "get parameter options from data"
    feature. Note that this will be slow if the Dashboard contains a lot of data.
14. Add parameter options if not getting the options directly from the Dashboard.
15. Click the "Save" button.

## Or add a parameter to a Dashboard from the Dashboard

1. While editing the Dashboard, click on the "Misc" tab.
2. Expand the "Filters & Parameters" section.
3. Select the parameter(s) that are applicable to the Dashboard.
4. Click the "Save" button.

## To apply a Parameter

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Open the filter menu on the right side of the screen.
5. Select or enter the value of the parameter.

### Multi Select Parameter Controls

Currently, Tableau does not offer multi-select-parameter controls. Instead, you can select one parameter value at a
time or type the long names by hand. In Curator, you can set up a parameter to allow multi-selection of your parameter
values without typing everything in.

1. Navigate to Tableau Desktop (or Tableau Server Edit Mode), and go to the sheet that the parameter should be applied to.
2. Create the parameter you need, and make sure
   * the Data type is a ***String***
   * the Current value is set to ***(ALL)***
   * the Allowable values is set to ***All***
3. Create a calculated field
   * `[param name]='(ALL)' OR CONTAINS([param name], [values field])`
   * Drag the calculated field onto the filter shelf and allow only ***True***
4. Publish Dashboard.
5. Do the steps described above to create a parameter in Curator backend, make sure
   * the Parameter type is ***Multi-Select***
   * toggle on ***Get parameter options from a field in the data***
   * enter the name of \[values field] (see 3.a) in ***Field Name*** input field
6. Click the "Save" button

### Step-by-step Guide

You can also follow the
[step-by-step guide](https://interworks.com/blog/tladd/2018/07/16/5-steps-to-enabling-a-multi-select-parameter-control-in-tableau/)
with screenshots that Tanner put together.


# Preloading Filters and Parameters
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/preloading_filters_and_parameters

Improve user experience by preloading filter and parameter values to reduce wait times during dashboard interactions.

## Setup

When you filter your Tableau Dashboards in Curator, this is typically done through the Tableau JavaScript API after the
Dashboard has loaded. This post-load filtering process will cause the Dashboard to refresh. If the filter or parameter
values are already known before the Dashboard is loaded, though sticky filters/parameters or because you want to
explicitly define them, you can take advantage of Preload Filters and Parameters. This feature injects the filter and
parameter values directly into the Dashboard’s initial load request (within the HTML), rather than applying them via
JavaScript afterward. The result is a faster, cleaner user experience with no visible reload.

When using Tableau's Connected Apps for the Embed authentication ([more details on Connected Apps](/creating_integrations/tableau_connection/embed_authentication))
you can no longer preload filters and parameters by appending them to the Tableau Server Dashboard URL on the
edit page of a Dashboard. Instead you can specify them by following these steps:

1. Navigate to your Curator backend > Tableau > Dashboards.
2. Select the Dashboards you want to define filters or parameters for that should be applied on load.
3. Switch to the Filters tab and open the **Preloading Filters & Parameters** section.
4. Add an item and enter the filter's/parameter's name into the name field as shown in the datasource/in the workbook.
5. Enter the value that you want the filter/parameter to preload with into the value field. You can leave it blank if
   you want the Dashboard to listen for possible preload options given through the Curator URL or sticky filters/parameters.
6. Specify whether this is a filter or a parameter in the type field.
7. Save the Dashboard.

> **Note:** When trying to filter on secondary datasources you'll likely see unexpected behavior.
> This is due to Tableau's embedding limitations. The JavaScript API still works on secondary
> datasources, but preloading may not function as expected.

When using Tableau's Trusted Ticket authentication (Attention: Deprecated!) you can append the name-value pairs to the
Tableau Server Dashboard URL directly.

## Preload Behavior

In the value field, you can enter the specific value you want the filter or parameter to preload with when the Dashboard
is initially rendered. This value will be directly injected into the HTML and used during the first load of the
visualization. No JavaScript will be executed to apply the filter/parameter, i.e. no reload will happen.
If you leave the value field blank, Curator will look for a matching value from other sources to optimize your initial
load experience, such as sticky filters/parameters saved from previous analysis steps or values passed through the
Curator URL (e.g., ?Region=West).
This makes the preload feature flexible: you can hardcode a default if needed, or allow Curator to dynamically detect
and apply a value based on your user's context.

### Full Domain Loading for Curator Filters

*This feature is only available when using [Connected Apps](/creating_integrations/tableau_connection/embed_authentication)
to authenticate to your Tableau Server.*

Curator gives you the flexibility to control whether Curator filters load with the full domain of
available values or only the subset of preloaded values. This setting can be configured individually for
each Dashboard.

To configure this behavior:

1. Navigate to your Curator backend > Tableau > Dashboards.
2. Select the Dashboard you want to configure.
3. Switch to the Filters tab and open the **Preloading Filters & Parameters** section.
4. Use the toggle **Preload Filters with Full Domain Values** to enable full domain loading or disable it to show
   only filtered values.

When enabled, users will see all possible filter values, maintaining full filtering capability while still benefiting
from the performance improvements of preloaded filters.

**Note**: To use the full domain values feature, ensure your field is placed on at least one filter shelf in your
Dashboard. The filter doesn't need to be visible or have a value applied, just Tableau needs to recognize it as a filter.

## Migration notice

If you used the Tableau Server Dashboard URL parameters you do not need to move everything manually once you are switching
to Connected Apps. They should be migrated for you once you upgrade to version when they became available. To have the
type automatically declared you will need to have Tableau's Metadata API enabled.
In case you want to rerun the migration and make sure filters and parameters are declared correctly do:

1. Run the migration command in the browser's address bar by just appending **/up** to you Curator domain.
2. In the console on your server, navigate to the root directory and run:

   ```php {/*cspell:disable-next-line*/} theme={null}
   php artisan tableauviz:updatepreloadsettings
   ```

   This will try to connect to the primary's Tableau Metadata
   API and check whether the specified names are parameters, otherwise they will be declared as filters.

To maintain previous functionality, we decided to migrate existing preload filters to not load the full domain of values.
However you can easily adjust the setting per Dashboard according to your needs.

## Metadata API Cache

If Tableau's Metadata API calls are slow, you can cache their results to reduce repeated queries to the Tableau Server.
Configure this under **Backend > Settings > Tableau > Tableau Server Settings > Advanced tab**, using the **Metadata
API Cache** field.

> **Note:** This setting applies to On-Prem (Tableau Server) deployments only. It is not available for Tableau Cloud
> deployments.

The following cache durations are available:

| Option   | Cache Duration |
| -------- | -------------- |
| Off      | 0 hours        |
| Minimal  | 1 hour         |
| Some     | 3 hours        |
| A Lot    | 18 hours       |
| Full Day | 24 hours       |

> **Note:** The internal connectivity check caches a positive result for a minimum of 1 hour, regardless of the value
> selected above. This check does not require instant feedback, so a longer cache is acceptable even when the Metadata
> API Cache is set to Off. A negative result is re-checked after 2 minutes instead, so a brief outage or a credential
> being rotated does not switch off Metadata API lookups for the rest of the cache window.


# Specify Filter Sheet
Source: https://docs.curator.interworks.com/embedding_using_analytics/filters_parameters/specify_filter_sheet

Configure which specific worksheet or sheet should be used as the source for filter controls and options.

Curator provides the ability to get your filter options from the data. The standard dynamic filtering looks at the first
worksheet loaded. However, you may have multiple data sources compromising your Dashboard or a slow-loading worksheet
you want to avoid. Use the steps below to specify a worksheet to improve load time and narrow the scope of the data
that Curator has to retrieve to populate your filter values.

## To enable Specify Filter Sheet

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Dashboards** in the left-hand menu.
4. Click on the Dashboard you want to edit.
5. Click the Misc tab.
6. Toggle on the Specify Filter Sheet option in the Filters & Parameters section.

This will display two additional fields "Filter Worksheet" and "Use Summary Data". The "Filter Worksheet" field will
allow you to specify the name of the worksheet to pull from. The switch for "Use Summary Data" uses a quicker API call
that pulls from the Summary Data rather than all of the Underlying Data. To determine if what you're looking for is in
the Summary Data you will need to View Data within your workbook on Tableau Desktop.


# Adding a Power BI Report
Source: https://docs.curator.interworks.com/embedding_using_analytics/power_bi_reports/adding_a_power_bi_report

Add and configure Power BI reports in Curator for seamless access via embedding.

Curator enables you to embed Power BI reports as a seamless part of your portal, providing your users with a unified
analytics experience, streamlining access to critical insights.

## Prerequisites

Before adding Power BI reports to Curator, ensure you have
[established your Power BI connection](/creating_integrations/power_bi_connection/curator_connection) and have reports
published to a Power BI workspace.

## Creating a Power BI Report in Curator

To add a new Power BI report to your Curator portal follow the steps below:

### Navigate to Power BI Reports

1. <BackendNavPath />
2. Click the **New Report** button
   <Frame>
     <img alt="Add new Power BI report from list page" />
   </Frame>
3. Fill out the details in the **Create Power BI Report** form:

   <Frame>
     <img alt="Create new Power BI report" />
   </Frame>

   * **Workspace**: Select the Power BI workspace containing the report.
   * **Report**: Select the specific report to embed.
   * **Title**: This appears in navigation menus and page titles - can be different from the Power BI report name.

The display options will allow you to control how the report is scaled (the **Display Option**), the appearance of the
toolbar, the persistence of filters, the appearance of the filter pane as well as the Power BI report Page Navigation.

### Display Settings Reference

The **Display** tab controls how the embedded report is scaled and how its page navigation renders:

| Setting                      | Description                                                                                                                                                                                                                                                                                             | Default        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Display Option**           | Controls how the embedded report is scaled on desktop viewports: **Fit to Page**, **Fit to Width**, or **Actual Size**. Leave it on **Global Default** to inherit the [tenant-wide default](#default-display-option). Applies to desktop viewports only — mobile always uses the single-column layout.  | Global Default |
| **Page Navigation**          | Show or hide the page navigation controls on the report.                                                                                                                                                                                                                                                | On             |
| **Page Navigation Position** | Controls where the page navigation pane renders: **Bottom** or **Left**. Only appears while **Page Navigation** is enabled. Leave it on **Global Default** to inherit the [tenant-wide default](#default-page-navigation-position). Has no effect when **Enable actionbar** is on (see the note below). | Global Default |

The **Report** tab exposes the following display toggles:

| Setting                       | Description                                                                                                                                                                                        | Default |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Show filter pane**          | Show or hide the collapsible filter pane on the report.                                                                                                                                            | On      |
| **Enable actionbar**          | Show or hide the Power BI action bar. Enabling Copilot forces the action bar to stay visible, and the toggle is disabled while Copilot is on.                                                      | Off     |
| **Enable status bar**         | Show or hide the Power BI status bar at the bottom of the report, which carries the zoom controls.                                                                                                 | Off     |
| **Enable persistent filters** | Preserve a user's filter selections between sessions, so each user's filter and slicer choices are restored the next time they open the report.                                                    | Off     |
| **Enable Copilot**            | Show the Power BI Copilot pane. Enabling it automatically enables the action bar — see [Enabling Copilot](/embedding_using_analytics/power_bi_reports/enabling_copilot) for the full requirements. | Off     |

<Note>
  Not every Power BI SDK setting is surfaced as a Curator option. The following are **not** currently configurable
  through Curator's interface:

  * **Zoom level** — a programmatic zoom override
  * **Bookmarks pane** — showing or hiding the bookmarks panel

  If you need one of these settings, submit a feature request through your support channel.
</Note>

Optionally, explore the Discovery tab and the rest of the Display tab (thumbnail and tutorial settings) to further
customize how the report appears and is found by users or linked to other content across your site.

Be sure to save your report before navigating away from the page.

## Default Display Option

The **Display Option** on an individual report (or dashboard) defaults to **Global Default**, which follows a
tenant-wide setting. To set that default:

1. <BackendNavPath />
2. Set **Default Display Option** to **Fit to Page**, **Fit to Width**, or **Actual Size**. This value is applied to
   every embedded Power BI report and dashboard that is left on **Global Default**.

An individual report or dashboard that specifies its own **Display Option** overrides this global default. If neither
the per-item option nor the global setting is configured, embeds fall back to **Fit to Width**. As with the per-item
option, this default applies to desktop viewports only; mobile viewports always use the `oneColumn` layout.

<Note>
  **Fit to Page applies to reports only.** Power BI dashboards do not support the Fit to Page layout, so a dashboard
  falls back to **Fit to Width** whenever **Fit to Page** is the resolved option. For this reason the per-dashboard
  **Display Option** offers only **Fit to Width** and **Actual Size**.
</Note>

## Default Page Navigation Position

The **Page Navigation Position** on an individual report defaults to **Global Default**, which follows a tenant-wide
setting. To set that default:

1. <BackendNavPath />
2. Set **Default Page Navigation Position** to **Bottom** or **Left**. This value is applied to every embedded Power BI
   report that has **Page Navigation** enabled and is left on **Global Default**.

An individual report that specifies its own **Page Navigation Position** overrides this global default. If neither the
per-report option nor the global setting is configured, embeds fall back to **Bottom**, which matches the standard
Power BI Service appearance.

<Note>
  **Page navigation applies to reports only.** Power BI dashboards do not have pages, so this setting has no effect on
  them, and no **Page Navigation Position** option appears on a dashboard.
</Note>

<Note>
  **The action bar overrides this setting.** When a report has **Enable actionbar** on, Power BI always places page
  navigation on the left, and the **Page Navigation Position** value is ignored for that report — this is a Power BI
  platform limitation, not a Curator setting. To use **Bottom** (or to switch to **Left** yourself), disable the action
  bar on the report. See Microsoft's
  [embedded report settings limitations](https://learn.microsoft.com/en-us/javascript/api/overview/powerbi/configure-report-settings#considerations-and-limitations).
</Note>

## Mobile Layout

When the viewport is 768px or narrower, Curator automatically switches Power BI
reports to the mobile-optimized `MobilePortrait` layout and `oneColumn` page view. This overrides the configured
[Display Option](#default-display-option), which only applies to desktop viewports. The mobile layout uses the layout
authored in Power BI Desktop or the Power BI Service. If a report does not have a mobile layout, Power BI falls back
to the standard landscape layout.

<Note>
  To take full advantage of this feature, author a mobile layout for your Power BI report in Power BI
  Desktop/Service. Without one, the report will still render on mobile but will use the default desktop layout scaled
  to fit the screen.
</Note>

Power BI dashboards also switch to `oneColumn` page view on mobile viewports but do not use `MobilePortrait` since
dashboards do not support mobile layouts.

## Adding Reports to Navigation

After creating a report, [add it to your site's menu](/site_content_design/menus/menu_items) for easy access and
automated authorization.

## Adding Reports to Pages

Once a Power BI Report has been added to Curator it can also be added to pages for a more dynamic layout.  Embed Power
BI reports in custom pages [using the Page Builder](/site_content_design/pages/power_bi_report).

## Security Considerations

Curator utilizes the permissions set within your Power BI tenant including both workspace-level permissions as well as
direct-access permissions.

### Workspace-Level Access

When a user has access to a workspace, they automatically have access to all reports within that workspace.
Curator checks workspace access to determine report visibility.  Due to performance concerns we strongly recommend
utilizing workspace-level access whenever possible.

### Direct Report Access

If a user does not have access to a workspace, Curator will check for direct access permissions to individual reports. This
allows for more granular control over report access but can lead to performance issues due to limitations in the Power
BI APIs.


# Enabling Copilot
Source: https://docs.curator.interworks.com/embedding_using_analytics/power_bi_reports/enabling_copilot

Enable the Power BI Copilot AI assistant pane in embedded reports for natural-language data analysis within Curator.

Curator does not include its own AI engine and does not support third-party AI agent plug-ins or add-ins. Any AI
capabilities available to your users come from the embedded analytics platforms Curator integrates with. Currently,
the only supported AI feature is **Power BI Copilot**, described below.

Copilot is Microsoft's AI assistant for Power BI, enabling users to explore and analyze report data using
natural-language prompts. It is currently the only built-in AI feature available in Curator, and it requires
either Power BI Premium or paid Fabric capacity in your workspace. Curator supports displaying the Copilot pane
within embedded reports, allowing users to interact with Copilot directly from your portal.

## Requirements

Before enabling Copilot in Curator, ensure the following requirements are met in your Power BI environment:

1. **Copilot is available in your Power BI tenant.** This feature requires an active Copilot tenant switch and either
   Power BI Premium or paid Fabric capacity in your workspace. If you can see the Copilot button in the action bar when
   viewing the report in the Power BI service, then your tenant meets this requirement.

2. **The `MLModel.Execute.All` permission is added to your Azure AD app registration.** This permission allows the
   embedded report to communicate with the Copilot service. See the
   [Azure App Setup - API Permissions](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/azure_app_setup#api-permissions)
   guide for instructions on adding API permissions to your app registration.

## Enabling Copilot on a Report

Once the requirements above are met, follow these steps to enable Copilot on a report in Curator:

1. <BackendNavPath />
2. Click on the report you want to enable Copilot for, or create a new report.
3. On the Report tab, toggle **Enable Copilot** to on.

<Note>
  Enabling Copilot will automatically enable the action bar, as the Copilot pane is accessed through it. While Copilot
  is enabled, the action bar cannot be independently disabled.
</Note>

1. Click **Save**.

Users will now see the Copilot button in the action bar when viewing this report in Curator.


# Capture Slides Using Custom Views
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/custom_view_capture

Capture Report Builder slides with the exact filter state shown on screen, including honored filter exclusions.

Report Builder normally captures a Tableau dashboard by asking Tableau for a static image of that dashboard's URL.
That request applies every filter in the workbook to every sheet in the workbook, regardless of whether an individual
filter was configured to apply only to selected worksheets. As a result, a filter that was deliberately excluded from
a dashboard can still appear to have been applied in the captured slide.

The **Capture Slides Using Custom Views** setting switches Report Builder to an alternative capture method that
preserves the exact filter state the user is looking at, so filter exclusions are honored in the captured slide.

## When to Use This Setting

Enable this setting if your users report that captured slides show filtered data they did not expect, and the filters
in question were configured to apply to only some of the worksheets in the workbook.

For example:

* A workbook contains Dashboard A and Dashboard B.
* Dashboard A has a "Region" filter that is excluded from Dashboard B.
* A user sets "Region = West" on Dashboard A, then captures Dashboard B as a slide.
* With the standard capture method, the slide for Dashboard B is filtered to "Region = West" even though the filter
  was excluded from that dashboard.
* With **Capture Slides Using Custom Views** enabled, the slide for Dashboard B is captured unfiltered, matching what
  the user sees on screen.

<Note>
  If snapshots do not match the dashboard view for a different reason — for example, filters applied inside the
  dashboard are not being captured at all — see
  [Troubleshooting: Snapshot Does Not Match the Dashboard View](/embedding_using_analytics/report_builder/troubleshooting#5-snapshot-does-not-match-the-dashboard-view)
  first. This setting only addresses filters being applied to sheets that excluded them.
</Note>

## Requirements

* [Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder) must be enabled.
* The Tableau connection must use **Connected Apps** authentication, which captures each slide under the viewing
  user's identity. See [Embed Authentication](/creating_integrations/tableau_connection/embed_authentication) for setup
  instructions.
* [Scheduled Reports](/embedding_using_analytics/report_builder/scheduled_reports) must be turned **off**. See the
  restrictions below.

## Restrictions

**Scheduled Reports and Capture Slides Using Custom Views cannot both be enabled.** This is enforced in Portal
Settings: while Scheduled Reports is on, the **Capture Slides Using Custom Views** toggle is displayed but cannot be
changed. Scheduled Reports must be turned off and saved before the toggle becomes editable.

The two are mutually exclusive because this capture method requires a signed-in user viewing the dashboard in their
browser at the moment the slide is captured. Curator's scheduled sends run unattended, with no user session to
capture from, so a scheduled report cannot produce slides this way.

Users can still build reports and email them manually with this setting enabled — it is only the recurring, unattended
delivery of Scheduled Reports that is unavailable.

<Warning>
  **Capture Slides Using Custom Views** uses an undocumented Tableau method to capture slides. Because that method is
  not part of Tableau's documented API, its behavior can change in a future Tableau version. Treat this as a legacy
  option: enable it only when honoring filter exclusions in captured slides matters more to your users than Scheduled
  Reports, and prefer the standard capture method otherwise.
</Warning>

## Enable Capture Slides Using Custom Views

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Scroll down to, and expand, the "Toolbar Buttons (Curator Actions)" section.
6. Confirm that the "Scheduled Reports Option" setting is toggled **off**, and click the "Save" button.
7. Click on the "Report Builder" tab at the top of the main page content.
8. Scroll down to the "Tableau Settings" section.
9. Click to toggle on the "Capture Slides Using Custom Views" setting and click the "Save" button.

If the toggle cannot be changed at step 9, the "Scheduled Reports Option" setting is still enabled. Return to step 4,
turn it off, save, and then reload the Report Builder tab.


# Email Option
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/email_option

Configure email delivery settings for automated report distribution including recipients, formatting, and attachment options.

This feature allows the frontend user to email their newly created report to multiple individuals. The Report Builder
Email Option requires that the Report Builder feature is enabled and that Curator is configured to send out emails. You
can set up the Mail configuration settings on the left navigation in the Mail section of the Settings.

## Enable Report Builder Email Option

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. In the left hand navigation click on **Settings** > **Curator** > **Portal Settings**.
4. Click on the "Features" tab at the top of the main page content.
5. Scroll down to, and expand, the "Toolbar Buttons (Curator Actions)" section.
6. Click to toggle on the "Report Builder: Email Option" button and click the "Save" button.

## Configure the default bcc, subject, and body

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. In the left hand navigation click on **Settings** > **Curator** > **Portal Settings**.
4. Click on the "Report Builder" tab at the top of the main page content.
5. Scroll down to, and expand the "Report Builder: E-Mail Settings" section.
6. Fill out the "Email BCC Addresses", "Email subject", or "Email body" fields as desired, and click the "Save" button.

## Send an email with the built report

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Generate the images you want to use for your report.
5. Click on the presentation icon at the top right portion of the screen. Normally this is displayed on the right side
   of the title bar in the Dashboard.
6. Click on the email icon to "Email presentation as PDF".
7. Fill out the Email Address(es) field with the desired recipients. You can enter multiple email addresses by using
   commas to separate them.
8. If you have the correct permissions you can edit the subject and body.
9. Click the send button when finished.


# Fallback Image
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/fallback_image

Configure fallback images for reports when live dashboard content cannot be rendered or is unavailable.

There may be occasional issues when generating reports using Curator's Scheduled Reports.  This can be for a variety of
reasons, such as bad Tableau Server configuration, networking interruptions, permission changes, or dashboards getting
moved/deleted.  To handle these scenarios, the majority of them are fixed by simply having your user log back in to
Curator, and re-create the slide.  See the steps below on how to update the existing "Fallback Image" if you'd like to
customize this for your users.

## Updating the Fallback Image

Before you proceed below, you need to upload your file using the [File](/site_content_design/files/files)
system in Curator.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the "Report Builder" tab at the top of the main page content.
4. Expand the "Report Builder E-Mail Settings" and update the Fallback Image.
5. Click the save button.


# Overview and Enabling Report Builder
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/overview_and_enabling_report_builder

Introduction to Report Builder functionality and step-by-step instructions for enabling report generation capabilities.

The system can allow users to export one or more Dashboard snapshots as a Microsoft PowerPoint or PDF presentation.

<Note>
  Report Builder is only compatible with Tableau dashboards. It does not support Power BI, ThoughtSpot, Sigma, or
  other embedded content types.
</Note>

## Optimal Tableau Connection

Report Builder relies on **Connected Apps** authentication to reliably capture your dashboards. Connected Apps let
Curator impersonate the viewing user when requesting each snapshot from Tableau's image API, so the snapshot renders
under the viewer's identity — applying row-level security, Tableau user functions (such as `USERNAME()`), and per-user
data visibility. The filters and parameters the user applied are sent to Tableau regardless of authentication method;
what impersonation determines is *whose* identity the snapshot renders under. This is why **Connected Apps are the
recommended option** for Report Builder.

Trusted Tickets reached **end-of-life in October 2025** and are no longer a supported authentication method. Existing
Trusted Ticket connections are automatically migrated to Tableau Default Authentication when Curator is upgraded.

<Warning>
  Do not switch a Tableau connection away from Connected Apps (to Tableau Default Authentication) if
  that connection is used with Report Builder. Whether Curator can impersonate the viewing user is gated by the
  connection itself: impersonation is **not** available when the connection's REST user holds a site-administrator role
  on Tableau Server, or when the connection uses Tableau Default Authentication — in either case impersonation is only
  supported on Tableau Cloud, not Tableau Server. When impersonation is unavailable, Curator still sends the applied
  filters and parameters with the image request, but the snapshot is rendered under the REST service account rather than
  the viewing user. As a result, row-level security, Tableau user functions (such as `USERNAME()`), and per-user data
  visibility reflect the service account's permissions instead of the viewer's — so slides and scheduled report emails
  may show data the viewer would not normally see, even though the filters they selected are applied.
</Warning>

If your Tableau connection is not currently using Connected Apps and you are experiencing image-retrieval failures or
snapshots rendered under the REST service account's permissions (for example, data scoped to the service account
rather than the viewer, or row-level security not being applied), migrate the connection to Connected Apps. See
[Embed Authentication](/creating_integrations/tableau_connection/embed_authentication) for setup instructions.

## Enable Report Builder

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Scroll down to, and expand the "Toolbar Buttons (Curator Actions)" section.
6. Click to toggle on the "Report Builder" function and click the "Save" button.

## Download one or more dashboards as a PowerPoint or PDF presentation

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Modify the filters, etc. as desired on the Dashboard.
5. Click on the presentation icon at the top right portion of the screen. Normally this is displayed on the right side
   of the title bar in the Dashboard.
6. Click on the camera icon to take a snapshot of the current Dashboard as a presentation slide.
7. Repeat steps 3-6 as desired to create the slides that should be included in the presentation. Note: You can navigate
   to other eligible dashboards to add as slides to the same PowerPoint presentation.
8. If you need to rearrange the ordering of the slides, you can drag and drop them as needed.
9. If you need to delete all of the slides, click on the trash can icon to remove them and repeat steps 3-6 as desired
   to add the correct slides.  If you need to delete a single slide, drag and drop the slide on to the trash can icon.
10. Click on the PowerPoint button to create a PowerPoint presentation of the specified slides. Click on the PDF button
    to create a PDF presentation of the specified slides.

## Adding all Tabs from a Single Workbook

When capturing slides for your Report Builder Report, you may want to capture the entirety of a workbook that has been
embedded into Curator.  This setting can be enabled by administrators and will present an optional button in the
Report Builder modal in addition to the standard "Capture Dashboard" button.  To enable this additional button:

1. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
2. Click on the "Report Builder" tab.
3. Click to toggle ON the "Enable Workbook Capture" button and click the "Save" button.

NOTE: When using this feature with Connected Apps, Tableau requires that the Dashboard be published with the
[Show Sheets as Tabs](https://help.tableau.com/current/pro/desktop/en-us/publish_workbooks_howto.htm#show-sheets-as-tabs)
checkbox is selected.

## Troubleshooting

If a workbook tab exports blank or with a missing chart in Report Builder while other tabs from the same workbook
export correctly, see
[Troubleshooting: Charts Missing or Blank in Exported Reports](/embedding_using_analytics/report_builder/troubleshooting).

If a Report Builder snapshot does not match the filtered state shown on screen, see
[Troubleshooting: Snapshot Does Not Match the Dashboard View](/embedding_using_analytics/report_builder/troubleshooting#5-snapshot-does-not-match-the-dashboard-view).


# PowerPoint
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/powerpoint

Generate PowerPoint presentations from dashboard content using Report Builder for professional report delivery.

The [Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder)
functionality in Curator allows users to create Microsoft PowerPoint presentations of Tableau dashboards. We'll guide
you through setting up a template for these presentations, which can be automatically applied to your exported images.

## Setting Up PowerPoint Template

1. Create or open an existing Microsoft PowerPoint presentation.
2. Access Slide Master by clicking on the "View" ribbon and then the "Slide Master" button.
3. Identify Blank Layout: Look for the Blank layout in the Slide Master. This layout is used by the [Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder).
   * If Blank Layout is Missing:
     * Right-click in the left pane and select "Insert Layout".
     * Right-click on the newly created layout and select "Rename Layout".
     * In the pop-up, change the name to "Blank" and click "Rename".
4. Save Template: Save the presentation in an easy-to-find location on your computer.

**Note**: Powerpoint Presentations cannot contain more than one Slide Master.  In addition, some images formats are
unsupported as they become blended with Dashboard images on export.  If you need to convert these images, typically
clicking the "Convert to shape" button on the "Graphics Format" tab will suffice.

## Applying Template in Portal Settings

1. Access Portal Settings: Navigate to Settings > Portal Settings > Layout in your portal's backend.
2. Upload Template: In the "Powerpoint Template" field, upload the saved PowerPoint presentation.
3. Save Changes: Click the "Save" button to apply the template.

## Group Override settings

Utilize group override functionality to apply different templates for various Tableau user groups, adding excitement
and customization to presentations.


# Scheduled Reports
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/scheduled_reports

Configure automated report generation and distribution on recurring schedules for consistent business intelligence delivery.

The Scheduled Reports feature allows you to set a report to be sent out via email on a recurring schedule. This feature
requires that the
[Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder)
and
[Report Builder: Email Option](/embedding_using_analytics/report_builder/email_option)
both be turned on.

As of the 2024.09-02 release, [Scheduled Reports](/embedding_using_analytics/report_builder/email_option)
now have an unsubscribe option.  Recipients who receive the email can remove themselves from the distribution list -
unless they are the only recipient, in which case the report needs to be deleted to cease distribution via the schedule.

## Setup

### To enable the Scheduled Reports Option

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Click to switch on the "Scheduled Reports Option" setting under the "Toolbar Buttons (Curator Actions)" section and
   click the "Save" button.

### To configure the default bcc, subject, and body

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "[Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder)"
   tab at the top of the main page content.
5. Scroll down and expand the
   "[Report Builder Email Settings](/embedding_using_analytics/report_builder/email_option)"
   section.
6. Fill out the "Email BCC Addresses", "Email subject", or "Email body" files as desired, under the
   "[Report Builder Email Settings](/embedding_using_analytics/report_builder/email_option)"
   section and click the "Save" button.

### To configure the scheduled report format

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "Report Builder" tab at the top of the main page content.
5. Scroll down and expand the "Report Builder Email Settings" section.
6. Locate the **Scheduled Report Format** dropdown and select either **PDF** (default) or **PowerPoint**.
7. Click the "Save" button.

### To send a scheduled report with the built report

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Generate the images you want to use for your report.
5. Click on the presentation icon at the top right portion of the screen. Normally this is displayed on the right side
   of the title bar in the Dashboard.
6. Click on the Schedule button to "Schedule recurring report email".
7. Click on the "New Scheduled Report" button
8. Fill out the Email Address(es) field with the desired recipients. You can enter multiple email addresses by using
   commas to separate them.
9. If you have the correct permissions you can edit the subject and body.
10. Select the Recurring Schedule time frame you want your report sent out on.
11. Click the send button when finished.

## Existing Scheduled Reports

### Backend overview

1. Once Scheduled Reports are setup, navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Tableau** > **Scheduled Reports** in the left navigation.

In this view, you can see all existing Scheduled Reports and status information like ***last sent*** and
***is active?***. By using the checkboxes on the left side, you can select which Scheduled Reports you want to send out
immediately.
You can also create a new Scheduled Report by clicking on ***New Scheduled Report***.
By clicking on a specific Scheduled Report you enter Edit Mode. You can edit details of your Scheduled Report, change
the schedule, change the status and trigger sending out the report. You can also delete the Scheduled Report.

### Clone Scheduled Reports (2023.10-03)

To duplicate a scheduled report, this can be done on the backend of Curator by system administrators.  To clone a
report, simply visit the edit-report page, and click the "Clone" button in the top-right corner of the page.  This will
display a "Clone Report" page where you can change the title and create your new report.

### Frontend overview (available in release 2023.02.22)

If you want to give users an overview of their existing Scheduled Reports, follow the steps below:

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Navigate to the **Features** tab > open the **Toolbar Buttons (Curator Actions)** section.
5. Enable **Manage my Scheduled Reports - Page**

As a frontend user:

1. Navigate to the frontend of the system (e.g. [https://www.curatorexample.com](https://www.curatorexample.com)).
2. Open the user menu in the top right corner by clicking on your username.
3. Click on **My Scheduled Reports**.

In this view, you can see all your existing Scheduled Reports and information like ***schedule***, ***timezone*** and
***is active?***.
By clicking on the pencil icon of a specific Scheduled Report you enter Edit Mode. You can edit details of your
Scheduled Report, change the schedule, change the status and trigger sending out the report.
By clicking on the bin icon, you delete the specific Scheduled Report.

## Timezone Settings

Curator has two timezone settings that affect when Scheduled Reports are delivered:

### Global Cron Timezone

The **Cron Timezone** setting controls the timezone that Curator's scheduler uses for all recurring background tasks,
including Scheduled Reports, cache warming, user sync, and integration scripts.

**To configure:**

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. On the **General** tab, find the **Cron Timezone** dropdown and select your preferred timezone.
5. Click the "Save" button.

The **Cron Time of Day** field directly below it controls what time daily and weekly scheduled tasks run, using the
Cron Timezone selected above.

<Note>
  Changing the Cron Timezone automatically recalculates the delivery times for all existing Scheduled Reports so they
  continue to arrive at the correct time relative to each report's own timezone setting.
</Note>

### Per-Report Timezone

Each individual Scheduled Report has its own **Timezone** field in its schedule configuration. This is the timezone
that the report creator selects when choosing "send at 9:00 AM" — Curator converts that to the correct time
internally.

The per-report timezone is independent of the global Cron Timezone. If a report is set to send at 9:00 AM
America/New\_York, it will be delivered at 9:00 AM Eastern regardless of what the Cron Timezone is set to.

### Backend User Timezone Preference

Backend administrators each have a personal timezone preference (set under **Backend** > **Preferences**). This setting
only affects how dates and times are displayed in the backend interface — it does not affect when Scheduled Reports are
sent. For more information, see
[Backend Administrators](/site_administration/backend_administrators/overview#backend-preferences).

## Troubleshooting

If scheduled reports are not sending — either on their automatic schedule or when triggered manually from the
backend — or are arriving at the wrong time, work through the checklist below in order. Most delivery problems come
from one of these seven causes.

### 1. Confirm all required features are enabled

Scheduled Reports depend on two other features being enabled first. All three toggles live on the same tab:

1. Navigate to **Settings** > **Curator** > **Portal Settings** and open the **Features** tab.
2. Confirm **Report Builder** is enabled.
3. Confirm **Report Builder: Email Option** is enabled.
4. Confirm **Report Builder: Scheduled Reports Option** is enabled.

Email Option depends on Report Builder, and Scheduled Reports Option depends on both — so if a higher-level toggle
is off, the ones beneath it cannot be used and reports will not send.

### 2. Verify your mail (SMTP) configuration

Curator sends reports through its configured mail provider. If mail is misconfigured, a report can be processed
successfully but never actually delivered.

1. Navigate to **Settings** > **Mail** > **Mail Configuration**.
2. Review your SMTP host, port, username, and password.
3. Click **Test Saved Settings** and enter an address you can check.
4. If the test email does not arrive within 5 minutes, check your spam folder.
5. Correct any SMTP errors and re-test before retrying the report.

For full mail setup instructions, see
[Email Configuration](/setup/email/email_configuration).

### 3. Check the cron job

Curator's scheduler dispatches Scheduled Reports from the server's cron job (the `schedule:run` command). If that
cron is not running, no reports will ever be sent, no matter how they are configured.

To confirm the cron is running and fix common problems, see
[Linux Cron Troubleshooting](/server_management/system_administration/linux_cron_troubleshooting).

### 4. Check for stuck or errored queued processes

Reports are delivered as background jobs. A job that errored or is stuck from a previous attempt can indicate why a
delivery failed.

1. Navigate to **Settings** > **Curator** > **Queued Processes**.
2. Look for jobs whose status begins with **Error** — the status text describes why the delivery failed.
3. Look for jobs stuck in **Pending** for an unusually long time, which can indicate a stalled queue worker.
4. Use **Clear Errors** or **Clear Pending** from the toolbar to clear them out, then retrigger the report.

For more information, see
[Queued Processes](/site_administration/performance/queued_processes).

### 5. Check the report's active status

When a Scheduled Report is next due to send, Curator checks that the frontend user who owns it still exists. If that
user's account has been deleted, Curator automatically marks the report **inactive**, writes a
`Could not find owner for Scheduled Report` line to the log, and skips the send.

1. Navigate to **Tableau** > **Scheduled Reports** in the backend.
2. Check the **Is Active?** column for the affected report.
3. If the report is inactive and its original owner still exists, open the report and re-enable it. If the owning
   user has been deleted, the report must be recreated by a current user.

### 6. After moving servers or moving to a new data center

If Scheduled Reports start failing immediately after Curator is moved to new server hardware or a new data center,
check both of the following before assuming the schedules themselves are broken.

**Outbound mail may now be blocked.** A new server has a new outbound IP address. If your SMTP provider or mail relay
allow-lists sender IP addresses, the new server's address may not be authorized yet, so every send fails even though
your mail settings in Curator have not changed. Re-run **Test Saved Settings** from the new server (see step 2 above)
and, if it fails, ask whoever administers your mail relay to allow-list the new outbound IP address.

When a send fails this way, Curator writes a `Failed to send scheduled report` line to the Event Log
(**Settings** > **Logs** > **Event Log**) and attempts to email a "Scheduled Report Failure" notice to your backend
administrators. Because mail itself is what is broken, that notice usually cannot be delivered either — so check the
Event Log directly instead of waiting for a failure email to arrive.

**Timestamps in the Event Log and Queued Processes are recorded in UTC.** Curator stores every timestamp in UTC and
the backend displays them in UTC by default, so an entry can appear several hours away from the wall clock on the new
server. This is expected and is not evidence that the new server's clock is wrong. The **Cron Timezone** setting and
each report's own **Timezone** field control *when* reports are delivered; they do not change how these timestamps are
displayed. To display backend dates and times in your own timezone instead, set the **Timezone** preference described
in [Backend Administrators](/site_administration/backend_administrators/overview#timezone).

### 7. Reports sending exactly one hour early or late

If the affected reports are off by exactly one hour — and only by one hour — this is almost always a Daylight Saving
Time (DST) transition rather than a timezone misconfiguration. Curator converts each report's local send time into
UTC and stores that converted value alongside the report. When a Daylight Saving Time change occurs after that value
was last calculated, the stored value can be an hour off from the report's intended local send time until it is
recalculated.

Curator detects and repairs this automatically. When the scheduler finds a report whose stored delivery time is
within an hour of the current time, it recalculates and saves the corrected value. Note that the first send after a
DST change may still go out up to an hour early or late — it is the sends *after* that one which return to the
correct local time.

To correct the delivery time immediately instead of waiting for the next scheduled run, open the affected report and
click **Save** without changing any fields. Saving always recalculates the delivery time. You can do this from
**Tableau** > **Scheduled Reports** in the backend, or as a frontend user from the **My Scheduled Reports** page.

Changing the **Cron Timezone** described above also recalculates the delivery times for every existing Scheduled
Report, so reports corrected as a side effect of that change need no further action.

If reports are still off by exactly one hour after you save them again, contact
[Curator support](https://interworks.com/help) with the report name, its configured **Timezone**, and the exact time
it was actually sent.

### Still not working?

If reports are still not sending after working through these steps, contact support with:

* The exact status text shown in **Queued Processes** (if any)
* Your SMTP settings (host, port, and encryption type — not the password)
* The result of the **Test Saved Settings** mail test
* Your server cron log for the `schedule:run` command


# Troubleshooting: Charts Missing or Blank in Exported Reports
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/troubleshooting

Diagnose and resolve blank or incomplete charts in Report Builder exports, covering render-path differences, authentication, static-image rendering, and single-tab isolation.

A common support scenario is a workbook tab that renders correctly when downloaded directly from Tableau, but
shows a blank or empty chart when the same tab is captured in Report Builder and exported, while every other tab
from the same workbook exports correctly.

The key difference is *how* the image is produced. A direct download from Tableau is exported by Tableau's own
print engine. A Report Builder slide is captured by Curator asking Tableau's REST API to render a static,
high-resolution image of the view server-side. The interactive embed you see in the browser and the static image
Tableau renders for the API are two different render paths, so a view can display correctly in the browser yet
produce a blank or incomplete static image. The steps below isolate and resolve the most common causes.

## 1. Confirm Which Render Path the Connection Uses

Curator captures a slide in one of two ways. Where impersonation is supported, it asks the REST API to render the
view as the current user, which produces the most reliable image. Where it is not, Curator falls back to the legacy
`.png` endpoint, which is less reliable and is the more common source of blank charts.

Impersonation is used for every Tableau Cloud connection, and for Tableau Server connections whose REST user is not
a site administrator and whose embed authentication is not Tableau Default Authentication. The legacy `.png`
fallback therefore applies only to **Tableau Server** connections that use Tableau Default Authentication, or whose
REST user holds a site administrator role.

Two consequences are worth noting before you change anything. On Tableau Cloud the render path is always
impersonation, so switching the embed authentication type will not change how a slide is captured. On Tableau
Server, selecting Connected Apps is not on its own enough: a site administrator REST user still takes the legacy
`.png` path.

To check which path a Tableau Server connection uses:

1. Navigate to **Integrations > Connections** in the Curator backend and open your Tableau connection.
2. Scroll to the **Embed Authentication** section, expand it, and note the selected method. Tableau Default
   Authentication forces the legacy `.png` path.
3. Check the site role of the connection's REST API user. A site administrator role also forces the legacy `.png`
   path, even when Connected Apps is selected.
4. If either applies, switch the connection to Connected Apps and supply a REST user that does not hold a site
   administrator role. See
   [Embed Authentication](/creating_integrations/tableau_connection/embed_authentication) for full setup
   instructions. Trusted Tickets are deprecated and reached end of life in October 2025, so **Connected Apps is the
   recommended and most stable authentication method for Report Builder.**
5. Clear the Curator backend cache and re-capture the affected slide in Report Builder.

## 2. Account for Views That Do Not Render Completely as a Static Image

Because the slide is a static image rendered by Tableau on request, complex views (those with large datasets,
heavy calculated fields, map layers, or web/extension objects) sometimes render blank or partially in the image
even though they draw correctly in the interactive embed. Tableau also caches its rendered images briefly (Curator
requests an image no more than a few minutes old), so a one-off incomplete render can persist on a re-capture for a
short time.

To check whether this is the cause:

* Open the affected tab in Curator and note whether the chart is noticeably slower or heavier to load than the
  tabs that export correctly.
* Wait a few minutes, clear the Curator backend cache, and re-capture the slide so Tableau produces a fresh image
  rather than returning a recently cached one.
* If the static image is consistently blank, open the same view in Tableau and confirm it can be exported there as
  an image (not only as a PDF). If Tableau itself cannot produce a complete image of the view, the workbook design
  needs to be adjusted in Tableau.

## 3. Verify the Workbook Is Published with Show Sheets as Tabs

When using the **Workbook Capture** feature to capture every tab at once, Tableau requires the workbook to be
published with the
[Show Sheets as Tabs](https://help.tableau.com/current/pro/desktop/en-us/publish_workbooks_howto.htm#show-sheets-as-tabs)
option enabled. If this setting is off, individual tabs may not be reachable during the capture and will appear
blank in the exported report. Confirm this option is enabled before re-publishing the workbook.

## 4. Isolate the Affected Tab

If other tabs from the same workbook export correctly and only one tab is blank:

1. Navigate directly to the affected tab in Curator.
2. Use the standard **Capture Dashboard** button to add only that tab as a single slide, then export it on its own.
   This shows whether the problem is specific to that tab rather than to the workbook capture or the export step.
3. If the single-tab capture is also blank, enable
   [Debug Mode for Tableau Server](/creating_integrations/tableau_connection/tableau_connection_troubleshooting#tableau-api-debugging)
   and reproduce the capture, then review the event logs and share them with Curator support for further
   investigation.

## 5. Snapshot Does Not Match the Dashboard View

Report Builder captures a Tableau dashboard in its current filtered state. For a snapshot to match what is on
screen, Curator must be tracking the active filter and parameter values in the dashboard's URL.

### The "Ignore Filter and Parameter Changes from Dashboard" Setting

The **Ignore Filter and Parameter Changes from Dashboard** toggle controls whether Curator listens to the filter
and parameter changes made within a Tableau dashboard. It is available per-dashboard (Tableau > Dashboards >
*\[Dashboard]* > **Filters** tab) and globally (Settings > Tableau > Tableau Server Settings). The per-dashboard
and global toggles are combined: if either one is on, Curator ignores filter and parameter changes for that
dashboard.

| Setting state     | Curator behavior                                                                                            | Effect on Report Builder                                  |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Off** (default) | Curator listens to filter and parameter changes made within the dashboard and adds them to the Curator URL. | Snapshots capture the currently displayed filtered state. |
| **On**            | Curator ignores filter and parameter changes made within the dashboard.                                     | Snapshots may not match the filters visible on screen.    |

If Report Builder snapshots are not reflecting the filters shown on screen, confirm this setting is **Off** for
the affected dashboard (and globally).

<Note>
  When the global **Ignore Filter and Parameter Changes from Dashboard** setting is on, Curator adds a note to the
  Report Builder toggle in Portal Settings reminding you that filter and parameter selections will be ignored when
  capturing slides.
</Note>

### Charts Breaking After Disabling This Setting

Some dashboards contain their own filter or parameter logic that overrides the values Curator sets. On those
dashboards, turning **Ignore Filter and Parameter Changes from Dashboard** off lets Curator write the dashboard's
filter and parameter events into the URL on load. If the applied values conflict with the dashboard's own logic,
charts can render incorrectly or appear blank. This is exactly the scenario the setting is designed to prevent: its
per-dashboard help text advises turning it on when a dashboard overrides the filter or parameter value set by
Curator.

To keep Report Builder capturing the correct state on your other dashboards without re-enabling the setting
globally:

1. Identify which dashboards are affected by testing each one individually.
2. Turn on **Ignore Filter and Parameter Changes from Dashboard** only on the specific dashboards that break,
   leaving the global setting off so Report Builder continues to capture the correct state on unaffected
   dashboards.
3. For a dashboard where this setting must remain on but you still need an accurate snapshot, use the **Alternate
   Report Builder Dashboard Link** field (Tableau > Dashboards > *\[Dashboard]* > **Advanced** tab) to point Report
   Builder at a separate, capture-only version of the dashboard that does not apply the conflicting filter logic on
   load. This field requires a Tableau Server formatted URL. Note that the **Alternate Report Builder Dashboard
   Link** field is hidden on any dashboard where the **Use PPTX Tab** option is also enabled; uncheck **Use PPTX
   Tab** on that dashboard (or use a separate capture-only dashboard that does not have that option enabled) before
   the field becomes visible.


# Watermark Text
Source: https://docs.curator.interworks.com/embedding_using_analytics/report_builder/watermark_text

Add custom watermark text to generated reports for branding, security, or identification purposes.

With Watermark Text, you can add your own custom text to the bottom left of every image exported out by the Report
Builder feature.

## Enable the Watermark Text

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "Report Builder" tab at the top of the main page content.
5. Fill out the text field under the "Watermark Text" section and click the "Save" button.


# Adding a Dashboard
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/adding_a_dashboard

Learn how to create and configure Tableau dashboards in Curator for seamless embedding and display.

Curator excels at showcasing embedded Tableau dashboards as a seamless part of your Curator site.

\***Note:** Due to limitations in Tableau's JS API we do not support embedding worksheets.  We recommend adding a
worksheet to a Dashboard instead.

## Create a Dashboard

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`) and log in if prompted.
2. Navigate to **Tableau** > **Dashboards**.
3. Click on the "New Dashboard" button.
4. Fill out the **Tableau Server**, **Site**, **Project**, **Workbook** and **Dashboard** drop-downs to select the
   Dashboard you'd like to embed.
5. Populate the remainder of the fields as desired. At the bottom of the **Dashboard** tab, the **Create Menu Link**
   checkbox is checked by default, which adds a main menu item for the Dashboard on save. Uncheck it if you do not want
   a menu item created.
6. Click on the "Create" button.

### Defaulting Create Menu Link to Unchecked

If your site serves content through tiles or the Explorer element rather than the main menu, you can change the
default so the checkbox starts unchecked on every single Dashboard create, matching the batch create form, which
never creates a menu link.

1. Navigate to **Settings** > **Tableau** > **Tableau Server Settings**.
2. On the **General** tab, find the **Dashboard Creation** section and turn on **Uncheck Create Menu Link by
   Default**.
3. Click on the "Save" button.

The checkbox remains available on the create form, so a menu link can still be created by checking it before you
click "Create".

## Dashboard Sizes

Curator respects the Dashboard sizes applied in Tableau. We experience that a fixed size ensures consistency in design
throughout many screen sizes. You wonder what the best suitable size is? Consider the size of your users' screens. How
much space do you need for navigation, titles, toolbar buttons and margins you want to apply.
Do you have dashboards that should take up the full remaining screen? Go to Tableau and set its size to *automatic* and
the Dashboard will stretch to all ends in Curator.

### Troubleshooting: Scrollbars Appearing on a Dashboard

If a Dashboard shows horizontal and/or vertical scrollbars in Curator instead of fitting the page, its **Size** is
almost always set to a fixed size (*Exactly*) in Tableau — for example `1400 x 1000`. Curator renders a fixed-size
Dashboard at exactly those dimensions instead of shrinking it to fit, so whenever the Dashboard is wider or taller
than the space available on the user's screen, scrollbars appear.

Keep in mind that a fixed-size Dashboard also needs a little more room than its configured height when Curator draws
Tableau's own controls around it. Showing the Tableau toolbar adds roughly 30 pixels of height, and showing Tableau's
native tabs adds roughly another 25 pixels. A Dashboard sized to exactly match a user's screen height can therefore
still scroll vertically.

There is no Curator setting that overrides, scales, or clips a fixed Tableau Dashboard size, so the sizing has to be
changed in Tableau:

1. In Tableau (Desktop or web authoring), open the workbook and select the Dashboard.
2. In the **Size** drop-down, change *Fixed size* to **Automatic**, or to **Range** with a minimum and maximum size,
   so the Dashboard resizes to the space available instead of rendering at fixed pixel dimensions.
3. Save and publish the workbook, then reload the Dashboard in Curator.

\***Note:** The Theme setting **Override Tableau Container Size on Mobile/Tablet** resizes only the container Curator
draws around the embed on phones and tablets. It does not resize the Dashboard itself, so it will not remove
scrollbars caused by a fixed size. Likewise, the **Dashboard Full-Screen Margin** Theme setting applies only to
dashboards using *automatic* or *range* sizing.


# Chrome and Edge Embedding Issues (Local Network Access)
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/chrome_edge_embedding_issues

Troubleshoot embedded content that fails to load in Chrome 142+ or Edge 143+ due to Local Network Access restrictions

<Info>
  This article applies to **all iframe-based embedded content** in Curator, including Tableau dashboards and Page Builder iframes.
  While earlier versions of this guide focused on Tableau, Chrome's Local Network Access restrictions affect any content
  loaded in an iframe.

  Curator applies a built-in mitigation to embedded iframes automatically (see
  [Curator-side mitigation](#curator-side-mitigation)), but that mitigation alone does not resolve the issue in most
  affected environments — your IT team will usually also need to configure the browser policies described in
  [Solutions for managed environments](#solutions-for-managed-environments).
</Info>

## Overview

If you're running **Google Chrome 142** (or later) or **Microsoft Edge 143** (or later), you may find that embedded
content in Curator fails to load. Instead of seeing your Dashboard or embedded page, you might see a blank area where
the content should appear.

This happens because of a new security feature in Chromium browsers called **Local Network Access restrictions** (LNA).
This feature blocks public websites from connecting to devices or services on your local network. While Curator and your
analytics platforms use only public HTTPS endpoints, certain security tools on your computer can trigger this restriction
and break embedded content.

<Warning>
  Curator provides a server-side mitigation (the `allow='local-network-access *; local-network *; loopback-network *'`
  attribute on embedded iframes), but it cannot fully override the browser's security checks. Your IT team will need to
  configure browser policies for a permanent fix.
</Warning>

<Warning>
  **Chrome is removing the temporary opt-out policy.** Chrome 152 (released August 25, 2026) is the last version to
  support the `LocalNetworkAccessRestrictionsTemporaryOptOut` enterprise policy — Chrome 153 (scheduled for release on
  September 8, 2026) removes it. If your organization relies on this policy as a workaround, embedded content will stop
  loading as Chrome 153 rolls out to your managed devices — migrate to `LocalNetworkAccessAllowedForUrls` and the other
  policies in the [Solutions for managed environments](#solutions-for-managed-environments) section now. Also note that
  Chrome moves to a two-week release cadence starting with Chrome 153, so browser-version-gated changes will arrive
  faster than they used to.

  Microsoft Edge has diverged from Chrome here: Edge keeps its equivalent opt-out policy until after **Edge 156**,
  giving Edge-managed environments more time to migrate.
</Warning>

You can read more about this feature in [Chrome's developer blog](https://developer.chrome.com/blog/local-network-access)
and [Tableau's documentation](https://help.salesforce.com/s/articleView?id=005228129\&language=en_US\&type=1).

***

## Symptoms

<Frame>
  <img alt="Example error message" />
</Frame>

You'll know you're experiencing this issue if you see:

* You might see a **blank area, loading screen, or error message** where embedded content should appear.
* **Error messages** in the browser saying a public page tried to connect to devices on the local network.
* **Content loads in other browsers** - The same content works fine in Firefox, Safari, or older versions of Chrome/Edge.
* **Works on other devices** - The content loads normally on personal devices that aren't connected to your corporate network.

***

## Why this happens

### What is Local Network Access?

Chrome 142 ([release notes](https://developer.chrome.com/release-notes/142#local_network_access_restrictions)) and Edge 143
([release notes](https://learn.microsoft.com/en-us/microsoft-edge/web-platform/release-notes/143#local-network-access-from-non-secure-contexts))
introduced Local Network Access (LNA) restrictions to protect users from malicious websites trying to access devices
on their local network.

When a public website tries to connect to these addresses, the browser will block or prompt:

* **Loopback addresses:** `127.0.0.1`, `localhost`
* **Private IP ranges:** `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`
* **Carrier-grade NAT ranges:** `100.64.0.0` to `100.127.255.255` (commonly used by security products)

Starting with Chrome 145, the single Local Network Access permission was split into two more granular permissions:
`local-network` (shown in the browser's permission UI as **Local Network**) and `loopback-network` (shown as
**Apps on device**). The original `local-network-access` permission name remains supported as an alias that covers
both. You may see either naming in browser prompts and site-permission settings depending on the browser version.

Today the restrictions apply to subresource requests, `fetch()` calls, and subframe navigation. Google and Microsoft
have both stated that they plan to extend the restrictions to WebSockets, WebTransport, and WebRTC connections in a
future release, so tools that currently escape the checks over those channels may start triggering prompts later.

### Why does this affect Curator?

In most cases, Curator and your analytics platforms use only public HTTPS endpoints, so LNA shouldn't be triggered.
However, in corporate environments with certain security tools installed, those tools may create connections to local
addresses while you're using Curator.

Common security tools that can trigger this issue:

* **[Zscaler Client Connector or ZPA](https://trust.zscaler.com/posts/26216)** - Uses IP range `100.64.0.0` and higher
  for internal routing
* **[Duo Desktop](https://help.duo.com/s/article/9470)** - Runs a local helper service
* **[Okta FastPass](https://support.okta.com/help/s/article/configure-chrome-to-suppress-the-local-network-access-prompt-for-okta-fastpass)**
  \- Uses local authentication components
* **[Box Tools](https://support.box.com/hc/en-us/articles/45163820905107)** - Connects to local services
* **Other DLP or endpoint security agents** - May expose local HTTP services

When one of these tools is running, your browser sees this as "public site (Curator) accessing local network" and
applies LNA restrictions. If this happens while loading content in an iframe, you often won't see a prompt—the
embedded content will simply fail to load.

***

## Who is affected

You'll see this issue if:

1. You're using **Google Chrome 142** (or later) or **Microsoft Edge 143** (or later)
2. Your organization uses security tools like those listed above that rely on local addresses or carrier-grade NAT ranges
3. You're accessing Curator on a managed corporate device

If you're using Firefox, Safari, or older versions of Chrome/Edge, you typically won't see this issue.

***

## Quick troubleshooting for end users

If embedded content isn't loading in Curator, try these quick checks:

1. **Test in another browser** - Try Firefox or Safari to see if the content loads normally. If it does, this confirms
   an LNA issue.

2. **Check your browser version**
   * In Chrome: Go to `chrome://settings/help`
   * In Edge: Go to `edge://settings/help`
   * If you see version 142+ (Chrome) or 143+ (Edge), LNA may be the cause

3. **Test on a different device** - Try accessing Curator from a personal device or home network. If it works there,
   the issue is related to your corporate security tools.

4. **Contact your IT team** - Share this article with them. They'll need to configure browser policies to fix the
   issue permanently.

***

## Diagnostic steps for IT teams

If users are reporting blank or failed embeds, follow these steps to confirm this is an LNA issue:

### Step 1: Confirm the environment

Check that:

* Users are on Chrome 142+ or Edge 143+
* Affected devices are managed corporate machines
* Users have security tools installed (Zscaler, Duo Desktop, Okta FastPass, Box Tools, or similar)

### Step 2: Inspect the browser console

On an affected computer:

1. Open Curator and navigate to a page with embedded content that's failing to load.
2. Open **Developer Tools** in the browser:
   * Chrome: Press `F12` or `Ctrl+Shift+I` (Windows) / `Cmd+Option+I` (Mac)
   * Edge: Press `F12` or `Ctrl+Shift+I` (Windows) / `Cmd+Option+I` (Mac)
3. Click the **Network** tab in Developer Tools.
4. Reload the page and look for failed requests:
   * Look for error messages mentioning **Local Network Access**
   * Check for remote addresses in these ranges:
     * `127.0.0.1` or `localhost`
     * `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`
     * `100.64.0.0` to `100.127.255.255` (used by Zscaler and others)
5. For failed requests, check the **Initiator** or **Origin** column to see which site initiated the request.

### Step 3: Capture diagnostic information

Take screenshots or note:

* The full URL of any failing requests
* The remote IP address and port
* Which security tool is involved (based on the URL/IP)
* The browser version

This information will help you determine which domains to allowlist in browser policies.

***

## Solutions for managed environments

For corporate-managed Chrome and Edge browsers, your IT team needs to configure Local Network Access policies to
allowlist trusted domains.

### For Google Chrome

Your IT team should configure Chrome enterprise policies ([full policy list](https://chromeenterprise.google/policies))
using your management platform (Group Policy, Jamf, Intune, etc.).

**Key policies** ([atomic group documentation](https://chromeenterprise.google/policies/atomic-groups)):

* `LocalNetworkAccessAllowedForUrls` - List of domains allowed to make local network requests without prompting
* `LocalNetworkAccessBlockedForUrls` - List of domains blocked from local network access
* `LocalNetworkAccessIpAddressSpaceOverrides` (Chrome 146+) - Reclassifies IP ranges as public, local, or loopback.
  This is the cleanest fix when a security tool's address range (such as Zscaler's carrier-grade NAT range) is being
  misclassified as local — see below.
* `LocalNetworkAccessPermissionsPolicyDefaultEnabled` (Chrome 146+) - Lets cross-origin iframes inherit the Local
  Network Access permission granted via `LocalNetworkAccessAllowedForUrls`, for cases where an allowlisted site still
  fails because an iframe in the chain lacks the `allow` attribute
* `LocalNetworkAccessRestrictionsTemporaryOptOut` - Temporary opt-out (last supported in Chrome 152;
  **removed in Chrome 153**, scheduled for September 8, 2026)

#### Recommended fix for Zscaler and other carrier-grade NAT tools

If the diagnostic steps above show failing requests to addresses in the `100.64.0.0` – `100.127.255.255` range
(Zscaler and similar tools), the most targeted fix is to reclassify that range as public with
`LocalNetworkAccessIpAddressSpaceOverrides`. The policy takes a **list of strings**, each in
`[cidr]=[public|local|loopback]` form:

```json theme={null}
{
  "LocalNetworkAccessIpAddressSpaceOverrides": [
    "100.64.0.0/10=public",
    "[fc00::6440:0]/112=public"
  ]
}
```

These are the exact values [Zscaler's own advisory](https://trust.zscaler.com/posts/26216) recommends for ZPA
(IPv4 and IPv6 respectively). This stops the browser from treating the security tool's traffic as local network
access at all, so no prompts appear and no per-site allowlisting is needed.

<Warning>
  The override removes Local Network Access protection for **everything** in the reclassified range, not just the
  security tool's traffic. Before applying it, confirm that your organization does not host internal services in the
  `100.64.0.0/10` (RFC 6598) space that should stay protected — if it does, scope the override to the narrower
  subranges your security product actually uses instead of the full range.
</Warning>

#### Example configuration

In JSON format for Chrome policy:

```json theme={null}
{
  "LocalNetworkAccessAllowedForUrls": [
    "https://your-curator-domain.com",
    "https://your-tableau-server.com"
  ]
}
```

<Info>
  The JSON examples on this page use Chrome's managed-policy JSON format, where the policy value is the array itself —
  for example a file in `/etc/opt/chrome/policies/managed/` on Linux. On Windows, configure the same policies through
  Group Policy or the registry (each list entry becomes a numbered value under the policy key), and on macOS through a
  configuration profile. Your management platform (Intune, Jamf, Google Admin console) may present these as list fields
  instead — enter one entry per line.
</Info>

<Info>
  Replace the example domains with:

  * Your Curator portal URL(s)
  * Your Tableau Server or Tableau Cloud URL(s)
  * Any identity provider domains if you use SSO
</Info>

**To verify the policy is working:**

1. On a managed computer, open Chrome and navigate to `chrome://policy`
2. Search for "LocalNetworkAccess" in the policy list
3. Verify that your `LocalNetworkAccessAllowedForUrls` policy appears with the correct domains

**If the allowlist alone doesn't fix it:**

The `LocalNetworkAccessAllowedForUrls` policy applies to the **top-level site** making the request. When the actual
local network request happens inside an iframe (which is how Curator embeds content), the iframe also needs the
`local-network-access` permissions-policy attribute — Curator adds this automatically (see
[Curator-side mitigation](#curator-side-mitigation)), so keep the **Local Network Access for Embedded Content** Portal Setting
enabled even after configuring browser policies. If embeds still fail with the allowlist in place, enable
`LocalNetworkAccessPermissionsPolicyDefaultEnabled` alongside `LocalNetworkAccessAllowedForUrls` so iframes inherit
the permission.

**Temporary workaround:**

<Warning>
  Chrome 152 is the last version to support the `LocalNetworkAccessRestrictionsTemporaryOptOut` policy — **Chrome 153**
  (scheduled for release on September 8, 2026) removes it permanently. Do not build new workarounds on it; use
  `LocalNetworkAccessAllowedForUrls` and `LocalNetworkAccessIpAddressSpaceOverrides` instead. The policy remains
  available in Microsoft Edge until after Edge 156 (see the Edge section below).
</Warning>

### For Microsoft Edge

Edge has equivalent policies
([policy documentation](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-policies)) that work the same way.

**Key policies:**

* [`LocalNetworkAccessRestrictionsEnabled`](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/localnetworkaccessrestrictionsenabled)
  \- Enable or disable the restriction
* [`LocalNetworkAccessAllowedForUrls`](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/localnetworkaccessallowedforurls)
  \- Allowlist specific domains
* [`LocalNetworkAccessIpAddressSpaceOverrides`](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/localnetworkaccessipaddressspaceoverrides)
  (Edge 146+) - Reclassify IP ranges (e.g., `100.64.0.0/10=public` for Zscaler's carrier-grade NAT range)
* [`LocalNetworkAccessPermissionsPolicyDefaultEnabled`](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/localnetworkaccesspermissionspolicydefaultenabled)
  (Edge 146+) - Let iframes inherit the permission granted to allowlisted top-level sites
* [`LocalNetworkAccessRestrictionsTemporaryOptOut`](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/localnetworkaccessrestrictionstemporaryoptout)
  \- Temporary opt-out (available until after Edge 156)

Microsoft also publishes a detailed adaptation guide with policy guidance for common scenarios (carrier-grade NAT
ranges, cross-origin iframes, and allowlists that don't take effect):
[Adapting your website for new Local Network Access restrictions in Microsoft Edge](https://learn.microsoft.com/en-us/deployedge/ms-edge-local-network-access).

#### Example Edge configuration

In Group Policy:

1. Navigate to **Administrative Templates** > **Microsoft Edge** > **Network settings**
2. Open the **Allow sites to make requests to local network endpoints** setting
   (`LocalNetworkAccessAllowedForUrls`)
3. Enable the policy and add your domains:
   * `https://your-curator-domain.com`
   * `https://your-tableau-server.com`
4. Click **OK** and apply the policy

**Temporary workaround:**

<Warning>
  Chrome removes `LocalNetworkAccessRestrictionsTemporaryOptOut` in Chrome 153 (scheduled for September 8, 2026), but
  Microsoft has postponed Edge's removal: the policy remains available until after **Edge 156**. Use the extra time to
  migrate to `LocalNetworkAccessAllowedForUrls` (plus `LocalNetworkAccessIpAddressSpaceOverrides` where a security
  tool's address range is the trigger) — don't wait for the removal to land.
</Warning>

If needed during transition, you can set **Local Network Access restrictions** (`LocalNetworkAccessRestrictionsEnabled`)
to **Disabled**. This should only be used temporarily while you configure the proper allowlist.

***

## Temporary workaround for individual users

If you need immediate access while your IT team configures the policies, you can temporarily disable Local Network
Access checks in your browser.

<Warning>
  This is a temporary workaround only. Your IT team should implement the browser policies above for a permanent solution.
  This setting may be reset when your browser updates or if your IT team enforces policies. The flag still exists as of
  Chrome 152, but Google may remove it in any future release — and with Chrome shipping a new version every two
  weeks starting with Chrome 153 (September 2026), that can happen with little notice.
</Warning>

### Chrome flags workaround

1. Open Chrome and go to `chrome://flags/` in the address bar.
2. Search for "Local Network Access" in the search box at the top.
3. Find the **Local Network Access Checks** flag and click the dropdown next to it.
4. Select **Disabled** from the dropdown.
5. Click the **Relaunch** button that appears at the bottom of the page to restart Chrome.

### Edge flags workaround

1. Open Edge and go to `edge://flags/` in the address bar.
2. Search for "Local Network Access" in the search box at the top.
3. Find the **Local Network Access Checks** flag and click the dropdown next to it.
4. Select **Disabled** from the dropdown.
5. Click the **Restart** button that appears at the bottom of the page to restart Edge.

After restarting, try accessing the embedded content in Curator again. It should load normally.

***

## Curator-side mitigation

Curator includes a server-side mitigation for Local Network Access restrictions. Starting with version **2025.12-03**,
Curator adds an `allow` permissions-policy attribute to iframes that embed content. This attribute signals to
the browser that the iframe is expected to make local network requests, which can prevent LNA from silently blocking
embedded content. The attribute now carries all three permission tokens —
`local-network-access *; local-network *; loopback-network *` — covering Chrome/Edge 142-144 (which use the original
`local-network-access` name), Chrome 145+ (which split it into `local-network` and `loopback-network`), and any future
version that drops the legacy alias. Browsers ignore tokens they don't recognize, so the widened attribute is harmless
on Firefox, Safari, and older Chromium versions.

<Warning>
  **Upgrading Curator alone does not resolve this issue in most affected environments.** The `allow` attribute only
  *delegates* the Local Network Access permission into the embed iframe — it is a prerequisite for the embed to work,
  not a grant of access. Whether the request is actually allowed is still decided by the browser, through the user
  permission prompt or your IT team's enterprise policies. If a security tool on the device is triggering LNA
  restrictions, the browser policies in [Solutions for managed environments](#solutions-for-managed-environments) are
  still required after upgrading.
</Warning>

This mitigation has been rolled out in stages:

* **Tableau V3 embeds:** The `local-network-access` attribute was added in Curator version **2025.12-03**.
* **Page Builder iframes:** The attribute was extended to Page Builder iframes in Curator version **2026.02-04**.

If you are running Curator **2026.02-04 or later**, all iframe-based embeds include this attribute automatically.

### Configuring Local Network Access

The `allow` attribute is controlled by the **Local Network Access for Embedded Content** toggle
in **Portal Settings** (General tab). This setting is **enabled by default**, preserving the existing behavior.

Administrators who want to disable the attribute — for example, in deployments where embedded content does not require
local network access — can turn off the toggle. When disabled, the `allow` attribute is omitted from all embedded
content iframes.

<Info>
  The `allow` attribute helps the browser handle LNA preflight checks correctly, but it does
  not replace browser policy configuration. If your users' security tools trigger LNA restrictions, your IT team should
  still configure `LocalNetworkAccessAllowedForUrls` as described in the
  [Solutions for managed environments](#solutions-for-managed-environments) section.

  The reverse is also true: browser allowlist policies apply to the top-level site, and Chromium browsers still require
  the iframe to carry the permissions-policy attribute (unless your IT team has also enabled
  `LocalNetworkAccessPermissionsPolicyDefaultEnabled`, which lets iframes inherit the permission). Leave this toggle
  **enabled** even after your IT team configures browser policies — disabling it can break embeds for users on
  Chrome 142+ / Edge 143+ wherever that inheritance policy is not in place.
</Info>

***

## Consider switching to Connected Apps

If your Curator system is currently using **Tableau Default** or **Trusted Tickets** for Tableau authentication,
switching to **Connected Apps** may reduce embedding issues related to Local Network Access restrictions.

Older authentication methods like Trusted Tickets involve multiple redirects between Curator, Tableau Server, and your
identity provider during the embed process. Each redirect is an opportunity for the browser to detect a local network
request and apply LNA restrictions, especially when security tools like Zscaler intercept those redirects. Connected
Apps use a JWT-based authentication flow that authenticates directly with Tableau without intermediate redirects or
local network interactions during the auth handshake. This significantly reduces the chance that LNA restrictions will
be triggered during the embed process.

***

## Additional vendor-specific guidance

If you've identified which security tool is causing the issue, these vendor guides may help your IT team configure
both the browser policies and the security tool itself:

* **Tableau:** [Embedded Tableau views fail to load after Chrome 142](https://help.salesforce.com/s/articleView?id=005228129\&language=en_US\&type=1)
* **Zscaler:** [Chrome 142 Local Network Access Advisory](https://trust.zscaler.com/posts/26216)
* **Duo Desktop:** [Chrome 142 and Edge 143 Changes](https://help.duo.com/s/article/9470)
* **Okta FastPass:**
  [Configure Chrome for Local Network Access](https://support.okta.com/help/s/article/configure-chrome-to-suppress-the-local-network-access-prompt-for-okta-fastpass)
* **Box Tools:** [Allow Local Network Access in Chrome and Edge](https://support.box.com/hc/en-us/articles/45163820905107)


# Navigation with URL Actions
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/cross_dashboard_navigation_url_actions

Walk through setting up a Tableau URL Action that navigates users to another Curator-hosted Dashboard with filters applied automatically.

This guide walks through a common use case: a user clicks a mark on a Tableau Dashboard (the *source*) and is taken
to another Curator-hosted Dashboard (the *target*) that is automatically filtered based on the selection. For example,
clicking a region on a map could navigate the user to a regional-detail Dashboard pre-filtered to that region.

## Step 1: Build the Target URL in the Tableau URL Action Dialog

In Tableau Desktop, create a URL Action on the source Dashboard that points to the target Dashboard's **Curator page
URL** — not its Tableau Server URL. Append query parameters whose names match the filter fields on the target
Dashboard.

For example, if the target Dashboard has a *Region* filter and the Curator page lives at
`https://www.curatorexample.com/dashboards/regional-detail`, the URL would be:

```text theme={null}
https://www.curatorexample.com/dashboards/regional-detail?Region=<Region>
```

Where `<Region>` is a Tableau field reference that will be replaced with the selected value at runtime. You can
chain multiple filter parameters with `&`:

```text theme={null}
https://www.curatorexample.com/dashboards/regional-detail?Region=<Region>&Year=<Year>
```

When the target Dashboard loads, Curator reads these query parameters and passes them straight through to the
Tableau embed, applying the filters automatically.

## Step 2 (Optional): Configure Multi-Value Delimiters

If a URL Action can send more than one value for a parameter (for example, when the user selects multiple marks),
configure the **Data Values** section of the URL Action dialog in Tableau:

1. Open the `Data Values` section below the URL field.
2. Check the box for *Encode data values that URLs do not support*.
3. Check the box for *Allow multiple values via URL parameters*.
4. Set the *Value Delimiter* to three pipes (`|||`).
5. Set the *Delimiter Escape Character* to a backslash (`\`).

Curator automatically converts the `|||` delimiter to commas before passing the values to the embedded Dashboard, so
multi-select filters work correctly on the target Dashboard.

## Step 3: Set the Source Dashboard's Link Target to Curator Detect

To make sure clicking the URL Action keeps the user inside Curator instead of opening the raw Tableau Server URL:

1. Log in to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend`).
2. Navigate to **Tableau** > **Dashboards** and click the **source** Dashboard.
3. Open the **Advanced** tab and find the *Embedded Options* section.
4. Set the [**Link Target**](/embedding_using_analytics/tableau_dashboards/url_action_overrides_link_target) to
   *Curator Detect* (same tab) or *Curator Detect New Tab* if you prefer the target to open in a new browser tab.
5. Click **Save**.

With *Curator Detect*, Curator inspects the URL produced by the URL Action. If it matches a Dashboard page in the
current user's navigation, Curator routes the user to that page directly — preserving the query-string filters. If
no match is found, the URL opens in a new tab instead.


# Custom Parameters in Tableau Embedding API v3
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/custom_parameters_v3

Understand why URL parameters appended to the Tableau Server Dashboard URL do not work in v3, and how Curator handles custom parameters via client-side rendering.

## Overview

When using **Tableau Embedding API v3**, URL parameters appended directly to the **Tableau Server Dashboard URL**
(e.g., `?:render=True`) are **not supported**. This is a known change from the v2 embedding approach and affects
any parameter that was previously passed by appending it to the Tableau Server URL.

If you are seeing unexpected behavior — such as images not rendering or toolbar options being ignored — after
upgrading to Tableau Embedding API v3, this page explains why and how to fix it.

<Warning>
  Do not append custom parameters (e.g., `:render`, `:refresh`, `:linktarget`) directly to the **Tableau Server
  Dashboard URL** field in Curator when using Embedding API v3. These parameters will be silently ignored.
</Warning>

***

## Why URL parameters don't work in v3

In the v2 embedding approach, Tableau dashboards were embedded using a plain `<div>` element and a JavaScript
initializer. URL query parameters could be appended directly to the Tableau Server Dashboard URL to control
rendering behavior.

In v3, Tableau dashboards are embedded using the `<tableau-viz>` web component. The web component does not
read or forward query parameters from the `src` URL in the same way. Instead, configuration options must be
provided as **child `<custom-parameter>` elements** nested inside the `<tableau-viz>` component.

From the
[Tableau Embedding API documentation](https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html#apply-custom-parameters-during-customization-using-web-components),
the correct way to pass custom parameters in v3 is:

```html theme={null}
<tableau-viz src="https://your-tableau-server/views/YourDashboard/Sheet">
    <custom-parameter name=":render" value="true"></custom-parameter>
</tableau-viz>
```

***

## How Curator handles this

Curator automatically generates the appropriate `<custom-parameter>` elements when a dashboard is embedded using
Embedding API v3. This is controlled by the dashboard's **Embedded Options** settings in the Curator backend.

The following parameters are handled automatically by Curator:

| Parameter        | Controlled by                                                      |
| ---------------- | ------------------------------------------------------------------ |
| `:render`        | **Render Client-Side** setting in the Advanced tab                 |
| `:refresh`       | **Refresh Data** setting in the Advanced tab                       |
| `:linktarget`    | **Link Target** setting in the Advanced tab                        |
| `:subscriptions` | **Show Toolbar** + **Hide Subscribe** settings in the Advanced tab |
| `:alerts`        | **Show Toolbar** + **Hide Alerts** settings in the Advanced tab    |

When Curator renders a v3 embed, it translates the dashboard's saved settings into `<custom-parameter>` child
elements inside the `<tableau-viz>` component. You do **not** need to manually add parameters to the Tableau
Server Dashboard URL.

***

## Fixing broken parameters: verify client-side rendering is enabled

The most common case where this issue surfaces is with the `:render=True` parameter, which forces Tableau to use
client-side (browser) rendering instead of server-side (image) rendering. If you had appended `?:render=True`
to the Tableau Server Dashboard URL in the Curator backend, it will be ignored in v3.

In Curator, **Render Client-Side** is enabled by default, so most dashboards will already produce the correct
`<custom-parameter>` output without any changes. However, if you have previously set this to a different value
or are seeing unexpected rendering behavior, verify the setting:

1. Navigate to the Curator backend > **Tableau** > **Dashboards**.
2. Select the Dashboard you want to configure.
3. Switch to the **Advanced** tab and open the **Embedded Options** section.
4. Verify that the **Render Client-Side** toggle is enabled.
5. Save the Dashboard if you made any changes.

Curator will then render the correct `<custom-parameter name=":render" value="true">` element inside the
`<tableau-viz>` web component automatically.

***

## Curator URL parameters vs. Tableau Server Dashboard URL parameters

It is important to distinguish between two different types of URL parameters:

**Curator URL query parameters** (e.g., `https://your-curator.com/dashboard?Region=West`) are still fully
supported in v3. Curator picks these up and converts them to filter and parameter values applied via the
Tableau JavaScript API. See [Preloading Filters and Parameters](/embedding_using_analytics/filters_parameters/preloading_filters_and_parameters#preload-behavior)
for details.

**Tableau Server Dashboard URL parameters** (e.g., appending `?:render=True` to the URL in the **Tableau Server
Dashboard URL** field in the Curator backend edit page) are **not supported in v3**. These must be replaced with
the equivalent Curator embedding option settings as described above.

| Parameter type                                        | v3 supported? | How to use it                            |
| ----------------------------------------------------- | ------------- | ---------------------------------------- |
| Curator URL query params (`?Region=West`)             | Yes           | Passed as filters/parameters via the API |
| Tableau Server Dashboard URL params (`?:render=True`) | No            | Use Curator's Embedded Options instead   |

***

## Additional resources

* [Tableau Embedding API v3: Custom Parameters](https://help.tableau.com/current/api/embedding_api/en-us/docs/embedding_api_parameters.html#apply-custom-parameters-during-customization-using-web-components)
* [Tableau Server: Browser Rendering](https://help.tableau.com/current/server/en-us/browser_rendering.htm)
* [Curator: Dashboard Settings](/embedding_using_analytics/tableau_dashboards/dashboard_settings)
* [Curator: Preloading Filters and Parameters](/embedding_using_analytics/filters_parameters/preloading_filters_and_parameters)


# Custom Views
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/custom_views

Configure and enable custom views functionality to allow users to save and reload dashboard states with applied filters and parameters.

Curator can allow users to save a Custom View of a Dashboard, which will include any applied filters and parameters, and
then load it again at a later date.

## Enable Custom Views

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Curator** > **Portal Settings** in the left-hand side navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Click to switch on the "Custom Views" setting under the "Toolbar Buttons (Tableau Actions)" section and click the
   "Save" button.

## Enable create/load a Custom View

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Modify the filters, etc. as desired on the Dashboard.
5. Click on the Custom Views icon at the top right portion of the screen. Normally this is displayed on the right side
   of the title bar in the Dashboard.
6. Enter a name for the new Custom View in the text box and click the "Create" button.
7. To load a different Custom View, select an existing view from the drop-down and click on the "Apply" button.

## Sharing Direct Links to Custom Views

Custom Views can be shared via direct URL links, allowing users to access specific Custom Views without manually
selecting them from the dropdown. This functionality works similar to Tableau's native Custom View sharing capabilities.

### How to share a Custom View via direct link

1. **Load the desired Custom View URL** — either by applying an existing Custom View using the steps above (steps 1-7),
   or by creating a new Custom View (the URL updates immediately when the view is saved).
2. **Copy the current URL** from your browser's address bar. The URL will automatically include the Custom View parameter.
3. **Share the URL** with other users who have access to the Dashboard.

### URL Parameter Format

Custom Views are accessed through the `curator_custom_view` URL parameter (or the legacy `::custom_view` parameter for
backward compatibility). For example:

```txt theme={null}
http://curatorexample.com/dashboard-name?curator_custom_view=MyCustomViewName
```

When a Custom View is loaded, Curator automatically adds a Custom View ID parameter (`cvi`) to the URL:

```txt theme={null}
http://curatorexample.com/dashboard-name?curator_custom_view=MyCustomViewName&cvi=abc123def456
```

The `cvi` (Custom View ID) URL parameter contains Tableau's unique identifier (LUID) for the Custom View, which ensures the
correct view is loaded even if multiple Custom Views share the same name. This parameter gets automatically added to the
URL for troubleshooting purposes by Curator. If no Custom View ID is provided via URL load, the first Custom View by
match on name is selected and its ID is added as the cvi parameter.

If a URL contains both the Custom View name and ID parameters, the `cvi` parameter takes precedence to ensure
the exact Custom View is loaded. This means you can safely share URLs that include both parameters without
worrying about ambiguity.

#### Legacy URL Format

For backward compatibility, the legacy `::custom_view` parameter is still supported:

```txt theme={null}
http://curatorexample.com/dashboard-name?::custom_view=MyCustomViewName
```

However, new Custom View links will use the modern `curator_custom_view` parameter format.

### Sharing Private Custom Views

Private Custom Views are only visible in the dropdown for the user who created them. However, similar to
[sharing a Custom View in Tableau](https://help.tableau.com/current/pro/desktop/en-us/customview.htm#share-a-custom-view)
anyone with access to the Dashboard can see a Custom View using the direct link [outlined above](#how-to-share-a-custom-view-via-direct-link).


# Dashboard Created and Updated Dates
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/dashboard_dates

Display creation and last updated dates from Tableau Server on dashboard pages in Curator.

When enabled, the creation and last updated dates from Tableau Server are shown on each dashboard page.
These dates reflect activity on Tableau Server, not changes made within Curator.

## Enable Dashboard Dates

1. Navigate to **Settings** > **Tableau** > **Tableau Server Settings**.
2. Click the **General** tab.
3. Expand the **Dashboard Display** section.
4. Switch on **Show Tableau Dashboard Dates**.
5. Click **Save**.


# Dashboard Settings
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/dashboard_settings

Complete guide to configuring Tableau dashboard settings in Curator including display, functionality and integration options.

When adding a Tableau Dashboard to the Curator backend, there are several tabs that offer a range of settings to
customize the integration, display, and functionality of your Dashboard. This guide will walk you through each tab
and its available options, ensuring you make the most of Curator’s features to enhance your Tableau experience.

To access these settings:

1. Navigate to the backend of the system and log in if prompted.
2. Navigate to Tableau > Dashboards.
3. Select the Dashboard for which you want to adjust the settings.

If you have not added a Dashboard yet, check out our [Adding a Dashboard Guide](/embedding_using_analytics/tableau_dashboards/adding_a_dashboard)

Below, you find detailed explanations of all the toggles, input fields, and settings within each tab:

## Tab: Dashboard

This tab contains the primary settings for adding a Tableau Dashboard to Curator. When you select a Dashboard
from the dropdown fields, the input fields below will automatically populate with the corresponding values.

* **Title**: The name of the Dashboard as it will appear in the Curator portal. It automatically picks up the
  title of your Dashboard from Tableau, but you can adjust it here if you prefer a different title. If you want
  to change titles in Curator, ensure you have the *Use Curator Dashboard Titles* toggle enabled in your Portal
  Settings (Backend > Settings > Curator > Portal Settings > Features tab > Usability section).

* **Tableau Server Dashboard URL**: The direct URL to the Dashboard on Tableau Server. No changes are needed here.
  This is useful for ensuring you are embedding the correct Dashboard - copying and pasting this into a new tab
  ensures you're certain of the Dashboard you're embedding.

* **Curator Dashboard URL "Slug"**: The ending of the URL used to access the Dashboard in Curator. You can adjust
  this as needed, but note that special characters are not supported. The full link to your Dashboard is displayed
  in the top right corner of the edit-Dashboard page.

* **Dashboard Tabs**: Determines whether or not other Dashboards published in the workbook should be shown
  and how. The display options are:

  1. **Off** - Do not show any other Dashboards from this workbook.
  2. **Styled (Web Friendly)** - Show tabs that can be styled in the Themes (Backend > Settings > Curator > Themes >
     select your Theme > *Title and Toolbar* tab). Check out our Design options [here](/site_content_design/theme/titles_and_toolbars).
  3. **Tableau Server Native** - Show tabs as they appear on Tableau Server. When using this option it is important to
     know that Tableau renders the Dashboard with the largest dimensions assigned in the workbook. This may lead to
     scroll bars within the iframe. Please refer to the [Knowledge Base article for more info](https://help.salesforce.com/s/articleView?id=001474123\&type=1).

  **Note:** This selection field is influenced by two factors:

  1. To make a selection, you need to publish your workbook with sheets as tabs.
  2. A global setting takes precedence over whether or not you can show tabs. This setting is found in Tableau
     Server Settings (Backend > Settings > Tableau > Tableau Server Settings > Workbooks section
     > **Global Dashboard Tabs** selection field). When the global setting is set to Styled or Native, it
     > overrides the individual Dashboard Tabs selection — including for dashboards with **Treat as Workbook**
     > enabled. The one exception is when the global setting is **Off**: dashboards with Treat as Workbook
     > ignore the Off setting because workbook-mode navigation requires tabs. In that case, the form displays
     > an inline message explaining the override.

## Tab: Discovery

This tab focuses on how the Dashboard will be discovered within the Curator portal.

* **Search & Content Discovery**: Add keywords to associate with your Dashboard. When users search for the specified
  keyword, the Dashboard will appear in the results. To add new keywords refer to [this guide](/site_content_design/content_discovery/keywords).

  If you turn on the **Hidden** switch, this Dashboard will not be discoverable through search, and it will not be
  displayed in any tiles or in the Explorer.

  The **Featured** flag adds the Dashboard to the list of featured Dashboards. This list can be used for content
  selection in Tiles, Explorer, Feed, and List elements on your pages.

* **Description**: Add context to your Dashboard. This information can be displayed in two places:

  1. **On hover over tiles**:
     * The global setting can be adjusted in Themes (Backend > Settings > Curator > Themes > select your Theme >
       Pages tab > Tiles Styles on the left-hand side > *Show Tile Description* selection field).
     * The individual setting is on the Page > Tiles Element > Tiles Settings > *Show Description*.
     * **Note:** The global setting will enable the individual setting.
  2. **In the toolbar**: Show the description when navigating to the frontend page of the Dashboard. To enable this, go to
     Backend > Settings > Curator > Portal Settings > Features tab > Toolbar Buttons
     (Curator Actions) > switch on *Dashboard Info Button*.

* **Related Content**: Associate menu items with your Dashboard. You can set how related content is displayed in
  Backend > Settings > Curator > Portal Settings > Features tab >
  Usability section > *Related Content Position* selection field.

* **New & Updated Flags**: Use the toggles to manually add a flag to the Dashboard that notifies your users.

## Tab: Display

In this tab, you can configure the visual aspects and layout of how the Dashboard will be displayed within Curator.

* **Thumbnail/Icon**: This displays the current thumbnail of your Dashboard, retrieved using Tableau's REST API
  during regular cron jobs. You can delete the current image by clicking the "x" next to the file name.
  In *Alternate Thumbnail URL*, you can specify a different URL to retrieve the thumbnail. If you want to
  refresh the thumbnail immediately, use the *Refresh Thumbnail* button. If you prefer to upload a static image,
  use the *Icon Image* file upload instead.
  *Note: Tableau Public dashboards cannot have their thumbnails generated automatically, because Tableau Public
  retired the image download endpoint Curator relied on. These dashboards will display a generic placeholder, so
  use the Icon Image upload above if you want a real image.*
  *Views with very large fixed layouts are automatically scaled down to thumbnail size. In rare cases an extremely
  large view may still fall back to the generic placeholder — set an Alternate Thumbnail URL pointing to a smaller
  view, or upload a static image instead.*

* **Loading Screen**: Select the loading screen to display while this Dashboard is loading. If you want to add new
  loading screens to the options, check out [this guide](/site_content_design/loading_screens/loading_screens).

* **Tutorial**: Select a tutorial to show when users navigate to the Dashboard.
  [This guide](/site_content_design/user_notifications_and_email/tutorials)
  walks you through the steps of how to create a tutorial.

* **Comments**: Enable [*User Commenting*](/embedding_using_analytics/data_manager/user_commenting)
  if you want to allow users to add comments to the Dashboard. To use this feature, you need to have Data Manager
  enabled. If you don't have Data Manager enabled yet, refer to [these steps](/embedding_using_analytics/data_manager/data_manager_basics).
  Comments are stored in the Curator database in the `interworks_datamanager_comment` table.

* **Mobile**: Point to a different Dashboard on Tableau Server for use in mobile view. *Note* that this feature is
  deprecated and will be removed in a future release.

* **Dashboard Dates**: To show the creation and last updated dates from Tableau Server on dashboard pages,
  see the [Dashboard Created and Updated Dates](/embedding_using_analytics/tableau_dashboards/dashboard_dates) guide.
  This is a global setting configured in Tableau Server Settings, not per-dashboard.

## Tab: Filters

The Filters tab allows you to configure the filters and parameters available for users interacting with the Dashboard.

* **Filters**: Add any of the selectable Curator filters to the Dashboard. Filters that don't match any field in your
  applied data source will be greyed out.
  Check out [this guide](/embedding_using_analytics/filters_parameters/filters)
  to add new Filters.

* **Parameters**: Add any of the selectable Curator parameters to the Dashboard. Parameters that don't match any field
  in your applied data source will be greyed out.
  Check out [this guide](/embedding_using_analytics/filters_parameters/parameters)
  to add new Parameters.

* **Specify Filter Sheet**: Specify a sheet from your Dashboard to retrieve filter or parameter options if you want to
  customize Curator's default behavior. Check out
  [this documentation](/embedding_using_analytics/filters_parameters/specify_filter_sheet)
  for all the details.

* **Ignore Filter and Parameter Changes from Dashboard**: By default, Curator listens to filter and parameter changes
  made within the Dashboard and adds them to the Curator URL. This allows the Dashboard to be reloaded with the same
  filters and parameters applied without resetting them. If you prefer not to have this behavior for your Dashboard,
  turn on this switch.

* **Enable Filter Actions**: When enabled, Curator listens for Tableau filter actions (e.g., clicking a mark to filter
  other visuals) and appends them to the URL. This can be enabled individually per Dashboard or globally in
  Settings > Tableau > Tableau Server Settings.

## Tab: Advanced

This tab provides access to more advanced settings and customizations.

* **Data Export Options**: Configure export options for your users. If allowing CSV and/or Excel exports, you can
  either show a list of worksheets for data export or specify a worksheet for automatic download. Alternatively,
  you can specify a link for the export in the *Alternate CSV Link* field. You can also provide an *Alternate PDF
  Link* for downloading in PDF format. *Note*: You need to enable the export features in
  Backend > Settings > Curator > Portal Settings > Features Tab > Toolbar Buttons (Tableau Actions) section.

<Warning>
  **Alternate CSV and PDF links are not compatible with Connected Apps authentication.** When a user clicks an
  alternate CSV or PDF link, the browser opens the Tableau Server or Tableau Cloud URL directly in a new tab as a
  plain request with no embed token attached. Tableau validates these direct requests using a browser session cookie,
  which Connected Apps authentication never creates — the signed JWT embed token authenticates only the embedded
  iframe, not the browser session. As a result, users are redirected to a Tableau login page instead of receiving the
  download.

  If your portal uses Connected Apps, use Curator's built-in **CSV** and **Excel** export buttons instead. These run
  inside the authenticated embed iframe via Tableau's Embedding API and do not depend on a browser session cookie.
</Warning>

* **Report Builder**: If Report Builder is enabled, you can specify a sheet for export to presentations in the
  *Use PPTX Tab* field. You can also specify an *Alternate Report Builder Dashboard Link* to use this Dashboard
  for export instead. More details on the Report Builder feature are documented
  [here](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder).

* **Embedded Options**: Adjust these settings to refine how your Dashboard is embedded in Curator. Your options are:
  1. **Link Target**: Override where links from within the Dashboard should load. For more information, see
     the [URL Action Overrides](/embedding_using_analytics/tableau_dashboards/url_action_overrides_link_target) guide.
  2. **Show Toolbar**: Switch on if you want to show the Tableau Server toolbar below the Dashboard, in addition
     to or instead of the Curator toolbar. If enabled, you can also choose to hide the Subscribe and Alert buttons from the
     Tableau Server toolbar.

     **Note:** There is also a global **Show Toolbar** switch. You will find it at Backend > Settings >
     Curator > Portal Settings > Features tab > Toolbar Buttons (Tableau Actions). The toolbar appears
     when either switch is on. While the global switch is on, every Dashboard shows the toolbar, and the
     switch here cannot turn it off. Check both places if the toolbar appears where you do not want it.
  3. **Refresh Data**: Switch on to ensure you are loading the latest data, not a cached version from Tableau Server.
     *Note*: This might significantly affect the Dashboard's loading time.
  4. **Render Client-Side**: Override the Tableau Server's configured behavior for this specific Dashboard. Check out
     [this article](https://help.tableau.com/current/server/en-us/browser_rendering.htm) for more details.
     If you previously passed `:render=True` as a URL parameter on the Tableau Server Dashboard URL, use this
     setting instead — URL parameters on the Tableau Server Dashboard URL are not supported in Embedding API v3.
     See [Custom Parameters in Tableau Embedding API v3](/embedding_using_analytics/tableau_dashboards/custom_parameters_v3)
     for full details.

* **Miscellaneous**:
  * **Dashboard Timer**: If enabled, a small timer is displayed in a corner of the screen when accessing a Dashboard
    on the frontend.
  * **Disable URL Filter**: Filter/parameter changes will not be added to the URL and will be ignored when loading the
    Dashboard with respective parameters.

* **Custom Code**: Add your own JavaScript snippets here to customize the Dashboard experience. **Important**: We
  cannot guarantee your code will work, as we cannot test it, and we cannot offer support for Custom Code.
  Please refer to
  [this article](https://curator.interworks.com/curator-is-sunsetting-custom-code-support-what-you-should-know)
  for more information.

## Tab: Workbook Settings

This tab groups the workbook-scoped settings that apply to how this Dashboard behaves within its Tableau workbook.

* **Treat as a Workbook?**: Turn on if you want all Dashboards in this workbook to be listed under this Dashboard's
  menu item. Turning this on also enables tabs on the Dashboard. Ensure the workbook is published with tabs on
  Tableau Server.

* **Show Workbook Title**: Turn on to display the Tableau Server workbook name in place of this Dashboard's title in
  the frontend heading. The heading stays fixed on the workbook name when users switch between tabs of the same
  workbook or trigger URL actions on the Dashboard. The Dashboard's own Title field (used in the backend, tiles,
  search results, and everywhere else the Dashboard is listed) is not affected. If the workbook name is unavailable
  from the stored Tableau metadata, the frontend heading falls back to the Dashboard's Title.

## Tab: Mark Commenting

In this tab, you can configure the mark commenting functionality, allowing users to leave comments on specific
marks within the Dashboard.

* **Inline Mark Commenting**: Details on Inline Mark Commenting and how to set it up can be found in
  [this documentation article](/embedding_using_analytics/data_manager/mark_commenting).

* **Tableau Group Whitelist**: Add groups from Tableau Server if you want to restrict commenting permissions to
  specific groups only.

***

If you encounter any unclear areas or mistakes, feel free to reach out to your lovely Curator team!


# Data Export
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/data_export

Enable and configure multiple data export options for end-users to extract data from Curator dashboards.

There are multiple ways for end-users to export data from Curator.  The current Dashboard data-exports all utilize
Tableau's standard export functionality with some optional overrides.  Check out the options below for all available
data exports you can find in Curator.

## Export CSV/Excel

Curator supports the ability to set various options when exporting data to CSV or Excel.  This functionality is supported
in large part by Tableau's native export capabilities, but Curator allows a more seamless export experience when some
guardrails are needed.

### Enable or Disable Export to CSV / Excel

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the **Features** tab and expand the Toolbar Buttons (Tableau Actions) section.
4. Toggle the switch to enable/disable Export CSV (or Export Excel) and click the "Save" button.

### Specify a worksheet when users export to CSV / Excel

If you would like to explicitly guide users to download data from a worksheet on your Dashboard (e.g. a hidden sheet
containing only the data you want them to have access to) you may find this feature very useful.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Tableau** > **Dashboards** section from the left-hand menu and select an existing Dashboard or
   create a new one.
3. Click on the **Advanced** tab and toggle OFF the "Show Worksheet Options for Data Exports" feature.
4. This will populate a dropdown below the Show Worksheet Options for Data Exports" option called
   "CSV / Excel Worksheet Export".
5. Select your worksheet from this list.
6. Click the save button.

### Enable or Disable specifying a worksheet for export CSV / Excel

By default Curator allows users to select which worksheet to export data from (reflecting the same default behavior on
Tableau Server).  However we offer additional configuration which you can see in the previous steps above.  If you would
like to disable this feature so Curator exports the first-available-worksheet follow the steps below.

<Warning>
  On multi-tab workbooks, disabling worksheet selection or pre-selecting a single worksheet restricts exports to that one
  worksheet regardless of which tab is currently active — end-users will not be able to export data from the other tabs.
  To allow exports from any visible tab, keep both the global "Worksheet Select (CSV and Excel Exports)" toggle and the
  per-Dashboard "Show Worksheet Options for Data Exports" toggle enabled.
</Warning>

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the **Features** tab and expand the Toolbar Buttons (Tableau Actions) section.
4. Toggle "Worksheet Select (CSV and Excel Exports)" to enable/disable worksheet selection options globally.
5. Click the save button.

### Exporting from Tableau Stories

CSV and Excel export is supported from embedded Tableau Stories. With worksheet selection
enabled, the dropdown populates with the worksheets contained in the **active story point** and
refreshes as users navigate between story points. Selecting a worksheet and choosing CSV or
Excel exports that worksheet's data, the same as on a Dashboard.

## View Data

Frequently, users need to be able to view the underlying data within a Dashboard to get more details on the data they're
looking at.  The View Data option exposes this row-level data, and allows users to export this data as well.

<Note>
  The Data option in the Download menu carries a small information icon directly after the word "Data". Hovering over
  that icon (not the Data option itself) shows the hint "Select at least one sheet before the data export can start".
  Tableau does not export anything when no worksheet is selected, and it gives Curator no reliable way to detect that
  after the fact, so the requirement is surfaced next to the button label rather than as an on-screen message after
  clicking.
</Note>

### Enable or Disable View Underlying Data

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the **Features** tab and expand the Toolbar Buttons (Tableau Actions) section.
4. Toggle the switch to enable/disable Export Data and click the "Save" button.


# Download Workbook
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/download_workbook

Configure and enable workbook download functionality for users to download Tableau workbooks directly from Curator.

Curator can allow users to download the Tableau workbook.

## Enable Workbook Downloads

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Curator** > **Portal Settings** in the left-hand side navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Click to switch on the "Export Workbook" setting under the "Toolbar Buttons (Tableau Actions)" section and click the
   "Save" button.

### Download a Tableau workbook

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Click on the download workbook icon at the top right portion of the screen. Normally this is displayed on the right
   side of the title bar in the Dashboard.


# Email Subscriptions
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/email_subscriptions

Set up automated email notifications for users when Tableau Server views are updated with new data.

Curator allows users to subscribe to dashboards where updates to the underlying Tableau Server views will be emailed to
them on a set schedule.

## Known Limitations

There is currently a limitation in Tableau's APIs that make subscribing to Custom Views unavailable for embedded
applications.  Curator can only create a subscription to the Dashboard's default view through Tableau's subscription
engine.  However,
[Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder)
supports subscriptions to Custom Views.

This functionality requires that the Tableau Server REST API is enabled. This allows you to subscribe to a Dashboard or
to the workbook the Dashboard belongs to on the associated Tableau Server.  See the
[Tableau Connection Setup](/creating_integrations/tableau_connection/creating_a_connection)
section for more information.

***To enable email subscriptions:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Curator** > **Portal Settings** in the left-hand side navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Click to switch on the "Subscriptions" setting under the "Toolbar Buttons (Tableau Actions)" section and click the
   "Save" button.

***To subscribe to an eligible Dashboard/workbook:***

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Click on the envelope icon at the top right portion of the screen. Normally this is displayed on the right side of
   the title bar in the Dashboard.
5. Select the desired schedule.
6. Select either workbook or Dashboard in the dropdown to receive subscriptions.
7. Click on the "Add Subscription" button.


# Generating Titles
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/generating_titles

Configure how dashboard page titles are generated, choosing between Curator-defined names or Tableau Server dashboard names.

When viewing dashboards via Curator, you can choose whether or not the page title is retrieved from the name you have
entered in the edit-Dashboard page or the name of the Dashboard on Tableau Server.

## Specify where your Dashboard titles are retrieved from

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. In the Features tab, expand the Usability section and find the *Use Curator Dashboard Titles* switch.
4. Toggle the switch to enable/disable *Use Curator Dashboard Titles* and click the "Save" button.

## Show the Tableau Server workbook name instead

You can also override the frontend heading on a per-Dashboard basis to display the workbook name from Tableau Server
instead of the Dashboard's own name. In the Dashboard edit page, open the **Workbook Settings** tab and turn on
**Show Workbook Title**. When enabled, the frontend `<h1>` heading renders the workbook name and remains fixed on
that name as users switch between tabs of the same workbook. The Dashboard's own Title field is unchanged and is
still used everywhere the Dashboard is listed in the backend. If the workbook name is not available from the stored
Tableau metadata, the heading falls back to the Dashboard's own Title.


# Pause and Resume Changes
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/pause_and_resume_changes

Enable users to pause dashboard refreshes while applying multiple filters and parameters for better performance.

Curator can allow users to pause a Dashboard so that multiple changes (e.g. applying multiple filters) can be made
before the Dashboard is refreshed.

## Enable Dashboard Pause

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Curator** > **Portal Settings** in the left-hand side navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Click to switch on the "Pause Dashboards" setting under the "Toolbar Buttons (Tableau Actions)" section and click
   the "Save" button.

## Pause a Dashboard

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Click on the pause layout updates icon at the top right portion of the screen. Normally this is displayed on the
   right side of the title bar in the Dashboard.
5. Make any desired changes to the filters, parameters, etc.
6. Click on the resume layout updates icon at the top right portion of the screen to apply all changes at once.


# Share Workbook
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/share_workbook

Enable workbook sharing functionality to allow users to share Tableau workbooks directly from Curator.

Curator can allow users to share the Tableau workbook.

## Enable workbook sharing

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Curator** > **Portal Settings** in the left-hand side navigation.
4. Click on the "Features" tab at the top of the main page content.
5. Click to switch on the "Share" setting under the "Toolbar Buttons (Tableau Actions)" section and click the "Save" button.

## Share a Tableau workbook

1. Navigate to the frontend of the system (e.g. `https://www.curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Click on the share icon at the top right portion of the screen. Normally this is displayed on the right side of the
   title bar in the Dashboard.


# Tableau Worksheets and Stories
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/tableau_worksheets_and_stories

Learn how to embed and configure individual Tableau worksheets and stories alongside dashboards in Curator.

In certain situations, especially if your Tableau Server's metadata API is disabled,you will be able to embed
single worksheets or stories instead of a Tableau Dashboard. Although it is technically possible it is not fully
supported as Tableau embedding API is limited in this area.

We added an informational popup to let the front end user know that, especially the toolbar buttons' functionality
is limited. If you wish to hide this information from your users you can simply disable it with the following steps:

1. Login to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend`).
2. Navigate to the **Settings** > **Tableau** > **Tableau Server Settings** section from the left-hand menu.
3. Under the "General" tab, look for the *Workbooks* section.
4. Enable the switch "Hide 'not a Dashboard' info".
5. Click the "Save" button.

The easiest workaround to avoid this situation of limited functionality is to put the worksheet on a Dashboard and
republish your workbook with visible sheets and stories.


# URL Action Overrides (Link Target)
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_dashboards/url_action_overrides_link_target

Configure URL actions in Tableau dashboards to control link behavior and user navigation within Curator.

When a URL action gets triggered in Curator, there are different settings that allow Curator to handle these actions in
a more sophisticated manner directing your users to the location they want to end up without much intervention in the
middle.  You can find a description of the available options at the bottom of this page.

## Set the Link Target

1. Login to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend`).
2. Navigate to the **Tableau** > **Dashboards** section from the left-hand menu.
3. Click the Dashboard you'd like to edit from the list page.
4. Under the "Advanced" tab, look for the *Embedded Options* section.
5. Change the Link Target field to the desired option (see below for descriptions)
6. Click the "Save" button.

### Available Options

*Default*
By default, Curator handles the URL as defined in the Tableau Dashboard.

*Self*
The URL Action defined in the Tableau Dashboard will load within the embedded frame on the page keeping the user in the
same location.

*Parent*
The URL Action defined in the Tableau Dashboard will change the location of the current browser tab the user is on
navigating them away from the current page.

*Blank*
The URL Action defined in the Tableau Dashboard will open in a new browser tab.

*Curator Detect*
Curator inspects the URL produced by the URL Action and checks whether it matches a Dashboard page in the current
user's navigation within Curator. If a match is found, it directs the user to that Curator page in the same browser
tab — preserving any query-string filters appended to the URL. If no match is found, it opens the URL in a new browser
tab instead.

*Curator Detect New Tab*
The same behavior as Curator Detect, only in both scenarios it opens up a new tab.

### Passing Filters through URL Actions

When passing filters through URL Actions on a Tableau Dashboard, Tableau has good documentation on how to set this up
[here](https://help.tableau.com/current/server-linux/en-gb/actions_url.htm?source=productlink#Using). For a complete
walkthrough of configuring a URL Action to pass filters and navigate users to a filtered Curator Dashboard, see
[Navigate to a Filtered Curator Dashboard via a URL Action](/embedding_using_analytics/tableau_dashboards/cross_dashboard_navigation_url_actions).


# Adding a Pulse Metric
Source: https://docs.curator.interworks.com/embedding_using_analytics/tableau_metric/adding_a_pulse_metric

Add and configure Tableau Pulse metrics for real-time dashboard performance monitoring and alerts.

In December 2023, Tableau Cloud introduced an innovative feature known as Pulse,
**which is not available in Tableau Server**.
This significant update ushered in the era of Metrics. With Pulse Metrics, users gain the ability to track individual
metrics and leverage guided exploration to gain deeper insights into their data.

Beyond just viewing metrics within Curator, you can also immediately send or subscribe to insightful digests via email.
These digests highlight crucial data changes, ensuring users always stay informed and updated.

Metrics from Tableau Pulse can be added easily to Curator using your existing
[Tableau Cloud connection](/creating_integrations/tableau_connection/creating_a_connection).

You can either create a new Metric within Curator, or add an existing one that has already been created in Tableau Pulse.

## Adding a Metric to Curator

### Create a new Metric

1. Navigate to the backend of the system (e.g. [http://curatorexample.com/backend](http://curatorexample.com/backend))
   and log in if prompted.
2. Navigate to **Tableau** > **Metrics**.
3. Click on the "New Metric" button.
4. Select the respective **Tableau Server** and **Site** drop-downs.
5. Set the **Metric Definition** dropdown to "Create New", then select the **Project** and **Data Source** you'd like to
   use.
6. Fill out the **Definition** selections in the **Details** tab to follow the specific metric.
7. Be sure to save!

### Add an existing Metric (already created on Tableau Pulse)

1. Navigate to the backend of the system (e.g. [http://curatorexample.com/backend](http://curatorexample.com/backend))
   and log in if prompted.
2. Navigate to **Tableau** > **Metrics**.
3. Click on the "New Metric" button.
4. Select the respective **Tableau Server** and **Site** and **Metric Definition** drop-downs.
5. Confirm the **Definition** selections in the **Details** tab to follow the specific metric.
6. Be sure to save!

## Embedding a Metric in Curator

By default, Metrics will have their own standalone pre-built template page that you can link to - this link can be found
on the edit-Metric page in the backend.

### Adding a Metric to a page

In addition to Curator's standalone templates, you can also add metrics to pages along side other content like images,
forms, Tableau Dashboards and even other metrics.  To add a metric to a page:

1. Navigate to the backend of the system (e.g. [http://curatorexample.com/backend](http://curatorexample.com/backend))
   and log in if prompted.
2. Navigate to **Content** > **Pages**.
3. Either find your page in the list you want to add your metric to or click "+ New Page" to create a new page.
4. Hover over the area of the page you'd like to add the Metric to, or click an element and click the "Change Element"
   button to display the element selection options.  Then select the Analytic Elements tab and click on "Tableau Metric":
   <img alt="Modal showing analytic elements and highlighting Tableau metric option" />
5. Use the left-hand Page Styles controls to select the metric you want to embed.
6. Be sure to save!

## Supported Features

When a Pulse Metric is embedded in Curator, the following interactive features are available to end users:

* **Headline stat with comparison** -- displays the current metric value along with the relative percentage and absolute
  change versus the prior period, plus the time-period range it covers.
* **Sparkline trend chart (Overview)** -- an inline Vega-Lite trend visualization rendered alongside the headline stat.
* **Dimension/breakdown toggle** -- users can switch between an *Overview* (trend) view and a *Breakdown* (dimension-level
  bar) view using the *Show Breakdown* / *Show Overview* button.
* **Guided insight text** -- textual insights generated by Tableau that explain metric changes (e.g., "Revenue is up 25%").
* **Favorite/bookmark** -- users can mark a metric as a favorite so it appears in their favorites.
* **Email digest** -- users can immediately send or subscribe to email digests that include the headline stat and trend image.

## Limitations

The following Tableau Pulse features are **not** currently available in Curator's embedded metric experience:

* **Ask Questions** -- the natural language query interface available in native Tableau Pulse is not supported.
* **Top Insights / Springboard** -- exploratory insights beyond the anchor and breakdown views are not rendered on the page.
* **Dynamic filtering** -- end users cannot add or modify filters; only the pre-configured *allowed dimensions*
  (set at authoring time in Tableau) are applied.
* **Custom time periods** -- the metric's granularity, time comparison, and range are fixed in its definition
  (configured in Tableau / when creating the Metric) and cannot be changed by end users while viewing the page.
* **Real-time refresh** -- insights are fetched once when the page loads; there is no live refresh or user-driven data
  update on demand.

## Accessing a Metric

In order to access a Metric on Curator, you must have a valid connection to Tableau Cloud.  The username you log in with
to the front-end of Curator *must match exactly* with the associated username on Tableau in order to properly determine
permissions.

The permissions for Metrics on Curator are based on access to the datasource that the Pulse Metric is connected to on
Tableau Cloud, or the datasource you selected on the create-Metric page. If the user you're logged in has no associated
account on Tableau, they will not be able to access the metric by default.  You can further restrict these permissions
by using the **[Restrict Access](/site_content_design/menus/restrict_access)**
menu permissions.


# ThoughtSpot Full App Embed
Source: https://docs.curator.interworks.com/embedding_using_analytics/thoughtspot_content/thoughtspot_full_app

Embed the complete ThoughtSpot application experience within Curator using the Page Builder.

If you have [integrated ThoughtSpot](/creating_integrations/thoughtspot_connection/integrating_thoughtspot_with_curator),
you can follow this guide to add a ThoughtSpot Full App Embed to Curator.

## Creating the ThoughtSpot Full App Embed

The ThoughtSpot Full App Embed is available directly in the Page Builder, allowing you to embed the complete
ThoughtSpot application experience within your Curator pages.

1. <BackendNavPath /> Find the page you'd like to add your embed to, or create a new page.
2. In the Page Builder, select an existing element from the preview and click the "Change Element" button. You can also
   add a new element.
3. Choose the "Analytic Elements" category then the "THOUGHTSPOT FULL APP" element.
   <img alt="Full app modal element" />
4. Once the element is added, choose the Org where your ThoughtSpot data lives from the left-hand panel:
   <img alt="Import SAML metadata" />
5. Finally choose the Homepage experience you'd like to use:
   <img alt="Search bar dropdown" />
   * **Classic Homepage** (default) - The traditional ThoughtSpot homepage experience
     <img alt="Classic homepage embed" />
   * **Spotter Homepage** - ThoughtSpot's new natural language search interface
     <img alt="Spotter Homepage embed" />

## Adding the ThoughtSpot Full App Embed to the Curator Frontend

Once configured in the Page Builder, the ThoughtSpot Full App Embed will be displayed on your page, providing users
with access to the complete ThoughtSpot application interface. Users will need appropriate ThoughtSpot permissions
on the configured Org to access the embedded application.

You can make the page containing the Full App Embed more discoverable by:

1. Adding it to your [navigation](/site_content_design/menus/managing_menus).
2. Creating a [tile](/site_content_design/pages/tiles) that links to the page.
3. Adding keywords to the page so it can be easily found via Curator's search or in the [explorer](/site_content_design/pages/explorer).


# ThoughtSpot Search
Source: https://docs.curator.interworks.com/embedding_using_analytics/thoughtspot_content/thoughtspot_search

Integrate ThoughtSpot search functionality for natural language query capabilities within Curator.

If you have [integrated ThoughtSpot](/creating_integrations/thoughtspot_connection/integrating_thoughtspot_with_curator)
you can follow this guide to add ThoughtSpot Search to Curator.

## Creating the ThoughtSpot Search

1. Navigate to the Curator backend > ThoughtSpot > ThoughtSpot Searches and click the "New ThoughtSpot Search" button.
2. Choose the Org where the data you'd like to search against lives.
3. Choose the type of search. The types include:
   1. Spotter - ThoughtSpot's new natural language search feature (replaces deprecated Sage)
   2. Standard Search - The standard ThoughtSpot Search experience
   3. Standard Search w/ Pre-made Answer - The standard Search experience, but initially loading with an Answer
4. Choose the data source or Answer you'd like the Search to load with, or none if you'd like the user to begin with a
   blank slate.
5. In the "Details" section, add a title. This will automatically generate a slug but feel free to overwrite it.
6. In the "Discovery" section, add keywords, a description, etc.
7. Hit the "Save" button.

## Adding the ThoughtSpot Search to the Curator Frontend

The ThoughtSpot Search is now created and accessible to Curator users, assuming they have ThoughtSpot users on the Org
being searched against. You can make the Search more discoverable in several ways:

1. Add it to your navigation.
2. Add it to a [page](/site_content_design/pages/pages_overview) directly.
3. Add it to a page as a [tile](/site_content_design/pages/tiles).
4. Add keywords so it can be easily found via Curator's search or in the [explorer](/site_content_design/pages/explorer).


# Curator SaaS
Source: https://docs.curator.interworks.com/get_started/curator_saas

Deploy a branded analytics portal in minutes with no-code simplicity and expert guidance

**Curator SaaS** is the recommended deployment option for most organizations, offering rapid implementation, expert guidance, and a fixed-cost model. Build a branded, no-code analytics portal in minutes, not months.

<Info>
  Ready to get started? Fill out our [contact form](https://interworks.com/contact) to learn more.
</Info>

## Choosing Curator SaaS

Curator SaaS transforms the traditional analytics portal deployment from a months-long technical project into a streamlined 2-week implementation with expert guidance included.

### Key Advantages

<CardGroup>
  <Card title="Rapid Deployment" icon="rocket">
    **Deploy in as little as 2 weeks** with dedicated expert guidance from the InterWorks team
  </Card>

  <Card title="No-Code Portal Builder" icon="wand-magic-sparkles">
    Build and customize your portal without any technical development resources
  </Card>

  <Card title="Unlimited Users" icon="users">
    Scale to your entire organization with unlimited users (fair use policies apply)
  </Card>

  <Card title="Fixed-Cost Model" icon="badge-dollar">
    Predictable pricing with no surprise infrastructure costs or maintenance fees
  </Card>

  <Card title="Expert Support" icon="headset">
    Dedicated support and guidance from analytics platform specialists
  </Card>

  <Card title="Automatic Updates" icon="cloud-arrow-up">
    Always stay current with the latest features and security updates
  </Card>
</CardGroup>

***

## SaaS requirements

To use Curator SaaS, ensure you meet the following technical requirements:

* **Supported Browsers:** Latest versions of Chrome, Firefox, Edge, or Safari
* **Network Access:** Ability for any of your hosted platforms (e.g. Tableau) to connect to Curator SaaS endpoints.
* **Data Security:** Compliance with your organization's data security policies, as Curator SaaS acts as a pass-through
  for your analytics content.

If you opt to use the legacy Self-Hosted deployment, please refer to the
[Self-Hosted Technical Requirements](https://curator.interworks.com/docs/installation/self_hosted_requirements) for
detailed specifications.

## SaaS vs. Self-Hosted

Not sure which deployment model is right for you? Here's a comparison:

| Feature                          | Curator SaaS            | Self-Hosted                               |
| -------------------------------- | ----------------------- | ----------------------------------------- |
| **Technical Expertise Required** | None                    | Moderate to High                          |
| **Infrastructure Management**    | Managed by InterWorks   | Customer managed                          |
| **Maintenance & Updates**        | Automatic               | Manual                                    |
| **Scalability**                  | Automatic               | Customer configured                       |
| **Pricing Model**                | Fixed cost, predictable | Variable infrastructure costs             |
| **Best For**                     | Most organizations      | Legacy systems, specific compliance needs |

<Note>
  **Recommendation:** Curator SaaS is the ideal choice for most organizations. Self-hosted deployments are primarily for existing customers or organizations with specific regulatory requirements.
</Note>

***

## Quick Start Resources

Once your SaaS instance is set up, these guides will help you make the most of Curator:

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/setup/trial_quick_start_guide/getting_started">
    Get up and running with your Curator SaaS portal
  </Card>

  <Card title="5-Minute Tutorial" icon="graduation-cap" href="/tutorials/get_started_with_curator_in_5_minutes">
    Learn the basics in just 5 minutes
  </Card>

  <Card title="Adding Content" icon="plus" href="/tutorials/backend_administration/quick_start_adding_content">
    Add dashboards and content to your portal
  </Card>

  <Card title="Customizing Your Portal" icon="palette" href="/tutorials/backend_administration/quick_start_styling">
    Apply branding and customize the look and feel
  </Card>
</CardGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How long does implementation take?">
    Most Curator SaaS implementations are completed in **2 weeks** with dedicated expert guidance. This includes platform integration, initial configuration, and training.
  </Accordion>

  <Accordion title="Can I connect multiple BI platforms?">
    Yes! Curator SaaS supports connections to Tableau, Power BI, ThoughtSpot, and Sigma.
  </Accordion>

  <Accordion title="What about user limits?">
    Curator SaaS includes **unlimited users** with fair use policies. Scale to your entire organization without worrying about per-seat licensing.
  </Accordion>

  <Accordion title="Is my data secure?">
    Yes. Curator SaaS follows enterprise-grade security practices. All data transmission is encrypted, and Curator acts as a secure pass-through for your analytics content. [Learn more about security →](/best_practices/security/password_settings)
  </Accordion>

  <Accordion title="Can I migrate from self-hosted to SaaS?">
    Yes! InterWorks can help you migrate your existing self-hosted Curator installation to SaaS. [Contact support](https://interworks.com/help) to discuss migration options.
  </Accordion>

  <Accordion title="Are there limits on SaaS that I get with self-hosted?">
    You won't lose any features by using Curator SaaS. In fact, SaaS users often gain additional benefits like automatic updates and dedicated support.
  </Accordion>

  <Accordion title="What level of support is included?">
    Curator SaaS includes dedicated support from the InterWorks team, including initial setup guidance, ongoing technical support, and access to documentation and tutorials.
  </Accordion>
</AccordionGroup>

***

## Ready to Get Started?

<CardGroup>
  <Card title="Start Free Trial" icon="rocket" href="https://curator.interworks.com/trial">
    Try Curator SaaS free for 30 days
  </Card>

  <Card title="Contact Sales" icon="comments" href="https://interworks.com/help">
    Speak with our team about your needs
  </Card>

  <Card title="View Marketing Site" icon="globe" href="https://curator.interworks.com/curator-saas">
    Learn more about Curator SaaS features
  </Card>

  <Card title="Watch Demo" icon="video" href="https://curator.interworks.com">
    See Curator SaaS in action
  </Card>
</CardGroup>

<Tip>
  **Already have a Curator SaaS instance?** Jump straight to the [Quick Start Guide](/setup/trial_quick_start_guide/getting_started) to begin building your portal.
</Tip>


# Self-hosted
Source: https://docs.curator.interworks.com/get_started/self_hosted_overview

Quick start guide for installing Curator on various platforms

<Warning>
  Self-hosted Curator CMS no longer our recommended offering.  Check out our [Curator SaaS](/get_started/curator_saas) for a modern, fully managed experience with expert guidance and no infrastructure to maintain.
</Warning>

*If you're an existing customer looking for requirements or there is another reason why you are installing locally, this is what you need to know:*

## Server Requirements

### General Requirements

Your Curator server must be its own standalone web server. Installing on the same web server as Tableau Server is **not** supported.

Containerized deployments are also **not** currently supported.

Your Curator server will need to be able to communicate directly with your Tableau Server, and your Tableau Server will need the REST and Metadata APIs enabled.

### Curator Standard/Enterprise

If you are hosting, you will need a standalone web server on which to install the software.

This can be highly customized, but plan on following minimum specifications:

* Linux (preferred) or Windows
* At least 4 CPU, 8GB of RAM and 20GB of disk space available
* Ports open for web traffic (80 and 443)
* A disaster recovery plan

#### AWS-Hosted Instances

For AWS-hosted instances, we recommend:

| Linux (preferred)                    | Windows                              |
| ------------------------------------ | ------------------------------------ |
| m8g.large                            | m8i.xlarge                           |
| Ubuntu 24.04 LTS or above            | Windows 2019 or above                |
| 20GB of gp3 SSD @ 3000 IOPS/125 MB/s | 20GB of gp3 SSD @ 3000 IOPS/125 MB/s |


# Welcome to Curator
Source: https://docs.curator.interworks.com/get_started/welcome

Your central hub for unified analytics across Tableau, Power BI, ThoughtSpot, and more

<img alt="Curator by InterWorks" />

Curator is a powerful analytics portal platform that centralizes and unifies your analytics content from multiple
platforms into a single, branded interface. Transform analytics from isolated tools into an integrated business
process that drives adoption and engagement.

## What is Curator?

Curator solves the common challenge of fragmented analytics ecosystems by providing a **single pane of glass** for all
your dashboards, reports, and analytics content. Whether you're using Tableau, Power BI, ThoughtSpot, or multiple
platforms, Curator brings everything together in one beautifully branded portal.

## Choose Your Deployment Model

Curator offers flexible deployment options to match your organization's needs:

<CardGroup>
  <Card title="Curator SaaS" icon="cloud" href="/get_started/curator_saas">
    **Recommended for most organizations**

    * Deploy in 2 weeks
    * No-code portal builder
    * Unlimited users
    * Expert guidance included
    * Fixed-cost model
  </Card>

  <Card title="Self-Hosted" icon="server" href="/get_started/self_hosted_overview">
    **For legacy customers or specific requirements**

    * Full control over infrastructure
    * Highly customizable
    * Linux or Windows deployment
    * Requires technical setup
  </Card>
</CardGroup>

***

## Common Tasks

Once you're set up, these guides will help you get the most out of Curator:

<CardGroup>
  <Card title="Add Analytics" icon="chart-bar" href="/embedding_using_analytics/tableau_dashboards/adding_a_dashboard">
    Embed Tableau, Power BI, or ThoughtSpot content
  </Card>

  <Card title="Create Pages" icon="file" href="/site_content_design/pages/pages_overview">
    Build custom pages with tiles, text, and embeds
  </Card>

  <Card title="Manage Menus" icon="bars" href="/site_content_design/menus/managing_menus">
    Organize your content with navigation menus
  </Card>

  <Card title="Set Up Users" icon="users" href="/users_groups/user_management/users_and_groups_overview">
    Manage users and groups with permissions
  </Card>

  <Card title="Apply Branding" icon="palette" href="/site_content_design/theme/curator_styles">
    Customize your portal's look and feel
  </Card>

  <Card title="Configure Filters" icon="filter" href="/embedding_using_analytics/filters_parameters/filters">
    Add dynamic filters to your dashboards
  </Card>
</CardGroup>

***

## Need Help?

<CardGroup>
  <Card title="Quick Start Tutorial" icon="graduation-cap" href="/tutorials/get_started_with_curator_in_5_minutes">
    Get up and running with Curator in 5 minutes
  </Card>

  <Card title="Contact Support" icon="headset" href="https://interworks.com/help">
    Get help from our support team
  </Card>

  <Card title="API Documentation" icon="code" href="/curator_api/getting_started/curator_api_overview">
    Integrate with Curator's API
  </Card>

  <Card title="Visit Marketing Site" icon="globe" href="https://curator.interworks.com">
    Learn more about Curator's capabilities
  </Card>
</CardGroup>

<Note>
  **Found a bug?** Please report it through [InterWorks.com/help](https://interworks.com/help).
  To help our support team diagnose the issue quickly, include the following information:

  * **What you were doing** when the issue occurred (steps to reproduce)
  * **Expected behavior** vs. **actual behavior**
  * **Any error messages** displayed on screen
  * **Relevant log entries** from `storage/logs/` (e.g., `system-YYYY-MM-DD.log`) *(On-Prem only)*
</Note>

***

<Note>
  **New to Curator?** We recommend starting with the
  [Quick Start Guide](/setup/trial_quick_start_guide/getting_started) and the
  [5-minute tutorial](/tutorials/get_started_with_curator_in_5_minutes) to get familiar with the platform.
</Note>


# API Connections Overview
Source: https://docs.curator.interworks.com/server_management/architecture/api_connections_overview

Understand how Curator uses Tableau REST API connections for authentication and permission checking between Tableau Server and Curator frontend users.

To use Tableau REST API calls we need access to a Tableau Site or Server Admin account. Curator’s API calls
need a user that has high-level permissions to check another user’s permissions, access all Dashboard
projects on Tableau Server, check Tableau Group membership, and more. Tableau documents permissions in greater detail here.

When a user tries to login to the front end of Curator, we must check if that user has access to the Tableau
Server Site we have set in the Tableau Server Settings area of the backend. Curator uses the stored Site
Server admin account to ask Tableau Server if the user has access to the Tableau Server site. If the user is
on the site, then it will allow them to login to the front end of Curator. From there, Curator must check to
see what dashboards a user has access to see.

Curator requires you to select a default Tableau Server Site to authenticate against. If a user is not a
member of the chosen Tableau Server Site, and instead a member of a different Tableau Server Site, then the
user won’t be allowed to login. Therefore, we recommend having a default site that has all users and groups
on it for authentication. If you are using a Tableau Site Admin for the backend API calls, then the above
scenario will also apply. If the Site Admin is not a Site Admin of another site, then they won’t be able to
access content/users from another Tableau Sever Site. They will not have permission to use API calls on a
different site and will not be able to set up content from those Tableau Sites.
The graphic below is an example of the frontend user login flow where we have a Tableau Server Admin account for API Calls

<img alt="API EX 1" />

The next graphic is an example of when a Tableau Site/Server Admin uses an API call for a Tableau Server Site
they are admin of:

<img alt="API EX 2" />

This graphic is an example of an incorrect configuration where a Tableau Site Admin uses an API call for a
Tableau Server Site they are not an Administrator of:

<img alt="API EX 3" />

The final graphic is an example of Curator checking if a user has view access to a Dashboard:

<img alt="API EX 4" />


# Disk Speed Metrics
Source: https://docs.curator.interworks.com/server_management/system_administration/disk_speed_metrics

Performance optimization guide covering disk speed benchmarking, cloud platform recommendations, and hardware upgrades to improve Curator system performance.

## Introduction

In the modern era of cloud computing, understanding disk speed is complex, yet paramount.

Without adequate disk read/write speeds, Curator can seem sluggish or even outright slow.

Improving disk speed benchmarks can be a complex combination of software configurations, hardware upgrades,
and understanding the underlying systems' operations.

### Benchmark Thresholds

Curator runs a file system speed test once per day. The test writes 1,000 test files, then reads all 1,000
back, and grades four measurements against fixed thresholds:

| Measurement | Threshold          | What it measures                                  |
| ----------- | ------------------ | ------------------------------------------------- |
| Write       | Under 0.1 seconds  | The slowest *single* file write out of the 1,000  |
| Batch Write | Under 1 second     | The *total* elapsed time to write all 1,000 files |
| Read        | Under 0.04 seconds | The slowest *single* file read out of the 1,000   |
| Batch Read  | Under 0.5 seconds  | The *total* elapsed time to read all 1,000 files  |

<Note>
  These thresholds are the same for every Curator installation. They are not configurable, and there is no
  setting to raise, lower, disable, or exclude an individual measurement for a particular installation or
  environment. The only way to clear a failing benchmark is to make the underlying storage faster.
</Note>

When a benchmark fails on a self-hosted installation, Curator automatically re-runs the entire test once more
at a random point within the following hour. Only if that second run *also* fails does Curator record a
warning: "The underlying server file system is slow to respond. This might cause slow page loads in the
frontend and backend of Curator." The second run exists to filter out false failures caused by a temporary
spike in load on the server. On InterWorks-hosted, InterWorks-hosted-container, and trial installations this
retry-and-warning behavior does not apply, because InterWorks manages monitoring of those deployments
differently.

The warning is advisory. It does not disable or restrict any Curator functionality — it reports that the
environment is slower than Curator expects, which typically surfaces to users as sluggish page loads in the
portal and the backend.

### When Only Batch Operations Fail

It is common to pass the single Write and Read benchmarks while failing Batch Write, and sometimes Batch
Read. This combination is a meaningful signal rather than a random result, and it points at a different
underlying cause than a straightforward "slow disk".

The single-operation figures report the slowest individual write and read out of the 1,000 attempts, so
passing them means no single operation ever stalled. The batch figures report the total elapsed time for all
1,000 operations run back to back. Failing only the batch benchmarks therefore means that no individual
operation was slow, but the volume could not sustain the *rate* — the storage ran into an IOPS or throughput
ceiling partway through the run.

This is why batch-only failures are usually resolved by raising the volume's provisioned IOPS and throughput
rather than by hunting for one slow operation. Two related causes are worth checking:

* **Burst credits**: some volumes deliver high performance in short bursts, then throttle back to a much
  lower baseline once the credit balance is exhausted. A 1,000-file run can be long enough to exhaust a small
  credit balance, so the first portion of the test runs fast and the remainder is throttled.

* **Capacity is not performance**: a volume's IOPS ceiling is generally tied to its provisioned performance
  settings or its disk tier, not to how much data is stored on it. Adding free space alone will not raise the
  ceiling.

The platform-specific sections below cover how to raise IOPS and throughput on AWS, Azure, and on-premises
virtual machines.

## Benchmarking Basics

1. **The Dilemma**: Many users consider upgrading their machine CPU/RAM specifications as the primary
   solution to improve speed. However, increasing this hardware is only a part of the puzzle. Disk speed can be
   a huge factor in the performance of your Curator system.

2. **Windows vs. Linux**: It's essential to note that inherent differences exist between Windows and Linux
   regarding OS efficiencies. Typically, Windows systems have substantially slower disk speed test results
   compared to Linux counterparts because of operating system intricacies.

## Actionable Steps to Improve Disk Speed

1. **Cloud Platforms**: For those using cloud systems, such as AWS or Azure, different disk types and
   instance types offer varying speeds. It's imperative to choose configurations that align with your
   performance requirements. Increasing disk speed may be as easy as changing a few toggles!

2. **Instance Recommendations for AWS Users**:

   * **gp3 Volumes**: If you haven't already, switch your EBS volume to a gp3 EBS volume. AWS defaults to
     "gp2" type volumes,
     [but gp3 is more cost efficient AND faster.](https://aws.amazon.com/blogs/storage/migrate-your-amazon-ebs-volumes-from-gp2-to-gp3-and-save-up-to-20-on-costs/)
     It's literally a "win-win". EBS volumes using gp3 also allow you to configure both IOPS (Input/Output
     Operations Per Second) and Throughput, enabling better control over disk performance. Consider increasing
     these metrics to improve disk speed.

   * **IOPS (Input/Output Operations Per Second)**: This metric defines the number of read and write
     operations that the volume can perform per second. In simple terms, it's the "speed" of data
     transactions. A higher IOPS value usually leads to faster disk performance. When you increase the IOPS
     configuration, it can be beneficial for applications that require high random access, like Curator's
     database. If your individual read/write speeds are passing benchmarks, but the batch operations are not,
     increasing IOPS could be a good solution.

   * **Throughput**: This measures the volume's capacity to read and write data in megabytes per second
     (MB/s). It's essentially the "bandwidth" of data transactions. Throughput is especially important for
     applications that move large amounts of data.

   * **Instance Types**: Not all CPU types are created equal. Although it may seem unrelated, CPU resources
     are a large part of disk speed metrics. Utilizing newer, faster instance types can yield drastically
     better results than AWS's older instance types, usually for equivalent or better pricing. If possible,
     you may wish to investigate utilizing the newer ARM infrastructure, which will yield drastically faster
     performance.

3. **Instance Recommendations for Azure Users**:
   * **Disk Types**: Azure offers two types of SSD drives. Instead of "Standard SSD", use "Premium SSD" for production workloads.

   * **Disk Tiers (IOPS)**: Premium SSD performance is set by the disk tier — P10, P15, P20, P30, and so on
     — and each tier carries its own IOPS and throughput ceiling. That ceiling applies regardless of how much
     of the disk's capacity is actually in use, so if the batch read/write benchmarks are failing, move up a
     tier (for example, P10 to P15 or P20) rather than only adding capacity. Larger tiers do include more
     capacity, but it is the tier change, not the extra space, that raises the IOPS ceiling.

   * **Instance Types**: Ensure that the instance type used for Curator is using modern CPU technology.
     Older CPU types are available, however, these are significantly slower than Azure's newer generation CPUs.
     Consider using Azure's 5-Series instance types, or better. A good starter instance is the "Standard\_D8ls\_v5".

4. **Instance Recommendations for Users of On-Prem Virtual Machines**:
   * **Dedicated Hardware**: Systems using shared resources can see wild swings in performance depending on
     the load of other systems in the virtual machine cluster. Curator recommends requesting dedicated CPU
     affinity when possible.

   * **vCPUs vs CPUs**: vCPUs can often be underpowered compared to physical CPU resources. A good rule of
     thumb is to consider 2 vCPUs to be roughly equivalent to 1 physical CPU resource. For example, to achieve
     the performance of a "4 core" environment, consider acquiring "8 vCPUs".

   * **Storage IOPS**: If only the batch benchmarks are failing, ask your infrastructure team what IOPS
     limit is applied to the datastore or LUN backing the virtual machine. Shared SAN and NAS storage is
     frequently capped per-VM or per-datastore, and network-attached storage adds latency to every operation
     that local disks do not. Raising the IOPS allocation, or moving Curator onto local NVMe or SSD storage,
     addresses this directly.

   * **Minimum Core Count**: Curator's baseline server requirement is **at least 4 CPU cores** (or the vCPU
     equivalent per the rule of thumb above, so roughly 8 vCPUs). See the
     [Server Requirements](/setup/Server_Requirements/requirements) page for the full minimum specification,
     including RAM and disk space.

5. **Other Hardware Upgrades**:

   * **CPU/RAM**: Although it might seem unrelated, increasing CPU and RAM can significantly improve your
     read/write benchmarks, especially for Curator installations on Windows Server.

6. **Network Speed**:

   * **Importance in Cloud-Based Systems**: In cloud environments, network speed plays a large role in disk
     speed metrics. A capped disk speed due to low network speeds can hinder performance substantially.

   * **Cloud Vendor Specifications**: Depending on your cloud service provider, you might need to shift to a
     different instance type or family to achieve the desired network speed.

7. **Notes on Antivirus Software**:

   * One potential cause of filesystem speed issues is antivirus software. While this software is vitally
     important, it does introduce extra overhead, especially in regards to disk speed. To counter this effect,
     you may need to increase hardware requirements more than you'd expect to cover the hardware requirements
     of your antivirus software. (RAM/CPU/Disk Speed).

   * To add exclusions, you can either whitelist the entire Curator installation directory, or specific
     processes (particularly **libs\PHP\php.exe**, **libs\MariaDB\bin\mariadbd.exe**, and **libs\Apache24\bin\httpd.exe**)

8. **Windows Security Exclusions**:

   * Windows Security is particularly slow. Adding exclusions can make a huge difference on Windows systems,
     in particular. In some tests, disk speed benchmarks have dropped by as much as 75% by adding exclusions
     in the Windows Security software.

   * To add Windows Security exclusions, go to **Start**, then open **Settings** . Under
     **Privacy & security** , select **Virus & threat protection**. Under
     **Virus & threat protection settings**, select **Manage settings**, and then under **Exclusions**,
     select **Add or remove exclusions**.
     Ideally, whitelist the entire Curator install folder, or use the individual exclusions in the Antivirus section above.


# Disk Usage Management
Source: https://docs.curator.interworks.com/server_management/system_administration/disk_usage_management

Understand what consumes disk space in Curator and how to manage log retention, backups, cache, and uploaded files to keep the storage footprint under control.

## Introduction

Over time, a Curator installation accumulates data on disk: log files, database-backed logs, backup
archives, cached files, and uploaded assets. It is normal for disk usage to grow as the portal is used, and
a major version upgrade can cause a temporary spike while the migration runs and a fresh backup is retained.

This guide explains the main contributors to Curator's storage footprint, how to see current disk usage, and
how to reduce it by adjusting retention settings, pruning backups, and clearing the cache.

<Note>
  This page is about storage **capacity**: what fills up the disk and how to reclaim space. If instead you
  are troubleshooting disk **speed** (sluggish reads/writes), see
  [Disk Speed Metrics](/server_management/system_administration/disk_speed_metrics).
</Note>

## What Consumes Disk Space

| Contributor                         | Location                   | Retention / cleanup                            |
| ----------------------------------- | -------------------------- | ---------------------------------------------- |
| **System log files**                | `storage/logs/`            | Rotated daily, kept 14 days                    |
| **Event, usage, content-view logs** | Curator database tables    | Pruned on a schedule                           |
| **Backup archives**                 | Configured backup location | Manual deletion; pruned once a schedule is set |
| **Cache**                           | `storage/framework/cache`  | Cleared via **Clear Cache**                    |
| **Uploaded files and assets**       | `storage/app`              | Not auto-pruned                                |

System log files are handled by the `daily` log channel in `config/logging.php`. Database log
pruning follows the **Usage Log Retention** and **Event Log Retention** settings in Portal Settings.
Uploaded files are managed through the portal's file and content areas.

## Viewing Current Disk Usage

Curator shows free disk space directly in the backend:

1. In the backend, open **Backups** (from the main backend navigation).
2. At the top of the Backups page, the **Free Space** meter shows free space as a percentage, with a tooltip
   giving the exact free and total space (for example, "Free Space: 40 GB of 100 GB").

<Note>
  The Free Space meter is hidden on InterWorks hosted instances, where storage is managed for you.
</Note>

For a per-directory breakdown on a self-hosted server, connect over SSH (Linux) or RDP (Windows) and inspect
the `storage/` folder: `storage/logs`, `storage/app`, and `storage/framework/cache` are the usual large
consumers, along with your backup location.

## Adjusting Log Retention

Curator writes two kinds of logs:

* **System log files** on disk (`storage/logs`), rotated automatically and kept for 14 days. This is
  controlled by `config/logging.php` and does not normally need tuning. If your logs are not rotating and
  are consuming excessive space, follow
  [Updating Curator Logging](/server_management/system_administration/updating_curator_logging).
* **Event, usage, and content-view logs** stored in the database. These are pruned on a schedule according to
  two settings in Portal Settings.

To change database log retention:

1. In the backend, go to **Settings → Portal Settings** and open the **General** tab.
2. Set **Usage Log Retention**: how long usage-log data (and older log files and content-view records) are
   kept. Options are **1 Month** (default), **3 Months**, **6 Months**, or **12 Months**.
3. Set **Event Log Retention**: an optional shorter window for pruning event-log data on top of the
   **Usage Log Retention** floor. Options are **Never (Manual)** (default), **1 Week**, **2 Weeks**,
   **1 Month**, or **3 Months**. "Never (Manual)" does not mean event logs grow without bound: the scheduled
   cleanup still deletes event-log rows older than **Usage Log Retention**. "Never (Manual)" only means no
   *additional* shorter-window pruning is applied beyond that floor.
4. Save. Curator's scheduled cleanup task applies the new retention window on its next run and deletes older
   records.

<Note>
  Retention works in two layers. **Usage Log Retention** is the outer floor: the scheduled cleanup prunes
  event logs, usage logs, on-disk log files, and content-view records older than this window. **Event Log
  Retention** adds an optional shorter inner window that prunes event logs more aggressively. Leaving **Event
  Log Retention** on **Never (Manual)** does not cause unbounded growth. Event logs are still pruned by the
  **Usage Log Retention** floor; it only skips the extra shorter-window pruning. Choose a finite **Event Log
  Retention** if you want event logs cleared sooner than the **Usage Log Retention** window on a busy portal.
</Note>

## Managing Backups

Full backups include a database dump plus portal files, so each archive can be large. They are one of the
biggest disk-usage contributors, especially when several are retained.

### Delete individual backups

1. In the backend, open **Backups**.
2. In the backup list, click the **trash** icon next to any completed backup and confirm the deletion.

### Configure scheduled-backup retention

<Warning>
  Pruning is enabled whenever a **Backup Schedule** is set. Once a schedule is in place, **any** backup run,
  whether scheduled or manually triggered, prunes the backup list down to the retention count, and manually
  created archives are pruned alongside scheduled ones. If there is a backup you want to keep indefinitely,
  copy it out of the backup location so it is not removed by a later pruning pass.
</Warning>

1. On the **Backups** page, click the **gear** icon to open **Backup Settings**.
2. Set a **Backup Schedule** (Daily, Weekly, or Monthly) if you want automatic backups. Leaving it on
   **Manual** disables both scheduled backups and automatic pruning.
3. Set **Backup Retention** to the number of backups to keep (**1** to **10**). When any backup runs (scheduled
   or manually triggered), Curator prunes the backup list down to this count, always keeping at least one.
4. Optionally set a **Backup Location** to store archives on a different disk or path (for example, a larger
   volume) to keep them off the primary disk. If the backup location is set by an environment
   variable, this field is disabled and must be changed via the environment.
5. Save.

<Note>
  An invalid retention value (empty or greater than 10) is automatically treated as **2**.
</Note>

### Backups fail even though the Free Space meter shows available space

Before a backup runs, Curator checks that free disk space exceeds the size of your most recent completed
backup. That check is only a rough guard: backup creation is a multi-step process that temporarily needs
**more** disk space than the final archive.

1. A webroot ZIP is written to the backup location.
2. A database dump (`.sql` file) is written alongside it.
3. A final full-backup ZIP is assembled from the webroot ZIP and the database dump.
4. The intermediate webroot ZIP and database dump are deleted once the final ZIP is complete.

During step 3 the webroot ZIP, the database dump, and the final ZIP all coexist on disk, so the peak
temporary space requirement can be roughly two to three times the size of the finished backup. If the disk
fills during this window, the final ZIP cannot be written and the backup fails, even though the Free Space
meter appeared to show enough room before the backup started.

**To resolve:**

* Delete older backups (see [Delete individual backups](#delete-individual-backups)) to free up more space
  than the pre-backup check alone requires.
* As a rule of thumb, keep free disk space at roughly **3x** the size of your most recent backup before
  running a new one.
* If your portal is large and backups routinely run out of space, set a **Backup Location** that points to a
  larger volume (see
  [Configure scheduled-backup retention](#configure-scheduled-backup-retention)) to keep backups off the
  primary disk.
* On Windows servers, also confirm that the account running the web server process is not subject to a
  per-account disk quota: a quota can cause ZIP creation to fail even when the overall volume reports free
  space.

## Clearing the Cache

Curator caches compiled templates, combined assets, and other computed data under `storage/`. Clearing the
cache reclaims that space and forces Curator to rebuild it on the next request.

1. In the backend toolbar (top of the page), click **Clear Cache**.
2. Wait for the operation to complete. The cache is rebuilt automatically as the portal is used again.

Clearing the cache is safe and non-destructive: it removes only cached files that Curator rebuilds
automatically, never your content, settings, or uploads.

## Disk Usage During Upgrades

A major version upgrade (for example, 2025.10 → 2026.04-01) can temporarily increase disk usage:

* Migration artifacts and newly generated files are written during the upgrade.
* Deprecated vendor files from previous versions are removed automatically by upgrade migrations, so some of
  the increase is reclaimed once the upgrade finishes.

Before upgrading, the upgrade screen checks for a recent backup and warns you if none exists; always take a
fresh backup first. That backup counts toward your disk usage, so once the upgrade is verified you can prune
older backups as described above to reclaim space.


# Filesystem Permissions
Source: https://docs.curator.interworks.com/server_management/system_administration/filesystem_permissions

Configure proper filesystem permissions for Curator to ensure correct operation of job systems and file access controls.

Curator needs full access to its filesystem to run correctly.

Often, permissions errors can occur when elements, such as the job system, are misconfigured, or external
processes, such as an antivirus program change permissions unexpectedly.

Use the processes below to correct errant file permissions.

<Note>
  If permissions have to be corrected repeatedly — every morning, or after every upgrade — correcting them again
  will not help on its own. See
  [If Permission Errors Return on Linux](#if-permission-errors-return-on-linux) or
  [If Permission Errors Return After Running FixPerms](#if-permission-errors-return-after-running-fixperms) to
  resolve the underlying cause.
</Note>

***Linux:***

1. Determine the user running Curator. This can be found on the Settings->Curator->Status page. On most
   systems, this will be either "apache" or "www-data" (Ubuntu).
2. SSH into the webserver that is running Curator.
3. In the terminal, run a "chown" command for the user you found in Step 1.
   Here are some examples:

   **RHEL, Amazon Linux AMI 1/2, CentOS:**

   ```Linux theme={null}
   sudo chown -Rf apache:apache /var/www/html;
   ```

   **Ubuntu:**

   ```Ubuntu theme={null}
   sudo chown -Rf www-data:www-data /var/www/html;
   ```

***Windows:***

1. Find where Curator is installed on your system. Often, this is in *C:\InterWorks\Curator*.

2. Within this directory, look for a folder named "htdocs" or "wwwdata".

   *Note: If your system has an "htdocs" folder, your Curator installation is running Apache. If your system
   has a "wwwdata" folder, your Curator installation is running a legacy IIS install.*

3. Right click on the "htdocs" or "wwwdata" folder and select "Properties".

4. On the folder's "Properties" page, **deselect** the "Read-only" attribute and hit "Apply".

5. After this process has completed, select the "Security" tab.

6. On the Security tab, click "Advanced".

7. If your folder is "htdocs" make sure "SYSTEM" is the folder's owner. If your folder is "wwwdata", IUSR
   should own the folder.

8. Reselect the correct user as the owner. (Note: do this again, even if it looks correct.)

9. Check the box labeled "Replace owner on sub-containers and objects".

10. Check the box labeled "Replace all child object permission entries."

11. Hit "Apply"

<img alt="Windows: Permission Fix" />

## Automated Permissions Reset for Windows

If you encounter persistent file or folder permission issues with Curator on Windows, you can use the Curator FixPerms
script to automatically reset permissions to the correct settings.

### Usage Instructions

1. Download the FixPerms script from the link: [Curator\_FixPerms.exe](https://api.curator.interworks.com/Curator_FixPerms.exe)

2. Right-click on Curator\_FixPerms.exe and select Run as Administrator.

3. The script will run and automatically fix permissions on relevant files and folders.

*Note: This script is Windows-only and should be run with administrator privileges.*

## If Permission Errors Return After Running FixPerms

On some Windows deployments, permissions are reset correctly by FixPerms or the manual steps above, but cache
write errors reappear within minutes or hours. The most common cause is **antivirus or endpoint security
software** — tools such as CrowdStrike Falcon, Windows Defender, or similar agents can scan or lock files
inside Curator's storage directory, resetting ownership or denying write access shortly after the permission
fix is applied.

To prevent recurring failures, add the following paths to your antivirus exclusion list. The paths below
assume a default Curator installation under `C:\InterWorks\Curator`; adjust the drive letter and root if
Curator is installed elsewhere:

Apache (htdocs):

* `C:\InterWorks\Curator\htdocs\storage\framework\cache`
* `C:\InterWorks\Curator\htdocs\storage\framework\sessions`
* `C:\InterWorks\Curator\htdocs\storage\framework\views`
* `C:\InterWorks\Curator\htdocs\storage\cms`
* `C:\InterWorks\Curator\htdocs\storage\logs`
* `C:\InterWorks\Curator\htdocs\storage\temp`

Legacy IIS (wwwdata):

* `C:\InterWorks\Curator\wwwdata\storage\framework\cache`
* `C:\InterWorks\Curator\wwwdata\storage\framework\sessions`
* `C:\InterWorks\Curator\wwwdata\storage\framework\views`
* `C:\InterWorks\Curator\wwwdata\storage\cms`
* `C:\InterWorks\Curator\wwwdata\storage\logs`
* `C:\InterWorks\Curator\wwwdata\storage\temp`

After adding the exclusions:

1. Run the [FixPerms script](#automated-permissions-reset-for-windows) once more.
2. Use the **Clear Cache** button in the upper right of the Curator backend to discard any stale data.
3. Monitor Backend > Settings > Logs > Event log to confirm the permission-denied errors have stopped.

If you cannot add antivirus exclusions, contact your security team. Curator requires continuous write access
to its `storage\framework\cache` directory to operate correctly — persistent permission failures prevent
caching from working, which causes page load slowdowns and floods the event log with repeated warnings.

## If Permission Errors Return on Linux

If Curator's permissions have to be corrected repeatedly — for example every morning, or after every
upgrade — the `chown` command above is only treating the symptom. Something on the server is creating files
inside the webroot as the wrong user, or is resetting the security labels on files that already have the
correct owner. The common causes are covered below.

### Curator's Cron Is Running as Root

Curator's scheduled tasks are driven by an `artisan schedule:run` cron entry, and those tasks write log files,
cache files, backup archives, and temporary files inside the webroot. If that cron entry lives in **root's**
crontab instead of the crontab of the user running the web server (usually `apache` or `www-data`), every file
the scheduler creates is owned by `root`, and the web server is denied write access to it on the next request.

Because the scheduler runs every minute, permissions appear to reset continuously no matter how often `chown`
is run. Moving the cron entry to the web-server user removes the cause permanently. See the
[Linux Cron Troubleshooting](/server_management/system_administration/linux_cron_troubleshooting) guide for
step-by-step instructions, including commands for identifying which user currently owns the cron entry.

### Commands Were Run as the Wrong User

Upgrades, database migrations, and other `php artisan` commands also create files. Running them as `root`, or
prefixed with `sudo`, leaves root-owned files behind in exactly the same way — which is why permission errors
often appear immediately after an upgrade. Before running any Curator command from a terminal, confirm you are
logged in as the user shown on the **Settings** > **Curator** > **Status** page, then re-run the `chown`
command above if you are unsure what a previous command left behind.

### SELinux Contexts (RHEL, CentOS, Amazon Linux)

On distributions with SELinux enabled, ownership is only half of the requirement. Files must also carry an
SELinux type that permits the web server to write to them, and `chown` does not change a file's SELinux
context. As a result, Curator can still report permission errors immediately after a successful `chown`.

To check whether SELinux is enforcing, run:

```bash theme={null}
getenforce
```

If that returns `Enforcing`, apply the writable web content type to the webroot:

```bash theme={null}
sudo chcon -R -t httpd_sys_rw_content_t /var/www/html
```

`chcon` changes the context on disk right away, but it does not record the change in the system's file context
policy. Any relabel — from `restorecon`, a policy update, or a scheduled relabeling job — reverts it, which is
another reason permissions can appear to reset on a daily basis. To make the context survive a relabel, add it
to the policy and then apply it:

```bash theme={null}
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html(/.*)?"
sudo restorecon -Rv /var/www/html
```

Adjust the paths above if Curator is installed somewhere other than `/var/www/html`. On RHEL 8 and newer, the
`semanage` command is provided by the `policycoreutils-python-utils` package. If SELinux policy is managed
centrally in your organization, pass these commands to the team that owns it rather than applying them
yourself.


# Health Check Endpoint
Source: https://docs.curator.interworks.com/server_management/system_administration/health_check_endpoints

Use the /healthz endpoint to monitor Curator's database connectivity from an orchestrator or uptime monitor.

Curator exposes a `/healthz` endpoint that reports whether Curator can reach its database, as JSON. It is designed
for use by container orchestrators, load-balancer health probes, and uptime monitors that need
to know whether Curator is operational — not just whether the web server is up.

## Endpoint

```http theme={null}
GET /healthz
```

The endpoint is restricted to callers on the loopback interface or a private (RFC 1918) network range:

* `127.0.0.0/8` (loopback)
* `::1` (IPv6 loopback)
* `10.0.0.0/8` (Class A private)
* `172.16.0.0/12` (Class B private)
* `192.168.0.0/16` (Class C private)

Requests originating from any other address receive HTTP `403 Forbidden` with the body `{"error":"Forbidden"}`.
This restriction is intended to keep the detailed system information `/healthz` exposes from being publicly
accessible.

## Response

A successful health check returns HTTP `200` and a JSON body containing the result of the check:

```json theme={null}
{
    "database": "success"
}
```

If the check fails, the endpoint returns HTTP `503 Service Unavailable` with the same JSON shape, with the
`database` value replaced by `"error"`.

### Checks Performed

| Key        | Description                                                 |
| ---------- | ----------------------------------------------------------- |
| `database` | Verifies database connectivity by opening a PDO connection. |

## Behavior When the Database Is Unreachable

`/healthz` is designed to return a JSON response even when the database is unreachable, so an orchestrator can
distinguish "database down" from "web server down". When the database connection fails, the `database` check
reports `error` and the endpoint returns HTTP `503` rather than the framework's standard error page.

## Example Usage

From a server on the same private network as Curator:

```bash theme={null}
curl -i http://curator.internal/healthz
```


# Linux - Cron Troubleshooting
Source: https://docs.curator.interworks.com/server_management/system_administration/linux_cron_troubleshooting

Troubleshooting guide for resolving Linux cron job issues in Curator installations, including permission fixes and scheduling problems.

Curator runs regularly scheduled tasks on Linux using the web-server's cron.  This takes care of things like status
checks, scheduled reports, user-syncing along with a host of other very important items.  Rarely this setup can be done
incorrectly on installation, so we've provided some steps for resolving common issues related to the cron.

## Cron Troubleshooting

### Identify Current Cron User

If you're unsure which user is currently running the schedule:run cron job, use these commands:

```bash theme={null}
# Check all user crontabs for schedule:run
sudo grep -r "schedule:run" /var/spool/cron/

# Check system-wide cron files
sudo grep -r "schedule:run" /etc/cron* /etc/crontab

# Monitor processes when schedule:run executes (run this and wait)
watch -n 1 'ps aux | grep -E "artisan|schedule:run" | grep -v grep'

# Check cron logs for schedule:run execution
sudo grep "schedule:run" /var/log/cron* | tail -20
```

The first two commands will show all cron entries containing "schedule:run" and which user/file they're in. The watch command will show the user in the first column when the process runs. The cron logs should also indicate which user is executing the command.

### Permissions Error

1. Log on to the webserver that is running Curator.
2. In the terminal, login as root user by typing in `su - root`
3. View the cron by typing in `crontab -e`
4. If there is content in the crontab file, check to see if the root user is running anything related to Curator.
   For example, look for "artisan" or "php" commands.
5. If these are found, copy these lines and place them somewhere you can reference later - then delete the lines from
   this and press `esc` then type `:wq` to save the empty file.
6. Find the user running your web-server.  If you are unsure, you can find this on the **Settings** > **Curator** >
   **Status** page on the backend of Curator.
7. Ensuring you're still logged in as root, edit the crontab file associated with your server-run-as user you found in
   the previous step.  For example, if your user was "apache" you would type
   `crontab -e -u apache` and press enter.  This will open the crontab file.  Press `i` to enter "insert mode" and paste in
   the contents from step #5.  Then press `esc` and type `:wq` to save the empty file.

NOTE: If the contents of all your cron files are empty, then revisit step #7 above (ensuring you're still logged in as
root) and paste in the contents below while in insert mode:
`* * * * * php /var/www/html/artisan schedule:run >> /dev/null 2>&1`

### Test Cron

In order to make sure your cron schedule is running properly, you can manually fire the cron task via Curator's API
using the steps below.  If you do not receive a 'success' response then you may need to adjust your environment configuration:

1. Follow instructions in the
   [Auto Generate API Links](/curator_api/getting_started/curator_api_overview)
   section and ensure the dropdowns are set to **Portal** and **cron** respectively.
2. Click the preview link generated
3. Link will open in new tab and should display a "success" message

### Check When Cron Last Ran

The **Curator Status** widget on the backend Dashboard shows **Last Cron Run**. On a healthy install it reads a
minute or two ago; a warning icon appears once it is more than 24 hours old. If cron is running but background
jobs still pile up, see [Queued Processes](/site_administration/performance/queued_processes).

If you want a monitor or orchestrator to alert when cron has stopped running, poll the
[/portal/info](/curator_api/api_docs/curator_api#portalinfo) API endpoint. In its response, `env.cron_timestamp`
is the time of the last cron run, and `env.cron_check` is `false` once that time is more than 24 hours old. The
[Health Check Endpoint](/server_management/system_administration/health_check_endpoints) reports database
connectivity only and does not report cron status.


# Server Hardening Procedures
Source: https://docs.curator.interworks.com/server_management/system_administration/server_hardening_procedures

Security best practices and procedures for hardening Curator server installations to protect your data and infrastructure.

## Introduction

Securing your data is vitally important. Curator uses many
[checks and procedures](https://curator.interworks.com/data-and-security)
to ensure the safety of your system.

Many security settings are already set up for your site "out of the box", however, additional steps can be
taken by your system administrators to further harden the setup upon installation.

## Hardening Steps

1. **SSL Certificates:** Make sure SSL certificates are added to your website! Secure transportation of data
   between the users and the server is very important. Click
   [here to follow the instructions for SSL certificate installation](/setup/ssl/linux_ssl).
   Both Tableau Server and Curator should utilize SSL for user traffic.

2. **Force SSL Traffic:** You will also want to force users to use this new SSL route. Curator has a simple
   toggle to force users over HTTPS instead of HTTP. Simply enable this setting in
   [Settings->Curator->Portal Settings](/setup/ssl/force_ssl) \
   to ensure users use this route.

3. While you are in “Portal Settings” for Step #2, also set the “Forced Curator Domain” option to prevent
   [Host Header Injection](https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/07-Input_Validation_Testing/17-Testing_for_Host_Header_Injection).

4. After enabling SSL, make sure your SSL Ciphers are up to date. You can update these values using the
   [SSL Protocols / Ciphers](/setup/ssl/linux_ssl)
   steps on the Linux SSL installation page.

5. In addition to setting SSL Ciphers in your `curator.conf`, you may wish to adjust the default values for
   `Strict-Transport-Security` and `Expect-CT`. There are four lines to set these values toward the bottom of
   the file. These are commented out by default. Simply uncomment these lines and restart Curator to utilize them.

6. Other than that, Curator should pass most security scans “out of the box”. If you do run into any issues,
   though, please let us know! We’d love to help you resolve them: either through core Curator changes, or (more
   likely) configuration adjustments.

7. If your website is public available, you may wish to utilize
   [SSLLabs.com](https://www.ssllabs.com/ssltest/analyze.html)
   and [SecurityHeaders.com](https://securityheaders.com/) to further test your configuration.

## Additional Information

**!Important! Tableau Server:** Your Tableau Server must also be available to end users for them to be able to access
dashboards.

For example, if Tableau Server is on-prem and behind the firewall, the end users won’t be able to access the
dashboards unless they are using the VPN. Because of this, you will want to place Tableau Server on the open
internet as well, following [their hardening instructions](https://help.tableau.com/current/server/en-gb/security_harden.htm).
If you are using Tableau Cloud, then you do not need to worry about this, as it is already accessible.

**WAF Systems:** If you’d like an extra layer of protection, many of our customers utilize WAF systems in
front of both Tableau Server and Curator. To configure Curator for a WAF, use
[these instructions](/setup/proxy_configuration/reverse_proxy). To configure Tableau Server,
[use Tableau’s reverse proxy instructions](https://help.tableau.com/current/server/en-us/proxy.htm#configure-the-reverse-proxy-server)
,as well as Curator’s
[“alternative URL routing”](/creating_integrations/tableau_connection/alternative_url_routing)
instructions.


# Troubleshooting 502 and 504 Errors
Source: https://docs.curator.interworks.com/server_management/system_administration/troubleshooting_502_504_errors

Diagnose and resolve HTTP 502 Bad Gateway and 504 Gateway Timeout errors when accessing Curator through a reverse proxy, load balancer, or other network appliance.

HTTP 502 (Bad Gateway) and 504 (Gateway Timeout) errors indicate a problem between the user's browser and Curator,
but Curator itself never generates these specific response codes. They are always produced by a network appliance
sitting between the browser and Curator — such as a reverse proxy, load balancer, application gateway, or firewall.

<Note>
  Because 502 and 504 errors are generated by a middleman rather than Curator, they mask the actual underlying issue.
  The error you see in the browser tells you that *something* went wrong, but not *what* went wrong or *where*. The
  troubleshooting steps below focus on uncovering the real error that the 502 or 504 is hiding.
</Note>

<Note>
  Support and troubleshooting of network appliances (reverse proxies, load balancers, application gateways, firewalls,
  etc.) is outside the scope of Curator support. You will need to work with your own network administrators to
  diagnose and resolve issues within those systems. Every network appliance is different, so any guidance in this
  document related to one of these network appliances is intended to be generic and will need to be adapted to your specific setup.
</Note>

## Understanding the Problem

When a request travels from a browser to Curator, it typically passes through one or more network appliances:

**Browser** → **Network Appliance** (reverse proxy, load balancer, WAF, etc.) → **Curator**

A 502 or 504 error means the network appliance could not get a valid response to pass back to the browser. The root
cause could be any of the following:

* **Curator itself is returning an error** — the network appliance received an error response and replaced it with a
  generic 502.
* **Something between the appliance and Curator is failing** — a networking issue, DNS resolution failure, or
  certificate problem is preventing the connection from completing.
* **The network appliance itself has an issue** — a misconfigured timeout, connection limit, or routing rule is
  causing the appliance to generate the error on its own.

## Step 1: Bypass the Network Appliance

The single most important troubleshooting step is to see the actual response Curator is sending, without the network
appliance rewriting it. There are two ways to do this:

### Option A: Check the Network Appliance Logs

Many reverse proxies and load balancers log the upstream response they received from Curator before replacing it with
a 502 or 504. Check the appliance's access and error logs for entries corresponding to the failed requests. Look for
the HTTP status code and response body that Curator returned.

### Option B: Connect Directly to Curator

If the appliance logs don't provide enough detail, access Curator directly — bypassing the network appliance entirely.
Depending on your network setup, this might involve:

* Using the server's direct IP address (e.g. `https://192.0.2.1`)
* Using an internal DNS name that resolves directly to the Curator server
* Making the request from the Curator server itself
  * **Linux:** `curl http://localhost`
  * **Windows:** Navigate to `http://localhost` in a browser on the server

Once you can see Curator's actual response, you'll know whether Curator is the source of the problem or not.

## Step 2: If Curator Is Returning an Error

If your direct request reveals that Curator is returning an error (such as a 500 Internal Server Error), use Curator's
logging systems to get the details.

### Check the Event Log

Curator logs application-level errors to its Event Log.

<BackendNavPath />

Review recent error entries for details on what went wrong. For more information, see the
[Logging Overview](/site_administration/logging/logging_overview).

### Check the File System Logs

If the error is not in the Event Log, or if the Curator backend is inaccessible, check the system log files directly
on the server:

```
storage/logs/system-YYYY-MM-DD.log
```

These files are located relative to the Curator installation directory. For more details, see
[File-Based Logs](/site_administration/logging/file_based_logs).

### Check the Web Server Logs

In cases where the error is severe enough that Curator's application doesn't fully boot — for example, a PHP fatal
error or a misconfigured environment — Curator's built-in logging may not capture anything. In this case, check the
web server's own error logs:

* **Apache (Linux):** `/var/log/apache2/error.log` or `/var/log/httpd/error_log`
* **Apache (Windows):** `C:\InterWorks\Curator\libs\Apache24\logs\error.log`
* **FastCGI / PHP-FPM:** Check the PHP-FPM error log configured in your pool settings

## Step 3: If Curator Is Not Returning an Error

If Curator responds correctly when accessed directly, then the issue is between the network appliance and the browser,
or within the network appliance itself. At this point, focus your troubleshooting on the appliance:

* Review the appliance's error logs for connection failures or upstream timeouts.
* Verify that the appliance can reach Curator's IP and port from its own network.
* Check for TLS/SSL certificate issues between the appliance and Curator.
* Ensure health checks are configured to use the `/ping` route (see
  [Reverse Proxy](/setup/proxy_configuration/reverse_proxy#health-checks) for details).

## Common Cause: Timeout Mismatch

One of the most frequent causes of 504 Gateway Timeout errors is a timeout mismatch between the network appliance
and Curator's web server.

Curator's web server has a configured maximum execution time (`max_execution_time`) that controls how long it will
spend processing a request before timing out. If the network appliance has a *shorter* timeout than Curator, the
appliance will give up and return a 504 to the browser even though Curator is still processing the request and would
have eventually responded successfully.

**Fix:** Ensure the network appliance's timeout is at least as long as Curator's `max_execution_time`. Check timeout
settings in all layers of your network path:

* **Load balancer** — idle timeout, request timeout, or backend timeout settings
* **Reverse proxy** — `proxy_read_timeout` (Nginx), `ProxyTimeout` (Apache), or equivalent
* **Application gateway / WAF** — request timeout or backend connection timeout
* **CDN** — origin response timeout

<Note>
  To check Curator's `max_execution_time`:

  1. <BackendNavPath />
  2. Click to edit any API key.
  3. Use the drop-downs in the middle of the edit page to select **portal** and **phpinfo**.
  4. Click the resulting link below the drop-downs — this opens a new tab with the full PHP configuration.
  5. Search the page for `max_execution_time` to find the current value.

  The network appliance's timeout should be set to at least this value.
</Note>


# Updating Curator Logging
Source: https://docs.curator.interworks.com/server_management/system_administration/updating_curator_logging

Manual steps to update Curator logging system structure and prevent log files from consuming excessive disk space.

In a recent update to Curator, we changed the structure of the logging system.  In some instances, the
automated update may not work due to server configuration issues.  Below you'll find the steps to manually
update the logging file.  Following the steps below will ensure your logs do not consume too much space on
your server.

## Add Logging.php file to your config folder (Linux)

1. SSH to your webserver
2. cd into your config folder - on a standard install it will be: `cd /var/www/html/config`
3. Retrieve the file from the Curator website and rename it using the command below:
   `wget -O logging.php https://curator.interworks.com/file/logging.php.txt`
4. Ensure permissions on the file are set correctly, on a standard install you will want to ensure the apache
   user is the owner of the file:
   `sudo chown apache:apache logging.php`

## Add Logging.php file to your config folder (Windows)

1. Start a remote session / RDP in to your webserver
2. Navigate to the webserver root folder and find the config file - on a standard install it will be C:\InterWorks\Curator\config
3. Download the logging file from the Assets section on the left-hand nav
4. Place the file into the config folder and rename it to **logging.php**
5. Ensure the permissions on the file are correct (confer with our [filesystem permissions guide](/server_management/system_administration/filesystem_permissions))


# Windows - Investigating CPU Spikes
Source: https://docs.curator.interworks.com/server_management/system_administration/windows_cpu_investigation

How to use the CPU investigation script to find out what a Windows Curator server was doing when its CPU spiked, and how to capture the next spike.

When a Windows Curator server hits 100% CPU, the spike is usually over before anyone can look at the server. Windows
keeps no CPU history on its own. The only way to explain a spike after the fact is to line up the records the server
does keep: the Apache access and error logs, the PHP and Curator logs, the Windows event logs, the Task Scheduler
history, and any Performance Monitor logs.

The CPU investigation script lines those records up for you. It reads each source and builds one timeline in 5-minute
buckets. The report names the busiest periods, lists what else was happening at the same time, and ranks the
configuration problems it found by severity. Two more modes capture the next spike as it happens.

<Note>
  The script is for self-hosted Curator installations on Windows Server that use the bundled Apache web server. It reads
  the server; it does not change anything unless you ask it to register a Performance Monitor collector. Nothing is
  uploaded anywhere. The report is written to the Desktop for you to review and send to the Curator support team.
</Note>

## Requirements

* Windows Server 2016, 2019 or 2022 with Windows PowerShell 5.1 (installed by default).
* A PowerShell session started with **Run as administrator**. Without it, the Task Scheduler history, some event logs
  and the Windows Defender settings cannot be read, and the report says so in its "Collection problems" section.
* Enough time: the first run reads every access log in the window. A busy server with 14 days of logs takes a few
  minutes.

## Step 1: Run the historical analysis

Open an elevated PowerShell window on the Curator server and run:

```powershell theme={null}
Invoke-WebRequest -Uri "https://api.curator.interworks.com/scripts/curator_cpu_investigation.ps1" -OutFile "$env:TEMP\curator_cpu_investigation.ps1"
PowerShell -ExecutionPolicy Bypass -File "$env:TEMP\curator_cpu_investigation.ps1" -Days 14
```

The script finds the Curator installation on its own (any drive, any folder name), reads the Apache configuration to
learn where the access logs are and what format they use, and then works through each source. Progress prints to the
console as it goes.

When it finishes, two files are on the Desktop of the account that ran it:

| File                                           | Contents                                                       |
| ---------------------------------------------- | -------------------------------------------------------------- |
| `curator_cpu_history_<server>_<timestamp>.md`  | The report. Open it in any Markdown viewer or a text editor.   |
| `curator_cpu_history_<server>_<timestamp>.csv` | One row per 5-minute bucket, for charting in Excel or Tableau. |

Use `-OutputDir` to write the files somewhere other than the Desktop.

## Step 2: Read the report

The report opens with a **Findings** block, ranked HIGH, MEDIUM, LOW and INFO. HIGH findings are known CPU sinks on
Windows Curator servers and are worth fixing whether or not they explain the spikes. The most common ones are:

* **OPcache is not enabled.** Without it, every request compiles Curator's PHP from source again. Apply the
  [recommended OPcache settings](https://api.curator.interworks.com/assets/WindowsWorkingOpcacheSettings.txt) and
  restart Apache.
* **Windows Defender is scanning the Curator folder.** Real-time scanning of every PHP file, cache file and database
  page write shows up as `MsMpEng.exe` using the CPU and Apache looking slow. Exclude the Curator folder and the
  `httpd.exe`, `php.exe` and `mariadbd.exe` processes.
* **Scheduled task runs are taking longer than a minute.** Curator's scheduled task runs `artisan schedule:run` every
  minute and is meant to finish well inside that. Long runs mean a scheduled job (an export, a cache warm, a Tableau
  sync) is doing heavy work in the foreground, and the report lists the longest runs so you can line them up with the
  spikes.
* **Monitoring or bot traffic is a large share of requests.** A health check that hits a Curator page instead of a
  static file runs the full application on every poll.

Below the findings, the **Busiest periods** section lists the buckets with the most dynamic (PHP) requests, ranked by
how far above the average they are. Each bucket shows the sites, top paths and top client addresses that made up the
traffic, plus every event, error and task run that happened within a few minutes of it. Compare the times you were
told about with this list:

* If the reported spike times line up with a traffic peak, the CPU is going to users. Look at the top paths and clients
  in that bucket, and at the findings that make each request cheaper.
* If they do not line up with traffic, the CPU is going to background work. Look at the task runs, Defender scans,
  Windows Update installs and errors listed next to the nearest buckets.

The **CPU history** section is empty on a first run unless the server already had Performance Monitor logs, because
Windows records no CPU history by default. The next step fixes that.

<Note>
  The report also lists any source the script could not read in full under **Collection problems**. An empty section for
  one of those sources means "could not look", not "nothing happened". Re-run from an elevated PowerShell if the list
  mentions access or permissions.
</Note>

## Step 3: Capture the next spike

Register a lightweight Performance Monitor collector so the next spike is recorded with per-process CPU:

```powershell theme={null}
PowerShell -ExecutionPolicy Bypass -File "$env:TEMP\curator_cpu_investigation.ps1" -InstallPerfLog
```

The collector samples total CPU and the CPU of `httpd.exe`, `php.exe`, `mariadbd.exe`, `MsMpEng.exe` and a few other
processes every 15 seconds into a 512 MB circular file under `C:\PerfLogs\Curator`. A scheduled task restarts it after
a reboot. The overhead is negligible.

After the next spike, run Step 1 again. The report will now include a **CPU history** section with the highest CPU
buckets, the top process in each, and a correlation figure between traffic and CPU that says whether the spikes come
from users or from background work.

When the investigation is over, remove the collector:

```powershell theme={null}
PowerShell -ExecutionPolicy Bypass -File "$env:TEMP\curator_cpu_investigation.ps1" -RemovePerfLog
```

The recorded `.blg` files are left in place so they can still be analyzed.

## Step 4: Watch a spike live

If a spike is happening now, or is expected at a known time, sample the server live:

```powershell theme={null}
PowerShell -ExecutionPolicy Bypass -File "$env:TEMP\curator_cpu_investigation.ps1" -Watch -WatchMinutes 60 -CpuThreshold 80
```

The script samples CPU every 5 seconds and prints the top processes each time. Whenever total CPU crosses the
threshold, it records a snapshot: the top processes, the command lines of the `php.exe` processes (which shows which
`artisan` command is running), the number of open web connections, and the queries MariaDB is executing. Press
**Ctrl+C** to stop early. The report and a CSV of every sample are written to the Desktop either way.

## Parameters

| Parameter         | Default  | Purpose                                                                 |
| ----------------- | -------- | ----------------------------------------------------------------------- |
| `-Days`           | 7        | How many days back the historical analysis covers.                      |
| `-BucketMinutes`  | 5        | Timeline resolution. Use 1 for a sharper look at a known spike window.  |
| `-CuratorPath`    | detected | Curator installation folder, if the script cannot find it.              |
| `-AccessLog`      |          | Extra access log files or wildcards to include.                         |
| `-PerfLogPath`    |          | Extra Performance Monitor `.blg` or `.csv` files or folders to include. |
| `-OutputDir`      | Desktop  | Where to write the report and CSV.                                      |
| `-Watch`          |          | Sample live instead of analyzing history.                               |
| `-WatchMinutes`   | 30       | How long to watch.                                                      |
| `-CpuThreshold`   | 80       | CPU percentage that triggers a snapshot while watching.                 |
| `-SampleSeconds`  | 5        | Seconds between samples while watching.                                 |
| `-InstallPerfLog` |          | Register and start the Performance Monitor collector.                   |
| `-RemovePerfLog`  |          | Stop and delete the collector.                                          |

## What the report contains

The report is internal material. It contains hostnames, file paths, client IP addresses and request paths from the
access logs, and messages from the error logs. A `-Watch` snapshot adds process command lines and the shape of the
running database queries. Before the script writes any of those, it strips query strings from URLs, replaces
credential-looking values, and replaces the literal values in SQL statements with placeholders.

The database credentials in each site's `.env` file are used only to run read-only status queries. The password is
never written to the report, the console or a command line.

## Send the report for analysis

Email the report and the CSV to the Curator support team, together with the files described in
[Performance Diagnostics](/site_administration/performance/performance_diagnostics), and say which spike times you were
told about. The support team will read the timeline against those times and recommend specific changes.

## Troubleshooting

* **"No Apache access logs were found."** The access log is declared by a `CustomLog` line in `curator.conf` or
  `httpd.conf`. If logging was turned off, turn it back on and re-run after a day of traffic.
* **"Task Scheduler history is disabled on this server."** Open Task Scheduler and choose **Enable All Tasks History**
  in the Actions pane, or run `wevtutil sl Microsoft-Windows-TaskScheduler/Operational /e:true` from an elevated
  prompt. The next run can then measure how long each `schedule:run` takes.
* **"The access log format has no request duration field."** Adding `%D` to the `LogFormat` line in `curator.conf`
  lets the next run report how long each request took, which separates slow pages from busy ones. Restart Apache after
  the change.
* **The CPU history section is empty.** Windows keeps no CPU history unless a collector is running. Follow Step 3 and
  re-run after the next spike.


# Windows - Cron Troubleshooting
Source: https://docs.curator.interworks.com/server_management/system_administration/windows_cron_troubleshooting

Troubleshooting guide for resolving Windows cron job issues in Curator installations, including scheduled task path fixes and configuration problems.

Curator runs regularly scheduled tasks on Windows using Task Scheduler. This takes care of things like status checks,
scheduled reports, user-syncing along with a host of other very important items. Occasionally this setup can have
issues, so we've provided some steps for resolving common problems related to Windows scheduled tasks.

## Scheduled Task Troubleshooting

### Path Issues

The most common issue with Windows scheduled tasks for Curator is an incorrect path to the artisan file. To troubleshoot this:

1. Open Task Scheduler:
   * Press `Windows Key + R`, type `taskschd.msc`, and press Enter
   * Or search for "Task Scheduler" in the Start Menu

2. Find the Curator task:
   * Look for tasks named "Curator Cron", "Curator Central Dispatch", or similar
   * Double-click the task to open its properties

3. Check the action path:
   * Click the "Actions" tab
   * Click "Edit" to view the action details
   * Note the full command in the "Program/script" and "Add arguments" fields
   * Common format: `C:\InterWorks\Curator\libs\PHP\php.exe C:\InterWorks\Curator\htdocs\artisan schedule:run`
   * **Note:** Your installation path may differ (e.g., `D:\Curator`, `E:\InterWorks\Curator`, etc.)

4. Test the command manually:
   * Open Command Prompt as Administrator
   * Copy the full command from the scheduled task (combining program and arguments)
   * Run the command exactly as it appears in the task
   * Observe the output:
     * **Success**: Command runs without errors
     * **"The system cannot find the path specified"**: Path to php.exe or artisan is incorrect
     * **PHP errors**: Path is correct but there are application issues
     * **No output**: May indicate the command is running but not producing visible output

5. Common path corrections:
   * Verify your Curator installation directory (common locations: `C:\InterWorks\Curator`, `D:\Curator`, etc.)
   * Ensure php.exe exists at: `[YourInstallDir]\libs\PHP\php.exe`
   * Confirm artisan file exists at: `[YourInstallDir]\htdocs\artisan`
   * Update the scheduled task with corrected paths if needed
   * **Remember:** Replace `[YourInstallDir]` with your actual installation path

### Determine Correct Scheduled Task User

The scheduled task should run as the same user that your web server (IIS/Apache) is running as. Here's how to determine the correct user:

**Check Web Server User in Curator Backend:**

1. <BackendNavPath />
2. Look for the "User" field in the System Information section
3. This shows which user account your web server is running as (e.g., IIS\_IUSRS, SYSTEM, apache, etc.)
4. Your scheduled task should be configured to run as this same user to avoid permission issues

**Verify Current Task User in Task Scheduler:**

1. In Task Scheduler, find the Curator task

2. View the user account using one of these methods:
   * **Method 1:** In the main panel, look at the "Security options" column
   * **Method 2:** Double-click the task, go to "General" tab
   * Look for "When running the task, use the following user account:"
   * Common accounts: SYSTEM, NT AUTHORITY\SYSTEM, or a service account

3. Additional task details:
   * "Actions" tab shows the exact command being run
   * "History" tab shows recent execution logs and any errors
   * "Triggers" tab shows when the task runs (typically every minute)

**Using PowerShell:**

```powershell theme={null}
# List all Curator scheduled tasks with their run-as user
Get-ScheduledTask | Where-Object {$_.TaskName -like "*Curator*"} | 
    ForEach-Object {
        [PSCustomObject]@{
            TaskName = $_.TaskName
            State = $_.State
            RunAsUser = $_.Principal.UserId
            Action = $_.Actions.Execute + " " + $_.Actions.Arguments
        }
    }
```

### Test Scheduled Task

To verify the scheduled task is working properly:

1. **Test command directly in Command Prompt:**
   * Open Command Prompt as Administrator
   * Navigate to your Curator directory (adjust path as needed): `cd C:\InterWorks\Curator`
   * Run the exact command from your scheduled task
   * **Important:** Replace the paths below with the actual paths from your Task Scheduler action:
     ```
     C:\InterWorks\Curator\libs\PHP\php.exe C:\InterWorks\Curator\htdocs\artisan schedule:run
     ```
     (Your paths may differ - use `D:\`, `E:\`, or different directory names as shown in Task Scheduler)
   * Check the output:
     * **Success**: Shows "Running scheduled command:" or similar output
     * **Errors**: Note any error messages for troubleshooting

2. **Manual test via Task Scheduler:**
   * Right-click the Curator task in Task Scheduler
   * Select "Run"
   * Check the "Last Run Result" column (should show "0x0" for success)

3. **Check via Curator API:**
   * Follow instructions in the [Auto Generate API Links](/curator_api/getting_started/curator_api_overview) section
   * Set dropdowns to **Portal** and **cron** respectively
   * Click the preview link
   * Should display a "success" message

4. **Verify in logs:**
   * Check Curator logs at: `[InstallDir]\storage\logs\system-[date].log`
   * Look for recent cron execution entries

### Common Issues and Solutions

1. **Task runs but nothing happens:**
   * Check if the user account has permissions to the Curator directory
   * Verify PHP can be executed by the task user
   * Check Windows Event Viewer for errors

2. **Task shows error code:**
   * `0x1`: General error - check the command syntax
   * `0x2`: File not found - verify all paths
   * `0x5`: Access denied - check permissions

3. **Task doesn't run on schedule:**
   * Verify the trigger is set to run every minute
   * Check if "Start the task only if the computer is on AC power" is unchecked
   * Ensure "Run whether user is logged on or not" is selected


# Requirements
Source: https://docs.curator.interworks.com/setup/Server_Requirements/requirements



## General Requirements

Your Curator server must be its own standalone web server. Installing on the same web server as Tableau Server is
**not** supported.

Containerized deployments are also **not** currently supported.

Your Curator server will need to be able to communicate directly with your Tableau Server, and your
Tableau Server will need the REST and Metadata APIs enabled.

<u>Curator Standard/Enterprise</u>

If you are hosting, you will need a standalone web server on which to install the software. By
choosing to self-host, you are also accepting responsibility for:

* Ensuring a robust backup routine beyond Curator's built-in full backup functionality.
* Performing server upgrades and maintenance for security patches, etc.
* Applying and maintaining SSL/TLS certificates, DNS, and firewall protections.

This can be highly customized, but plan on following minimum specifications:

* Linux (preferred) or Windows
* At least 4 CPU, 8GB of RAM and 20GB of disk space available
* Ports open for web traffic (80 and 443)
* A disaster recovery plan

For AWS-hosted instances, we recommend:

| Linux (preferred)                    | Windows                              |
| :----------------------------------- | :----------------------------------- |
| t4g.large                            | t3a.xlarge                           |
| Ubuntu 24.04 LTS or newer            | Windows 2019 or above                |
| 20GB of gp3 SSD @ 3000 IOPS/125 MB/s | 20GB of gp3 SSD @ 3000 IOPS/125 MB/s |

## High Availability (Multiple Instances)

<u>Curator Standard/Enterprise</u>

Curator supports running multiple application instances behind a load balancer in a high availability (HA)
topology. In this setup, two or more application nodes share a single database and filesystem, allowing traffic
to be distributed across nodes for better uptime and increased concurrent user capacity.

Running multiple Curator instances on the **same single server** is **not** supported. Each Curator instance must
run on its own dedicated server (or virtual machine) that meets the standard server requirements listed above.

For full details on supported HA topologies, infrastructure components, and setup instructions, see the
[High Availability](/setup/high_availability/high_availability) guide.


# Active Directory
Source: https://docs.curator.interworks.com/setup/authentication/active_directory

A guide to setting up Active Directory authentication for Curator.

## Web Server Setup (Apache)

1. Find the **`curator.conf`** file (default location is `C:\InterWorks\Curator\curator.conf`).

2. Un-comment the lines (by deleting the `#` at the front of the line) starting at
   `LoadModule authnz_sspi_module modules/mod_authnz_sspi.so` and ending at `</Location>`.  See example below:

   ```conf theme={null}
   # Uncomment the lines below for AD automatic login
   LoadModule authnz_sspi_module modules/mod_authnz_sspi.so
   <Location />
       AuthName "Curator"
       AuthType SSPI
       SSPIAuth On
       SSPIAuthoritative On
       <RequireAll>
           <RequireAny>
               Require valid-user
           </RequireAny>
           <RequireNone>
               Require user "ANONYMOUS LOGON"
           </RequireNone>
       </RequireAll>
   </Location>
   ```

3. After the configuration file has been edited and saved, restart the webserver.

## Curator Setup

After you have completed the Curator installation and the Web Server Setup steps above, you can enable Active
Directory/Kerberos on Curator.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Security** > **Authentication Settings** section from the left-hand menu.
3. Change the "Authentication Type" to  **Active Directory / Kerberos**.


# Microsoft Entra ID (Azure AD)
Source: https://docs.curator.interworks.com/setup/authentication/azure_ad_saml

A guide to setting up Microsoft Entra ID (formerly Azure AD) SAML authentication for Curator.

<Note>
  Microsoft renamed **Azure Active Directory (Azure AD)** to **Microsoft Entra ID** in 2023.
  These two names refer to the same service. This documentation applies to both.
</Note>

## Switching from Another SAML Provider (e.g. Okta)

If you are moving an existing Curator instance from a different SAML identity provider (such as Okta or OneLogin) to
Microsoft Entra ID, you are replacing Curator's current SAML configuration in place. Curator supports **one active
authentication provider at a time**, so there is no way to run the old and new SAML IdPs side by side — the new
Entra configuration takes over from the old provider the moment you save.

<Warning>
  Saving new authentication settings takes effect **immediately** for everyone. As soon as you save the Entra
  configuration, all users are directed to Entra on their next login, and the previous provider is no longer used.
  Plan the change for a maintenance window and validate it before announcing it to end users.
</Warning>

<Note>
  This is different from a portal-to-portal migration (moving to a new server and cutting over DNS), which is
  covered in the [SAML Cutover Process](/upgrading_migration/migration/saml_cutover) guide. The steps below are for
  swapping the SAML identity provider on the **same** running Curator instance.
</Note>

**Recommended cutover steps:**

1. **Prepare the Entra app in advance** — Complete the [Azure App Creation](#azure-app-creation) and
   [Azure to Curator Configuration](#azure-to-curator-configuration) steps below before your cutover window, and have the
   Entra Federation Metadata XML ready to import so the live change is quick.
2. **Provision every user in Entra first** — Each Curator user must exist in Microsoft Entra with a username that
   matches their Tableau Server username *exactly* (see the
   [Provisioning Users](#provisioning-users-on-microsoft-entra-id-azure-ad) section below). Any user not provisioned in
   Entra will be unable to log in after the switch.
3. **Update Curator's authentication settings during the window** — In the backend under **Settings** >
   **Security** > **Authentication Settings**, import the Entra metadata (see
   [Import Azure Metadata to your Curator Instance](#import-azure-metadata-to-your-curator-instance)) and save. This is
   your cutover point — the previous provider is replaced immediately.
4. **Validate with a test user before announcing** — Log in as a test user through the Entra flow to confirm the
   integration works end to end before telling end users the switch is complete.
5. **Decommission the old IdP app** — Once the migration is confirmed stable, remove the Curator enterprise
   application from your previous identity provider.

## Provisioning Users on Microsoft Entra ID (Azure AD)

For provisioning users with Azure AD, you will need to have a user created in both Azure AD and Tableau Server - their
username's must match (the "Application username format" step in #4 below).

Once the user logs in, their username in Azure needs to match *exactly* the username of a user on Tableau Server.

## Curator Setup

If you have not installed Curator you can do this with the commands in the Installation documentation.

Also ensure you have connected to your Tableau Server instance following the [Tableau Server connections steps](/creating_integrations/tableau_connection/creating_a_connection).

## Tableau Setup

**Tableau Cloud**
Tableau has excellent documentation on connecting Azure AD to Tableau Cloud. [https://help.tableau.com/current/online/en-us/saml\_config\_azure\_ad.htm](https://help.tableau.com/current/online/en-us/saml_config_azure_ad.htm)

Make sure to follow the additional setup steps in the Tableau Cloud documentation.

**Tableau Server**
To ensure that after a user signs in to SAML via Curator they do not have to re-sign in to the embedded Tableau Server Dashboard:

On your Tableau Server run the command below:

```bash theme={null}
tsm configuration set -k wgserver.saml.iframed_idp.enabled -v true
```

Next, either run:

```bash theme={null}
tsm pending-changes apply
tsm restart
```

Or open TSM in your browser and click Pending Changes at the top of the page then click 'Apply Changes and Restart'.

## Azure App Creation

The app you create here will be in addition to the one you already setup for Tableau.

### Create your Azure App

1. Login to [https://portal.azure.com](https://portal.azure.com)
2. In the search bar search for "Azure Active Directory" and click the result that matches from the result list.
3. From the left-hand menu click "Enterprise Applications"
4. Click "Create a new application"
5. Click the "+ Create your own application"
6. Enter a name for your app and select the **non-gallery** option - We recommend the name `Curator`
7. Click "Create"

## Azure to Curator Configuration

### Import Curator Metadata to your Azure App

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`)
2. Navigate to the **Settings** > **Security** > **Authentication Settings** section from the left-hand menu.
3. Change the "Authentication Type" to SAML
4. This will expose two buttons, click the "Download SAML Metadata" button, and save the file somewhere you can soon retrieve.
5. Return to the app you created in the steps above in the Azure portal, and from the left-hand navigation click
   "Single sign-on".
6. At the top click "Upload metadata file" and upload the file you downloaded from Curator in step #4 here.

### Import Azure Metadata to your Curator Instance

1. Continuing from the steps above, while still on the same page find the section of the page titled
   "SAML Signing Certificate" and click the "Download" link next to **Federation Metadata XML**
2. Save this file.
3. Click the "Import SAML Metadata" button and follow the steps to upload the file downloaded in step #7.
4. After the file is uploaded, ensure your Authentication Type is still set to SAML and re-save your settings.

#### Troubleshooting Attributes and Claims

In many cases you will need to adjust the "Attributes and Claims" section on your app by adding a new claim with the
name "username".  If you see an error on logging in after setting up saying "User \[username] not found" the
\[username] is what Azure is sending to Curator.  That must match exactly the username found on Tableau Server.

**Note**: If you have already created a Tableau app in Azure and your authentication is running successfully, then
simply ensure the Attributes and Claim and configuration of your Curator app matches exactly the setup you have for
your Tableau app.

**Troubleshooting Tableau Login**
If a Tableau login button appears where a Dashboard should be after configuring SAML, be sure to follow the steps to
enable iFrame embedding in the following document:
[https://help.tableau.com/current/online/en-us/saml\_config\_okta.htm#optional-enable-iframe-embedding](https://help.tableau.com/current/online/en-us/saml_config_okta.htm#optional-enable-iframe-embedding)


# Curator Users
Source: https://docs.curator.interworks.com/setup/authentication/curator_users

A guide to setting up local Curator users to authenticate with SAML.

If you would like to use SAML for authentication with your Curator users, but do not want to use a 3rd party tool
(e.g. Okta) you're in luck - you can utilize Curator as your Identity Provider (IdP)!  However, there is one important
caveat: if you set up Curator as your IdP by following the instructions for Curator Users below, you will also need to
make Curator your IdP for any connected applications (e.g. Tableau Cloud).
, they will then be redirected back to whichever entry point they came in from (e.g. Tableau Cloud will redirect back to
Tableau's homepage and Curator will redirect back to Curator's homepage).

**If you set up Curator as your IdP for Tableau ALL users will see the Curator login when trying to access
Tableau directly**.

NOTE: This setup will *not* work with Tableau Server, and is not needed due to the availability of using Trusted Ticket
on Tableau Server.

## 1. Curator Setup

If you have not installed Curator yet, please refer to our installation documentation in the setup section on the
left-hand side menu.

Also ensure you have connected to your Tableau Cloud instance following the
[REST API  Integration steps](/creating_integrations/tableau_connection/creating_a_connection).

## 2. Retrieve Tableau SAML Details

Next, navigate to your Tableau Cloud instance and find the Tableau Entity ID and the Assertion Consumer Service URL
(ACS) by setting your Authentication type to SAML.

[Tableau Cloud Documentation for reference](https://help.tableau.com/current/online/en-us/saml_config_okta.htm)

## 3. Curator IdP Setup

1. Navigate to the **Settings** > **Security** > **SAML IdP** section from the left-hand menu.

2. Fill out the required fields:
   * For the **Curator Entity ID** enter the URL of your Curator website
   * For the **Tableau Entity ID** paste in the value you retrieved from the previous step
   * For the **Assertion Consumer Service URL (ACS)** paste in the values

3. Once the form is completed, click the "Auto-Generate Key/Cert" button and fill out the form, then click "Generate".

4. Save this page

5. After saved successfully, click the "Download Metadata" button at the top and save this file, it will default to
   `curator_metadata.xml`.

## 4. Setup Tableau Cloud SAML

1. Return to Tableau Cloud
2. Click the **Settings** menu item on the left, then the **Authentication** tab at the top of the page.
3. Ensure "SAML" is selected under the "Enable an additional authentication method" section.
4. Find the "Import metadata file into Tableau Cloud" section, and upload the `curator_metadata.xml` file you download
   in the previous step then click "Apply"
5. In the "Match attributes" below, ensure the "Identity Provider (IdP) Assertion Name" is set to "email", and select
   "Full name" for "Display Name", and change the value to "full\_name" and click "Apply"

Last, you can click the "test connection" button in the *Import metadata file into Tableau Cloud* section to ensure your
SAML authentication has been set up correctly to direct users to Curator.  You should see your Curator login screen
appear (if you are not already logged in).

You can now change individual users on the list-users screen in Tableau Cloud by changing the user's configuration to SAML.

## 6. Testing Your Curator Users Authentication

**NOTE**: You *must* complete Step #3 for this button to display.

1. Navigate to the **Settings** > **Tableau** > **Frontend Users** section from the left-hand menu.
2. Click the "Sync from Tableau" button
3. Once the sync has finished, open an incognito window in your web-browser
4. Visit your Tableau Cloud site and log in with a user that has been registered as a SAML user on Tableau Cloud.
5. You will be redirected to Curator to login, after which you will be redirected again to Tableau Cloud.
6. You have now set up Curator as your SAML IdP, nice work!


# Local Login Fallback
Source: https://docs.curator.interworks.com/setup/authentication/local_login_fallback

A guide to enabling an unlisted page where users sign in with their Curator credentials while the site uses SSO.

When Curator is configured for single sign-on, the standard login page at `/user/login` hands every visitor straight to
your identity provider (IdP). That is usually exactly what you want -- but it leaves no way in when the IdP is
unavailable, when its certificate has expired, or when an account exists in Curator but not in the IdP.

The **Local Login Fallback** setting adds a second, unlisted login page at `/user/local_login` that checks a user's
Curator username and password instead. Everything else on the site keeps using your configured authentication type, and
`/user/login` continues to redirect to the IdP exactly as before.

The setting is off by default. While it is off, `/user/local_login` returns a "page not found" response, so the page
does not exist until you turn it on.

## Enabling the Fallback

1. Go to **Settings** > **Security** > **Authentication**.
2. In the **Customization** section, toggle "ON" the *Local Login Fallback* switch.
3. Save these settings.

The switch is only shown when the site uses an authentication type that sends users elsewhere to sign in (SAML, OAuth,
Active Directory, Tableau Server or ThoughtSpot). It is hidden for **Curator Users** and **Pass-Through**, where the
standard login page already accepts Curator credentials and a fallback would add nothing.

## Using the Fallback

The page is deliberately unlisted -- nothing in the site's navigation, footer or login page links to it. Share the URL
with the people who need it:

```text theme={null}
https://your-curator-site.com/user/local_login
```

The form on that page looks and behaves like the standard login form, with one difference: it checks the username and
password stored on the user's **Curator** account, rather than passing the sign-in to your identity provider, Tableau
Server or ThoughtSpot. A failed attempt returns to `/user/local_login` so a mistyped password does not send the user
back to the IdP.

## Which Accounts Can Sign In

Only accounts that have a Curator password set can use this page. Users provisioned automatically at their first SSO
sign-in (just-in-time provisioning) normally have no Curator password, and cannot sign in here until one is set for
them under **Settings** > **Users** > **Frontend Users**.

The **Password** field on an individual frontend user's page appears whenever this setting is on, whatever
authentication type the site uses. While the setting is off, an SSO site hides that field, because no Curator password
is checked anywhere.

Passwords for this page are administrator-controlled. The fallback page deliberately offers no "forgot password" link,
and self-service password reset is unavailable while the site is configured for SSO -- a backend administrator sets and
changes these passwords under **Settings** > **Users** > **Frontend Users**. This keeps the page to its intended
audience: administrators, and the handful of people who need a way in when they are not in the identity provider.

Because of that, set a Curator password on at least one administrator account *before* you need the fallback. If the
only account with a password forgets it while the identity provider is down, there is no self-service way to recover
it.

<Warning>
  This page authenticates against Curator, so any policy your identity provider enforces -- MFA, conditional access,
  device or network restrictions, session limits -- does **not** apply to sign-ins made through it. Curator's own
  [multifactor authentication](/setup/authentication/multifactor_authentication) setting still applies: if it is enabled,
  users signing in through the fallback are challenged for a code as usual.

  Treat the URL as sensitive, enable the setting only while you need it, and turn it back off afterwards.
</Warning>

## Auditing Its Use

Both successful and failed sign-ins through the fallback are written to the Curator log with the username and the
client IP address, so you can review use of the page under **Settings** > **Curator** > **Event Log**. Login throttling
is shared with the standard login page -- the fallback does not grant a separate set of attempts.


# Multifactor Authentication (MFA)
Source: https://docs.curator.interworks.com/setup/authentication/multifactor_authentication

A guide to setting up multifactor authentication (MFA) for Curator users.

If your Curator system is using a Curator-based authentication form, multifactor authentication is available utilizing
Google Authenticator (or another authenticator app of your choice -- see
[Customizing the Suggested Authenticator App](#customizing-the-suggested-authenticator-app) below).

After enabling multifactor authentication, users will be prompted to setup the Authenticator application using a QR
code. For more information on the frontend user interface, see our
[feature demo video](https://curator.interworks.com/page/curator-new-feature-spotlight-multi-factor-authentication).

## Curator Setup

1. To enabled MFA, go to **Settings** > **Security** > **Authentication**.
2. In "Customization", toggle "ON" the Multi-factor Authentication switch.
3. Save these settings
4. Now, all users will be prompted to setup and use multifactor authentication after their next login.

## Customizing the Suggested Authenticator App

The Curator-based MFA setup screen suggests a single authenticator app and provides per-platform download links.
The defaults are Google Authenticator, but any RFC 6238 TOTP authenticator app works with Curator's QR code -- if your
organization standardizes on a different app (for example, Microsoft Authenticator), you can change the suggestion in
**Settings** > **Security** > **Authentication** using the three fields shown when *Multi-factor Authentication* is
enabled:

* **MFA Authenticator App Name** -- The name shown in the download step (e.g. `Microsoft Authenticator`). Leave blank
  to use the default (`Google Authenticator`).
* **MFA Authenticator App Store URL (iOS)** -- The link followed when a user clicks the bold app name on the iOS tab.
  Must start with `https://`. Leave blank to use the default Google Authenticator App Store link.
* **MFA Authenticator App Store URL (Android)** -- The link followed when a user clicks the bold app name on the
  Android tab. Must start with `https://`. Leave blank to use the default Google Authenticator Play Store link.

Each field is independent -- you can change only the name, only the URLs, or any combination, and Curator falls back
to the Google Authenticator default for any field left blank.

## Backend Administrator MFA

Backend administrator accounts (the users who sign in at `/backend`) do not have a dedicated MFA toggle of their own.
Instead, MFA is applied to backend administrators by routing their sign-in through the frontend authentication form:

1. In **Settings** > **Curator** > **Portal Settings**, on the **General** tab, enable
   *Force Backend Users to Login Via Frontend Authentication Forms*.
2. Make sure every backend administrator has a frontend user with a matching username. Only backend usernames matching
   frontend users will be able to access Curator's administrative interface. See the
   [Backend Administrators](/site_administration/backend_administrators/overview) documentation for the full setup.
3. Enable MFA as described in [Curator Setup](#curator-setup) above.

With both settings enabled, a backend administrator visiting `/backend` is redirected to the frontend login form,
completes the standard frontend MFA challenge via their authenticator app, and is then re-routed back to the backend.
A backend session that exists without a verified MFA challenge will be redirected to `/user/mfa` before any backend
page is served.

<Note>
  If your Curator instance authenticates users through SAML, MFA is handled by your identity provider rather than by
  Curator. Configure MFA policies (and any backend-administrator-specific MFA enforcement) at the IdP, and Curator will
  honor whatever assertions the IdP returns.
</Note>

## Emergency Access (Break-Glass)

Curator does not ship a dedicated break-glass authentication feature -- there is no separate emergency login flow that
bypasses MFA, SAML, or *Force Backend Users to Login Via Frontend Authentication Forms*. If the frontend authentication
path is unavailable (for example, the SAML identity provider is down, or the MFA secret for an administrator is lost),
recovery is a two-step process: disable *Force Backend Users to Login Via Frontend Authentication Forms* through one of
the supported channels below, then sign in directly at `/backend` with a backend administrator's username and password.

Curator exposes two supported ways to toggle that setting without a working admin session:

### Option 1: Artisan CLI command (On-Prem only)

On On-Prem deployments where you have SSH access to the Curator server, run the
`portal:forcefrontendloginforbackend` artisan command from the application root:

```bash theme={null}
php artisan portal:forcefrontendloginforbackend 0 --force
```

The first argument accepts `0` (disable) or `1` (enable); `--force` skips the confirmation prompt. After the command
reports success, the administrator can sign in directly at `/backend` with their backend-account credentials. Once
access is restored, re-enable forced frontend login by running the same command with `1`:

```bash theme={null}
php artisan portal:forcefrontendloginforbackend 1 --force
```

### Option 2: API endpoint

If you have a Curator API key with access to the `portal.setForceFrontendLoginForBackend` permission, send a `POST`
request to `/api/v1/portal/setForceFrontendLoginForBackend` with `force_frontend_login_for_backend=0`:

```bash theme={null}
curl -X POST "https://your-curator-domain/api/v1/portal/setForceFrontendLoginForBackend" \
    -d "apikey=YOUR_API_KEY" \
    -d "force_frontend_login_for_backend=0"
```

The response confirms the new value. After signing in at `/backend`, re-enable forced frontend login by sending the
same request with `force_frontend_login_for_backend=1`.

<Note>
  Audit `storage/logs/system-YYYY-MM-DD.log` for the sign-in event whenever break-glass access is used, and re-enable
  *Force Backend Users to Login Via Frontend Authentication Forms* as soon as the underlying issue is resolved so that
  backend administrators continue to authenticate through the frontend MFA/SAML flow.
</Note>

## Troubleshooting

When a user reports that their authenticator codes are rejected, the cause is almost always one of three things: they
are reading a code from a stale entry in their app, their device clock has drifted, or the portal's own clock has
drifted. Work through the steps below in order.

### The user has more than one Curator entry in their authenticator app

This is the most common cause, and the easiest to miss. Curator labels the QR code with the user's username and the
portal name, and neither changes when an administrator clears a user's MFA. The secret behind the entry does change,
so **every reset adds another entry to the authenticator app with a name identical to the previous one**. Nothing in
the app distinguishes the live entry from the dead ones, and a user reading a code from an old entry sees it rejected
every time.

Have the user delete **every** Curator entry from their authenticator app before re-enrolling, not just the one they
believe is current. After they scan the new QR code there should be exactly one Curator entry left, and the code they
read from it is the only one that will be accepted.

### The user's device clock has drifted

TOTP codes are derived from the current time, so a device whose clock is wrong generates codes that are correct for the
wrong moment. Ask the user to set their phone's date and time to update automatically, then try again.

<Note>
  Some authenticator apps used to expose a setting that corrected their internal clock independently of the device
  clock. Do not rely on finding one -- these options have been removed from several apps, including Google
  Authenticator. Setting the device itself to automatic time is the step that matters, and it works regardless of which
  authenticator app the user has.
</Note>

### The portal's clock has drifted

Curator accepts a code from the current 30-second window and from one window on either side, so a code is valid for
roughly **30 seconds before and after** the moment it was generated. That tolerance is not configurable. It is
generous enough to absorb a user typing slowly, but not much more -- if the portal host's clock is off by more than
about half a minute, codes generated by perfectly accurate phones are rejected.

Suspect this when the symptoms do not fit a per-user problem:

* several users fail at once, rather than one;
* the failures survive repeated MFA resets, so the stored secret is clearly not the issue;
* and a user occasionally starts working again with nothing having been changed, which is what a clock sitting near
  the edge of the tolerance window looks like as it drifts back and forth across the boundary.

On an On-Prem deployment, check that the Curator server's time is synchronized against a reliable time source and
correct it if it has drifted. On InterWorks-hosted deployments, raise this with InterWorks support and quote the
pattern above, since host time synchronization is managed for you.

### What to collect before escalating

If the steps above do not resolve it, gather the following before contacting support. Each one rules out a cause that
would otherwise have to be guessed at:

* confirmation that only **one** Curator entry remains in the user's authenticator app;
* the exact time and time zone shown on the user's device at the moment they submit a code that is rejected;
* whether the failure affects one user or several, and whether it has ever cleared on its own;
* the username affected and the approximate time of the most recent failed attempt, so the attempt can be matched
  against `storage/logs/system-YYYY-MM-DD.log`.

<Note>
  An administrator clears a user's saved MFA at **Settings** > **Users** > **Frontend Users**, by opening the user and
  clicking **Remove Saved MFA**. The button appears only while *Multi-factor Authentication* is enabled in
  **Settings** > **Security** > **Authentication**, and requires the *Manage Frontend Users* permission. Clearing the
  secret prompts the user to enroll again with a fresh QR code at their next sign-in.
</Note>


# Okta
Source: https://docs.curator.interworks.com/setup/authentication/okta_saml

A guide to setting up Okta SAML authentication for Curator.

After you have installed Curator, you can being integrating your users seamlessly with your existing Okta instance.
This guide will walk you through the steps to set up Okta SAML authentication for Curator, allowing users to log in
through a single sign-on (SSO) experience.

## Tableau Setup

Before you can set up Okta SAML authentication for Curator, you need to ensure that your Tableau Server or Tableau Cloud
is configured to work with Okta. This involves setting up SAML authentication on Tableau, which is a prerequisite for
integrating with Okta.

You can either refer to the [Tableau Cloud guide to setting up Okta](https://onlinehelp.tableau.com/current/online/en-us/saml_config_okta.htm)
or the [Okta guide to configure SAML for Tableau Server](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Tableau-Server.html).

## Creating an Okta Application

In order to link Curator to your Okta instance, you must first create a new Application on Okta. If you already have an
Okta application set up for Tableau (Server or Cloud), you will **not** be able to re-use that application for Curator
and will need to create an application dedicated to Curator integration.

Refer to the Okta document on [creating a new SAML 2.0 integration](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm).

### Curator Details to use for your Curator Okta app

You will need to use some Curator-specific details when setting up the Okta application. Below are the details you would
use for a new Curator site installed at the url `https://mycuratorsite.com`:

* **Single sign-on URL**: `https://mycuratorsite.com`. This is the URL that users will be redirected to after logging
  in.  Use the URL to the homepage of Curator.
* **Audience URI (SP Entity ID)**: `curator-site.com` This is the identifier for the service provider (Curator) in the
  SAML authentication process.
* **Application username format**: `Email` (typically). If your users do not use email to login to Okta applications,
  then select the format that matches Tableau Okta app's usernames.
* **Application username format**:  `user.email` (typically).  If your users do not use email to login to Okta applications,
  then select the user-attribute that matches the Tableau Okta app's usernames.

## Curator Setup

Once you've created the Okta application, you can proceed to configure Curator to use SAML authentication with Okta.

### Export Authentication Metadata from Okta

Follow the [Okta guide to downloading your SAML metadata](https://support.okta.com/help/s/article/Location-to-download-Okta-IDP-XML-metadata-for-a-SAML-app-in-the-new-Admin-User-Interface).
Ultimately, this will provide you with a `.xml` file that contains the necessary metadata for
integrating Okta with Curator.

### Add Okta metadata to Curator

<BackendNavPath />

#### Importing Okta Metadata

From the authentication list select "SAML". You can use the "Import SAML Metadata" button to import the XML file you generated
from Okta.

<img alt="Import SAML metadata" />

#### Manually Entering Okta Metadata

Alternatively, you can manually enter the information:

* **Entity ID**:  Enter the "Audience URI (SP Entity ID)" you filled in before.
* **SignOn URL**: Enter the "Identity Provider Single Sign-On URL" URL found in the setup section.
* **IdP ID**: Enter the "Identity Provider Issuer" from the setup section.
* **SignOut URL**: Enter the URL of the application `/login/signout` (i.e.
  [https://mydomain.okta.com/login/signout](https://mydomain.okta.com/login/signout))
* **Certificate**: Open the "SAML Advanced" section, copy the certificate text from Okta, and paste it in the field.

## Enabling iFrames for Tableau's Okta App

You may encounter issues with seamlessly embedding Tableau content in Curator if the Okta application is not set up to
allow  iFrame embedding - if you see an image like the one below when trying to access Tableau content in Curator,
then you will need to refer to Tableau's guide on [enabling iFrame embedding for Okta](https://help.tableau.com/current/online/en-us/saml_config_okta.htm#about-enabling-iframe-embedding)
to complete your Okta integration.

<img alt="Tableau iFrame embed without authentication" />

### Additional Customization Options

#### Auto-launch

You may want to select a few options to make the login process more streamlined. First, set the Curator application to
"Auto-launch" in the "edit application" section on Okta.

#### Hide Tableau Cloud Icon

You may also wish to hide the Tableau Cloud icon from users. You can do this in the edit application area for the
Tableau Cloud app. Under "App Settings", select "Do not display application icon to users".

#### Sign-out Page

When users sign out of Curator, they will be redirected to the Okta sign-out page by default. This may be preferred, but
if you'd like to redirect users back to the homepage of Curator, refer to Okta's guide on
[customizing the sign-out page](https://help.okta.com/en-us/content/topics/settings/settings-configure-sign-out.htm).


# OneLogin (OIDC)
Source: https://docs.curator.interworks.com/setup/authentication/one_login_oidc

A guide to setting up OneLogin as an OpenID Connect (OIDC) provider for Curator.

## OneLogin Setup

1. Go to the Applications page in the Administration area of OneLogin and click "Add App."
2. Enter "oidc" in the search bar and select "OpenId Connect (OIDC)." The vendor should be "OneLogin, Inc."
3. Give the Application a display name like "InterWorks Curator," upload icons if you'd like, and click "Save."
4. In the Application's settings page, navigate to "Configuration" and enter the following for the URL and URI's:
   * **Login URL**: Base Curator URL (i.e. `https://www.curatorexample.com`).
   * **Redirect URI's**: Base Curator URL with `/user/oauth` appended (i.e.
     `https://www.curatorexample.com/user/oauth`). No other URI's should be entered.
   * **Post Logout Redirect URI's**: Base Curator URL (i.e. `https://www.curatorexample.com`). No other URI's should be entered.
5. In the Application's settings page, navigate to "SSO" and set the following:
   * **Application Type**: Set this to "Web."
   * **Token Endpoint - Authentication Method**: Set this to "POST."
6. Save the settings and stay on the "SSO" page. We'll need this info for the Curator-side of the setup.

## Curator Setup

1. Go to the Authentication Settings under Settings > Security in the Curator backend.
2. Choose "OAuth / OpenID Connect" for the Authentication Type.
3. Expand the "Customization" section and enter the following:
   * **OAuth Domain**: Enter the "Issuer URL" from the "SSO" area of the Application's settings in OneLogin. This
     usually ends in `/oidc/2`.
   * **OAuth Client ID**: Enter the "Client ID" from OneLogin.
   * **OAuth Client Secret** Enter the "Client Secret" from OneLogin. You may have to click "Show client secret" in
     OneLogin to see it.
4. Save the settings.

## Users

As users log in via OAuth, user records will automatically be provisioned in Curator. If Curator is connected to an
analytic platform it will sync over details like display name or email at the same time during login. No SCIM necessary!


# OneLogin
Source: https://docs.curator.interworks.com/setup/authentication/one_login_saml

A guide to setting up OneLogin SAML authentication for Curator.

## Server Setup

If the server is not already setup for web traffic, install Apache, MySQL, PHP, and dependencies. You can do this with
the commands in the setup documentation.

## Tableau Cloud Setup

Tableau has excellent documentation on connecting OneLogin to Tableau Cloud.
[https://onlinehelp.tableau.com/current/online/en-us/saml\_config\_onelogin.htm](https://onlinehelp.tableau.com/current/online/en-us/saml_config_onelogin.htm)

Make sure to follow the additional setup steps in the Tableau Cloud documentation.

If a Tableau login button appears where a Dashboard should be after configuring SAML, be sure to follow the steps to
enable iFrame embedding in the following document:
[https://help.tableau.com/current/online/en-us/saml\_config\_okta.htm#optional-enable-iframe-embedding](https://help.tableau.com/current/online/en-us/saml_config_okta.htm#optional-enable-iframe-embedding)

## OneLogin App Setup

In the OneLogin system, ensure you have turned OFF framing protection by going to "Settings->Account Settings". At the
bottom of the page, ensure that "Framing Protection" is disabled by "checking" the box next to it. (Make sure to hit
"Save" after checking the box! They hide it at the top of the page.)

Then, setup a new App of type "Tableau Cloud SSO". (In addition to the one you already setup for Tableau Cloud)

Name this one after your Curator portal.

For the "Consumer URL", paste in the url to the homepage of Curator. For "Audience", put in the Curator URL without the
trailing /, or http/https.

Go to the "SSO" tab for the settings needed for the Curator Setup.

## Curator Setup

In the /backend settings, go to the Settings->Tableau Server Settings->Authentication area. Select "SAML". For the
Entity ID and IdP ID, put in the "Audience" that you added to OneLogin.

For the SignOn URL, put the "SAML 2.0 Endpoint (HTTP)" URL found in the SSO tab of the App in OneLogin.

For the SignOut URL, put the "SLO Endpoint (HTTP)" URL found in the SSO tab of the App in OneLogin.

Hover over "More Actions" in the OneLogin system. Export the SAML Metadata. Open this file with a text editor and
copy/paste the certificate from the file into the Certificate area of Tableau Server.


# Overview
Source: https://docs.curator.interworks.com/setup/authentication/overview

An overview of the authentication methods available in Curator.

When <Tooltip>integrating your analytics</Tooltip> Curator relies on those source-systems
to authorize users to see and interact with content that is embedded in Curator.  However, in order to utilize those
systems that your content relies on Curator must be set up to authenticate users to the frontend of the site. Curator
can use a variety of methods to authenticate users to the frontend - each method may require additional
setup, so be sure to check out the relevant section for your established security - or reach out to our support team
using the link at the top of the page if you have questions about choosing the right method for your organization.

## Default Authentication

By default, Curator is set up to "Pass Through" authentication to your embedded content, and has no Authentication or
Authorization system in place.

When users encounter embedded content, they will be prompted to log in with their own credentials, and there will be no
menu permissions - so everyone will be able to see everything, but the source-system in question will still restrict
access to content based on the user's permissions in that system.

## Authentication Type Options

If you plan to integrate any <Tooltip>analytic-content</Tooltip> it's wise to get that
connection set up first.  Review the steps for [creating your integration](/creating_integrations/overview) in our
documentation, and then come back here to set up your authentication.

* [SAML](/setup/authentication/okta_saml)
  This allows user accounts to authenticate using your SAML Identity Provider (IdP),
  such as Okta, Microsoft Entra ID (Azure AD), OneLogin, etc.

* **Tableau Server (needs documented)**
  This allows user accounts to authenticate directly with a Tableau Server using their local Tableau Server username and password.

* [Curator Users](/setup/authentication/curator_users)
  This allows users to be created and stored locally on the site. For Tableau Cloud customers you can use Curator as your
  SAML Host (IdP), in which case you would set up your Tableau Cloud site to use Curator as the SAML authenticator.

* [Pass-Through (Security Disabled)](/setup/authentication/pass_through_authentication)
  This turns off authentication to the frontend and makes all links and pages public.  The user is still
  required to authenticate directly to the Tableau Server for any underlying views in a Dashboard which
  requires a login.

* [Active Directory](/setup/authentication/active_directory)
  Users authenticate seamlessly with Microsoft Active Directory - not to be confused with [Microsoft Entra ID (Azure AD)](/setup/authentication/azure_ad_saml)
  which is a cloud-based service.

* **OAuth/OpenID (needs documented)**
  This allows user accounts to authenticate using your OAuth provider.


# Pass-Through Authentication
Source: https://docs.curator.interworks.com/setup/authentication/pass_through_authentication

An overview of the Pass-Through Authentication method in Curator.

"Pass-Through" authentication is the default security setting in Curator. This does not mean it's recommended though -
in fact typically it's *not* recommended as it's the lowest security setting available.  However, it allows you to
quickly get started with Curator and your analytics content, and is a good way to test out the platform before
committing to a more secure or complex authentication method, or it can be useful if you would like to use Curator
in a public-facing manner where you will have almost entirely anonymous users who may or may not have access to
<Tooltip>analytics content</Tooltip>.

## Changing Authentication Settings to Pass-Through

<BackendNavPath />

Select the **Pass-Through (Security Disabled)** option and be sure to save your changes.

<img alt="Authentication settings page with Pass-Through selected" />


# SAML Troubleshooting & Maintenance
Source: https://docs.curator.interworks.com/setup/authentication/saml_troubleshooting

Diagnose broken SAML logins, rotate an expired IdP certificate, enable SAML debug logging, and recover access when SAML locks users out.

This guide is for administrators who already have SAML configured and need to **maintain or repair** it — for
example when logins suddenly stop working or the Identity Provider (IdP) certificate expires. If you are setting
SAML up for the first time, start with the provider-specific guides instead:
[Okta](/setup/authentication/okta_saml), [OneLogin](/setup/authentication/one_login_saml), or
[Microsoft Entra ID (Azure AD)](/setup/authentication/azure_ad_saml). If you are **replacing** an existing IdP with a
new one — for example moving from Okta to Microsoft Entra ID — follow [Switching from Another SAML
Provider](/setup/authentication/azure_ad_saml#switching-from-another-saml-provider-eg-okta) instead. That is a bigger
change than a certificate rotation, because every user must exist in the new IdP before the cutover, and it has its
own checklist.

## Where SAML settings live

All SAML configuration lives on a single backend page:

<BackendNavPath />

Select **SAML** as the **Authentication Type** to reveal the SAML fields. They are grouped into four sections:

* **General** — the **Authentication Type** selector plus the **Download SAML Metadata** and **Import SAML
  Metadata** buttons.
* **SAML General** — the core IdP fields: **Entity ID**, **IdP Entity ID**, **SignOn URL (SSO)**, and **Logout
  URL (SLO)**.
* **SAML Attributes** — custom attributes to retrieve and store as part of each user's profile. Not relevant to the
  troubleshooting scenarios below.
* **SAML Advanced** — everything else, including the **Certificate** field, **Debug Mode**, strict-mode and
  signing toggles, and the Service Provider certificate/key. This section is collapsed by default; click its
  header to expand it.

<Note>
  The Curator **backend** login (at `/backend`) is a separate account system from the frontend SAML login. A
  broken SAML configuration only locks users out of the **frontend** portal — you can still sign in to the
  backend with your Curator backend credentials to reach the settings above and fix the problem.
</Note>

## Common failure symptoms

| Symptom                                                                                               | What it usually means                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Blank gray page / blank box on every page**                                                         | The frontend cannot complete authentication. This commonly indicates an expired or mismatched IdP signing certificate, or a SignOn URL that no longer matches the IdP. Enable [Debug Mode](#enabling-debug-mode) to see the underlying SAML error in the system log.                                                                                                                        |
| **Redirect loop** (the page bounces between Curator and the IdP)                                      | The IdP returns a response Curator rejects — frequently a certificate mismatch, a clock skew between servers, or an **Entity ID** that no longer matches what the IdP is configured to send.                                                                                                                                                                                                |
| **"User not found" or access denied after a successful IdP login**                                    | The IdP authenticated the user, but the username Curator received does not match a Curator/Tableau user. Check the **Strip Domain Prefix** setting and the **Custom User Identifier Field**, and confirm the user exists on the connected platform.                                                                                                                                         |
| **Login worked yesterday, fails today with no config change**                                         | Most often an **expired IdP certificate**. Follow [Updating the IdP certificate](#updating-an-expired-or-changed-idp-certificate).                                                                                                                                                                                                                                                          |
| **Login worked with the old IdP, but breaks right after switching to a new one** (e.g. Okta to Entra) | You replaced the provider rather than updating it in place, so every user must be provisioned again in the new IdP. Most failures trace back to a user missing from the new IdP, or a username claim that does not match the Tableau Server username exactly. See [Switching from Another SAML Provider](/setup/authentication/azure_ad_saml#switching-from-another-saml-provider-eg-okta). |

## Diagnosing a single user after an IdP switch

The guidance above is written for a cutover you have not made yet. Once the cutover is done, you are usually
dealing with a different situation: most users are fine, but one user's dashboard tabs and buttons are missing or
their content is denied.

The usual cause is that the username the new IdP sends for that user no longer matches their existing platform
user. Curator links a Frontend User to a Tableau user by username, so when the format of that username changes,
the Frontend User is left with no platform user behind it. The login itself still succeeds, which is why the
failure looks like missing content rather than a login error.

### Step 1: Find the exact username the IdP sent

Curator resolves the username from the **Custom User Identifier Field** when one is configured, then from a
`username` or `Username` attribute, and finally from the SAML NameID. It then strips the domain prefix if **Strip
Domain Prefix** is enabled and converts the result to lowercase. That final value is the one that must match the
platform user, so guessing at the claim your IdP is configured to send is not enough — read the value Curator
actually resolved.

1. Set **Debug Mode** to **Response User Information** using [Enabling Debug Mode](#enabling-debug-mode).
2. Have the affected user log in again.
3. Read the captured entry:
   <BackendNavPath />
   The entry records the attributes the IdP sent alongside the resolved `username`.
4. Set **Debug Mode** back to **Disabled**.

### Step 2: Check whether the platform user link resolved

<BackendNavPath />

Open the affected user, then click the tab for your platform — **Tableau Users** for a Tableau connection. The
table lists **Tableau User ID**, **Username**, **Full Name**, **Site Role**, **Site**, **Server**, and **Last
Synced**.

* A working link shows a real ID in the **Tableau User ID** column, the expected **Site** and **Site Role**, and a
  recent **Last Synced** timestamp.
* A broken link shows `User not on Site '<site name>'` in the **Tableau User ID** column, meaning Curator found no
  matching user for that username on that site. An empty tab reading **No Tableau users found.** means no platform
  user is associated with the Frontend User at all.

If a **Sync from Tableau** button is available on the tab, click it before drawing a conclusion — that re-queries
the server and rules out a merely stale row.

### Step 3: Reconcile the username formats

Compare the username from Step 1 with the username the user has on the platform. If the two differ only in
**format** — for example the old IdP sent `domain\first.last` and the new one sends `first.last@example.com` —
configure [Username Mapping](/users_groups/user_management/username_mapping) to translate between them. Do this
instead of renaming platform users by hand, so the fix applies to every affected user at once and survives future
logins.

<Note>
  Username Mapping can only change the format of a username, not the username itself. If the new IdP sends a
  genuinely different identifier (for example `flast@example.com` where the platform user is
  `first.last@example.com`), mapping cannot reconcile it. Either have your IdP administrators send the original
  value in the username claim, or point the **Custom User Identifier Field** at an attribute that still carries it.
</Note>

## Updating an expired or changed IdP certificate

When your IdP rotates or renews its signing certificate, the certificate stored in Curator no longer matches and
logins break. There are two ways to update it.

### Option 1: Re-import the IdP metadata (recommended)

1. Download a fresh **Federation Metadata XML** file from your IdP. Each provider exposes this differently — see
   the [Okta](/setup/authentication/okta_saml), [OneLogin](/setup/authentication/one_login_saml), or
   [Azure AD](/setup/authentication/azure_ad_saml) guides for the exact location.
2. <BackendNavPath />
3. With **SAML** selected as the Authentication Type, click **Import SAML Metadata** in the **General** section
   and upload the XML file.
4. Curator re-reads the metadata and updates the **IdP Entity ID**, **SignOn URL (SSO)**, **Logout URL (SLO)**,
   and the **Certificate** field automatically.
5. Save the page and test a login.

<Note>
  Re-importing metadata only updates the fields present in the XML; it does not clear your other SAML settings. If
  the file does not contain a value for a field, that field is left unchanged.
</Note>

### Option 2: Paste the certificate manually

If you only have the new certificate (not a full metadata file):

1. <BackendNavPath />
2. Replace the contents of the **Certificate** field with the new IdP signing certificate.
3. Save the page and test a login.

<Note>
  The **Certificate** field holds the **IdP's** signing certificate. It is distinct from the **Service Provider
  Certificate** and **Service Provider Private Key** fields lower in the SAML Advanced section, which Curator uses
  to sign its *own* requests. See [Signing Login Requests](/setup/authentication/signing_saml_login_requests) for
  those.
</Note>

## Enabling Debug Mode

Curator has a built-in **Debug Mode** that writes detailed SAML output to the system log so you can see exactly
what the IdP is sending.

1. <BackendNavPath />
2. Set **Debug Mode** to one of:
   * **SAML Response** — logs the raw SAML response and prints the parsed attributes to the browser, halting the
     login. Use this for a one-off inspection, not on a live production login flow.
   * **Response Attributes** — logs the attributes Curator parsed from the response.
   * **Response User Information** — logs the resolved username alongside the attributes and API calls.
3. Save the page and reproduce the failed login.
4. Read the captured output in the system log under `storage/logs/` (files are named
   `system-YYYY-MM-DD.log`).
5. **Set Debug Mode back to Disabled when you are finished** — it logs sensitive authentication data and, in the
   **SAML Response** mode, interrupts the login flow.

## Emergency recovery: regaining access when SAML is broken

If a SAML misconfiguration is preventing **all** frontend users from logging in, you can temporarily restore
frontend access while you diagnose the problem. Because the backend login is independent of SAML, you always
retain access to the settings needed to do this.

1. Sign in to the Curator backend at `/backend` with your backend credentials.
2. <BackendNavPath />
3. Change the **Authentication Type** from **SAML** to **Curator Users** and save. Curator now authenticates
   frontend users against locally stored accounts instead of your IdP.
4. Create or use a local frontend user so you and your team can access the portal while SAML is down. See
   [Curator Users](/setup/authentication/curator_users) for managing local accounts.
5. Diagnose and fix the SAML problem — typically by [updating the IdP
   certificate](#updating-an-expired-or-changed-idp-certificate) and using [Debug
   Mode](#enabling-debug-mode) to confirm the response now validates.
6. Once SAML works again, switch the **Authentication Type** back to **SAML** and save.

<Warning>
  Leave the integration on **Curator Users** only for as long as the recovery takes. While it is active, your IdP
  is not enforcing authentication for the Curator frontend.
</Warning>


# Signing Login Requests
Source: https://docs.curator.interworks.com/setup/authentication/signing_saml_login_requests

Optional steps to configure Curator to sign SAML login requests.

This is an optional step in addition to configuring Curator for SAML authentication.  See these links for help
configuring SAML within Curator first:

* [Okta](/setup/authentication/okta_saml)
* [OneLogin](/setup/authentication/one_login_saml)
* [AzureAD](/setup/authentication/azure_ad_saml)

## Configuring Curator to Sign SAML Requests

If your SAML Identity Provider (IdP) requires SAML requests to be signed, you'll need a certificate and private key in
Curator's authentication settings. Curator can automatically generate these for you, or you can provide your own.

### Automatic Certificate Generation (Recommended)

Curator will automatically generate a self-signed certificate and private key when you import your IdP's SAML metadata
for the first time. This certificate is valid for 1 year and uses 4096-bit RSA encryption.

**Steps:**

1. <BackendNavPath />
2. In the **General** section at the top, click **Import SAML Metadata** and upload your IdP's metadata XML file.
3. Curator will automatically generate and populate the **Service Provider Certificate** and **Service Provider Private
   Key** fields in the **SAML Advanced** section.
4. Expand the **SAML Advanced** section and toggle on the **Sign Log In Requests** and **Sign Logout Requests** options.
5. Save the changes.
6. You will likely need to send the certificate file to your SAML IdP administrator.

### Manual Certificate Generation (Optional)

If you prefer to generate certificates manually or need to regenerate them (e.g., for periodic security rotation), you
have two options:

#### Option 1: Use Curator's Regenerate Button

1. <BackendNavPath />
2. Expand the **SAML Advanced** section.
3. Click the **Regenerate Certificate** button.
4. The **Service Provider Certificate** and **Service Provider Private Key** fields will be automatically populated.

#### Option 2: Generate Your Own Certificate

1. Generate a certificate and private key using an external tool (e.g., [SAMLTool.com](https://www.samltool.com/self_signed_certs.php)
   or OpenSSL).
2. Navigate to Curator's **Backend** > **Settings** > **Security** > **Authentication Settings** and expand the
   **SAML Advanced** section.
3. Copy the certificate contents and paste them into the **Service Provider Certificate** field.
4. Copy the private key contents and paste them into the **Service Provider Private Key** field.
5. Save the changes.

### Final Steps

After setting up your certificate (automatically or manually):

1. Toggle on the **Sign Log In Requests** and **Sign Logout Requests** options in the **SAML Advanced** section.
2. Save the changes.
3. Send the certificate file to your SAML IdP administrator.
4. If the **Certificate** field (the field above the **Service Provider Certificate**) is blank, you'll need to get an
   updated metadata file from your IdP administrator and import it using the button in the **General** section at the top
   of the page.


# Windows LDAP
Source: https://docs.curator.interworks.com/setup/authentication/windows_ldap_iis

A guide to setting up Windows LDAP authentication for Curator using IIS.

<Danger>
  Curator no longer supports IIS on new installations.
</Danger>

For current information on how to set up Active Directory on Windows, please see our
[Active Directory](/setup/authentication/active_directory) documentation.

*The information below is only for reference on legacy/existing installations.  It is *highly* recommended that you
reinstall with Apache for stability, please see our
[Windows Apache Installation](/setup/installation/windows_installation)
documentation for steps on how to achieve the best Curator experience for Windows.*

Using IIS, you can use the user's AD credentials automatically.

Enable Windows Authentication in "Add/Remove Windows Features". (Sometimes this is known as Add Roles and Features)
Server Roles > Web Server (IIS) > Web Server > Security > Window Authentication.
*Note: This may be found in the Server Manager, not IIS*

Once this is added, go to your site in IIS, click "Authentication". Change "Windows Authentication" to "Enabled" and
"Anonymous Authentication" to "Disabled".

<img alt="Authentication settings" />

Go to the site in the IIS Manager and open the Configuration Editor

<img alt="Configuration editor" />

Choose "system.webServer/serverRuntime" for the Section selection. Select UseWorkerProcessUser. Click Apply.

<img alt="Configuration editor settings" />

In Curator's Tableau Server Settings, select "Active Directory" as the Authentication Type.

<img alt="Portal settings" />

If you have issues, make sure to disable UAC, to allow access to the filesystem.  You can find this setting under
Control Panel > System and Security > User Account Control Settings.


# Linux Central Dispatch
Source: https://docs.curator.interworks.com/setup/central_dispatch/linux_central_dispatch

Set up distributed processing capabilities with Central Dispatch on Linux systems

1. Install Curator using  [Linux installer](/setup/installation/linux_installation)
   like usual.

2. You *can*  make a new directory called  `centraldispatch`  at  `/var/www`  and move the contents of the webroot
   (`/var/www/html`) there or you can leave it as is. The newly deployed instances will be located at
   `/var/www/instance-name`  while the main Central Dispatch site remains at `/var/www/html` or `/var/www/centraldispatch`.
   The rest of the guide will assume `/var/www/html`  so change all of the commands to the correct path if you chose
   `/var/www/centraldispatch`.

3. Set up SSL for this initial instance. This
   [blog by the great and powerful Orr](https://interworks.com/blog/morr/2019/10/24/portals-for-tableau-101-setting-up-ssltls-certificates-for-https/)
   will get you most of the way there.  NOTE: Ubuntu systems are slightly different.

4. There should already be a default conf file that has an **IncludeOptional** line that points to a directory where
   additional vhost conf files can go. Make sure you know where the newly added vhost conf files should go:
   * Ubuntu:
     * Default conf:  `etc/apache2/apache2.conf`
     * Includes vhost conf files:  `etc/apache2/sites-enabled/*.conf`
     * Ubuntu is a little different and actually stages the conf files here before being enabled:  `/etc/apache2/sites-available/*.conf`
   * Everything else:
     * Default conf:  `/etc/httpd/conf/httpd.conf`
     * Includes vhost conf files:  `/etc/httpd/conf.d/*.conf`

5. Create database user using the `worker_database_user.sql` example script at
   `/var/www/html/plugins/interworks/centraldispatch/workers` directory. Tweak the password if you'd like before executing.
   * Run the sql file:

     ```bash theme={null}
     mysql -u root -p curator < worker_database_user.sql
     ```

   * Enter root password

   * Test if the new user is there:  **mysql -u worker -p**

   * Enter worker password

6. Create directory  `/var/www/archives`

7. Set up worker script
   1. Copy php\_worker.example.php script to php\_worker.php in the `/var/www/html/plugins/interworks/centraldispatch/workers`
      directory:

      ```bash theme={null}
      sudo cp php_worker.example.php php_worker.php
      ```

   2. Copy `vhost.template.example.conf` to `vhost.template.conf` in the same directory.

      ```bash theme={null}
      sudo cp vhost.template.example.conf vhost.template.conf
      ```

   3. Make sure apache user owns everything:

      ```bash theme={null}
      sudo chown -R $APACHEUSER:$APACHEUSER /var/www
      ```

   4. Tweak paths as needed in  `php_worker.php`
      1. DB\_ENV\_DISPATCHER uses details from step 5 above.
      2. DB\_ENV\_INSTANCE uses the root database details to be able to provision users as needed. Can set up dispatcher
         user with these permissions if you don’t want to use the root account.
      3. Modify vhost section:
         1. Uncomment `directory` and modify as needed to where the vhost conf files should go from step 4.
         2. Uncomment `template` for `/var/www/html/plugins/interworks/centraldispatch/workers/vhost.template.conf`.
      4. Modify worker section:
         1. Uncomment `source_directory` for `/var/www/html`.
         2. Uncomment `archive_directory` for `/var/www/archives`.
      5. Modify \$DEFAULT\_BACKEND\_EMAIL as needed.
      6. Modify \$LINUX\_APACHE\_RESTART to the relevant apache restart command for your distro.
      7. Modify \$LINUX\_APACHE\_USER to the relevant apache user for your distro.

   5. Tweak vhost template as needed in workers directory
      1. Comment out the #apache 2.2 lines (lines 22-23) and uncomment out the #apache 2.4 lines unless using Apache 2.2.
      2. Update SSLCertificateChainFile, SSLCertificateFile, and SSLCertificateKeyFile as needed.

   6. Schedule root to run worker with the following command. Feel free to change the frequency (this one is every 15
      minutes). Also, make sure to change  `$APACHEUSER`  to the relevant apache user in the chown command (this makes
      sure the application owns all the files even though root is making everything).

      ```bash theme={null}
      (sudo crontab -l ; echo "*****/15 * * * * sudo php
      /var/www/html/plugins/interworks/centraldispatch/workers/php_worker.php >> /dev/null 2>&1 && sudo chown -R $APACHEUSER:$APACHEUSER /var/www****") | sudo crontab -
      ```

8. Restart apache

9. In the Central Dispatch Curator portal’s backend, register the workers with the dispatcher at **Backend** >
   **Settings** > **Central Dispatch** > **Central Dispatch Settings**. Probably with these settings:
   1. Host URL: localhost
   2. Worker name: localhost (or use something more descriptive)
   3. Install Path:  `/var/www`

10. Attempt to deploy a new managed instance at Backend > Central Dispatch > Managed Instances.

## Configuring Managed Instances After Deployment

Each managed instance is a full, standalone Curator install with its own web root, its own database, and
its own settings. Integrations such as Tableau are configured **on the instance itself**, not on the Central
Dispatch controller. To configure an instance, browse to that instance's own backend URL — for example
`https://instance-name.example.com/backend` — and set up its Tableau connection there.

<Note>
  Managed instances do not share settings. Because every instance has its own isolated database, the Tableau
  connection credentials you configure on one instance have no effect on any other instance. Always confirm
  the URL in your browser's address bar before saving so you know which instance you are editing.
</Note>

When deploying several instances in quick succession, follow this workflow to avoid configuring the wrong
instance:

1. Wait for the worker to finish provisioning before configuring an instance. In the Managed Instances list,
   an instance that is still provisioning shows a pending **Status** such as `pending deployment`; once the
   worker completes, the **Status** column reflects the live instance instead. The worker runs on the
   schedule you set in step 7 (every 15 minutes in the example cron), so a newly requested instance may not
   be ready immediately.
2. Open each instance's backend URL in its own browser tab, and check the address bar before saving, so you
   can be certain which instance you are configuring.
3. After saving an instance's Tableau settings, return to Backend > Central Dispatch > Managed Instances. The
   list includes a **Tableau Server** column that reports the Tableau server URL each instance is connected
   to, letting you confirm from the controller that every instance has the settings you expect.

## Manual Back Out of Deployment

In case of a failure during a deployment, Central Dispatch is not yet able to automatically back out the deployment to
try again. You can determine the nature of the failure by visiting the Managed Instance record in the backend of the
Central Dispatch portal and scrolling to the bottom of the page. There will be an error field that will show any issues
the worker had during the deployment.

To back out a deployment, it's important to determine which step it failed at so you'll know which of the following
steps you'll need to take to back it out. They are in reverse order of the deployment, so you can skip steps if the
deployment didn't make it that far. When in doubt, just perform all of the steps.

1. Remove cron job with the name of this managed instance by using `sudo -u <apache user> crontab -e` to edit.
   *Note: This will use VI as the default editor in case you need to look up how to edit the file.*

2. If using Ubuntu, disable the vhost entry by running `sudo a2dissite <managed instance vhost record without .conf>`

3. Remove the vhost record specific to this managed instance in the vhosts directory (see step 4 above to determine
   location). The command will be similar to `sudo rm /etc/apache2/sites-available/<managed instance vhost record>`

4. Remove site-specific SSL/TLS certificate, key, and (optional) chain certificate, if the managed instance supplied
   them. These should be in the /etc/apache2/certs/ directory. The commands will be similar to these two commands below:

   ```bash theme={null}
   sudo rm /etc/apache2/certs/<name of manage instance crt file>
   ```

   ```bash theme={null}
   sudo rm /etc/apache2/certs/<name of managed instance key file>
   ```

5. Remove the portal code for the managed instance in the /var/www/ directory. The command will be similar to
   `sudo rm -Rf /var/www/<managed instance web root directory name>`

6. Drop the database specific to the managed instance by using `mysql -u root -p` and the root database credentials
   (see `/var/www/info.txt`). The SQL statement to drop the database would be: `DROP DATABASE '<database name>';`

7. Delete the database user specific to the managed instance by using `mysql -u root -p` and the root database
   credentials (see `/var/www/info.txt`). The SQL statement to drop the database would be:

   ```SQL theme={null}
   DROP USER IF EXISTS '<username>'@'localhost';
   ```


# Windows Central Dispatch
Source: https://docs.curator.interworks.com/setup/central_dispatch/windows_central_dispatch

Configure distributed processing with Central Dispatch on Windows systems

Each section below has steps you can follow, all steps must be followed to set up Central Dispatch accordingly.

## 1. Curator install and folder Creation

1. Install Curator using Apache installer like usual.
2. Ensure the following folders exist, and if not, use a Windows Explorer window to create them
   * `C:\InterWorks\Curator\vhosts`
   * `C:\InterWorks\Curator\archives`

## 2. `curator.conf` file adjustments

1. Move Central Dispatch portal to subfolder of htdocs
   1. Make directory `C:\InterWorks\Curator\htdocs\centraldispatch`
   2. Move all other files and folders in `htdocs` directory to `centraldispatch` directory using Windows Explorer
2. Save SSL/TLS certificates and key files to `C:\InterWorks\Curator\certs` directory (create if it doesn’t exist)
3. Update `curator.conf` Located in `C:\InterWorks\Curator`
   1. Point the default virtualhost’s document root and directory to `C:\InterWorks\Curator\htdocs\centraldispatch`
   2. Use wildcard subdomain for servername and/or serveralias (do not use \* in the path)
   3. Add include statement at the bottom to look for configuration files in `C:\InterWorks\Curator\vhosts` directory:
      1. IncludeOptional `C:\InterWorks\Curator\vhosts\`
   4. Configure it to listen on 443 and point at the certs and key in the certs directory by uncommenting the lines at
      the bottom section.
   5. Add these 2 lines to the 443 VirtualHost (usually under the DocumentRoot)
      1. ErrorLog `${APACHE_LOG_DIR}/centraldispatch_error.log`
      2. CustomLog `${APACHE_LOG_DIR}/centraldispatch_access.log` combined
4. Update the existing Curator cron scheduled task to fix the path to the (now) Central Dispatch portal (i.e.
   `C:\InterWorks\Curator\htdocs\centraldispatch\artisan`).
5. Restart apache using the shortcuts on the desktop. If you receive an error message about access, then right click on
   the `stop.bat` and `start.bat` scripts within `C:\InterWorks\Curator` and run as administrator.  Ensure the portal still
   works as expected.

## 3. Create the Worker Database User

1. Open the `worker_database_user.sql` example script in a text-editor, located in the
   `C:\InterWorks\Curator\htdocs\centraldispatch\plugins\interworks\centraldispatch\workers` directory.

2. Change the username and password as needed before executing.

3. Open a terminal and run the command below to create the new user

   ```bash theme={null}
   mysql -u root -p -e "source C:\InterWorks\Curator\htdocs\centraldispatch\plugins\interworks\centraldispatch\workers\worker_database_user.sql"
   ```

4. NOTE: You will be prompted to enter a password. Use the root user's password that was created when you installed
   Curator. Refer to the [Windows Installation here](/setup/installation/windows_installation).

## 4. Create script and vhost files

1. Navigate to the `C:\InterWorks\Curator\htdocs\centraldispatch\plugins\interworks\centraldispatch\workers` directory
2. Create a copy of `php_worker.example.php`, rename it to `php_worker.php`, and move it to `C:\InterWorks\Curator`.
3. Create a copy of `vhost.template.example.conf`, rename it to `vhost.template.conf`, and move it to
   `C:\InterWorks\Curator`.
4. You will have created the following files
   * `C:\InterWorks\Curator\php_worker.php`
   * `C:\InterWorks\Curator\vhost.template.conf`

## 5. Worker Script Setup

NOTE: Within PHP, use forward slashes, not backslashes for directory separators.  Outside of PHP, use backslashes.

1. Open `php_worker.php` in a text editor
2. Modify the user section:
   1. For the `DB_ENV_DISPATCHER` set the `user` and `pass` values to the user and password you set using the script in
      the **Create the Worker Database User** section above.
   2. `DB_ENV_INSTANCE` uses the `root` user's details for simplicity. This ensures you can provision with the highest
      access. Alternatively, if you do not want to use the `root` user for this create a separate user and use those details.
3. Modify vhost section:
   1. Uncomment `directory` for "C:/InterWorks/Curator/vhosts" (update path as needed).
   2. Uncomment `template` for `C:/InterWorks/Curator/vhost.template.conf` (update path as needed).
4. Modify worker section:
   1. Uncomment `source_directory` for "C:/InterWorks/Curator/htdocs/centraldispatch" (update path as needed).
   2. Uncomment `archive_directory` for "C:/InterWorks/Curator/archives" (update path as needed).
      1. Modify `$DEFAULT_BACKEND_EMAIL` as needed
      2. Modify `$WINDOWS_INSTALL_DIR` if not using C:/InterWorks/Curator (i.e. if installed to D:\InterWorks\Curator)

## 6. vhost Template Setup

1. Determine the Apache version you're using by running `C:\InterWorks\Curator\libs\Apache24\bin\httpd -v` in a Command
   Prompt window
2. Open `C:\InterWorks\Curator\vhost.template.conf` in a text editor
   1. If using Apache 2.2:
      1. Ensure lines 22-23 **do not** start with a '#', enabling those lines.
      2. Ensure line 25 starts with a '#', disabling that line.
   2. If using Apache 2.4:
      1. Ensure line 25 **does not** start with a '#', enabling that line.
      2. Ensure lines 22-23 start with a '#', disabling those lines.
3. Schedule worker by running the command in the `worker_scheduled_task.bat` example script. Tweak as needed. It
   defaults to 15 minutes.

## 7. Register and Test Dispatcher

1. In the Central Dispatch Curator portal’s backend, register the workers with the dispatcher at **Backend** >
   **Settings** > **Central Dispatch** > **Central Dispatch Settings**. Probably with these settings:
   1. Host URL: localhost
   2. Worker name: localhost (or use something more descriptive)
   3. Install Path: C:/InterWorks/Curator/htdocs/
2. Attempt to deploy a new managed instance at Backend > Central Dispatch > Managed Instances.

## Manual Back Out of Deployment

In case of a failure during a deployment, Central Dispatch is not yet able to automatically back out the deployment to
try again. You can determine the nature of the failure by visiting the Managed Instance record in the backend of the
Central Dispatch portal and scrolling to the bottom of the page. There will be an error field that will show any issues
the worker had during the deployment.

To back out a deployment, it's important to determine which step it failed at so you'll know which of the following steps
you'll need to take to back it out. They are in reverse order of the deployment, so you can skip steps if the deployment
didn't make it that far. When in doubt, just perform all of the steps.

1. Remove scheduled task with the name of this managed instance by opening the Windows Task Scheduler.

2. Remove the vhost record specific to this managed instance in the `C:\InterWorks\Curator\vhosts directory` (adjust drive
   letter as needed).

3. Remove site-specific SSL/TLS keys if the managed instance supplied them. These will be in the
   `C:\InterWorks\Curator\certs directory` (adjust drive letter as needed).

4. Remove the portal code for the managed instance in the `C:\InterWorks\Curator\htdocs directory` (adjust drive letter
   as needed).

5. Drop the database specific to the managed instance by using HeidiSQL and the root database credentials
   (see `C:\InterWorks\Curator\info.txt`). The SQL statement to drop the database would be:

   ```SQL theme={null}
   DROP DATABASE '<database name>';
   ```

6. Delete the database user specific to the managed instance by using HeidiSQL and the root database credentials
   (see `C:\InterWorks\Curator\info.txt`). The SQL statement to drop the database would be:

   ```SQL theme={null}
   DROP USER IF EXISTS '<username>'@'localhost';;
   ```


# Email Configuration
Source: https://docs.curator.interworks.com/setup/email/email_configuration

Configure SMTP and email settings for Curator features including Report Builder and notification systems.

There are a variety of places that use e-mail settings across Curator.  The largest piece is the
[Report Builder](/embedding_using_analytics/report_builder/overview_and_enabling_report_builder),
and e-mail also delivers notifications, including:

* [System Notifications](/site_administration/admin_email_notifications/system_notifications):
  You can have Curator e-mail a digest of the issues and suggestions it raises about your instance.  Subscribed
  backend administrators receive it, plus any addresses you add.

* [Data Manager Notifications](/site_administration/admin_email_notifications/data_manager_notifications):
  You can have Curator e-mail the recipients you choose when someone submits a Data Manager form.

Whatever the case, the e-mail setup will reside almost entirely with your e-mail provider or IT group that manages your
mail server.  Once you have confirmed with them that you'll be able to utilize their mail service, use the steps below
to fill out the details for your e-mail configuration on Curator.

## Enabling and Testing Mail Settings

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Mail** > **Mail Configuration** section from the left-hand menu (see "Mail
   Configuration Permissions" below if you do not see this menu item).
3. Fill out the form using the details provided from your mail administrator.
4. Save the form.
5. Ensure the details are accurate by clicking the "Test Saved Settings" and entering your email.
6. Once you click send, wait up to 5 minutes (and double-check your spam inbox) - if you have not received an e-mail
   double-check the settings with your mail administrator to ensure everything is set up properly

## Mail Configuration Permissions

Access to Mail configuration may not be granted by default depending on your installation.  In order to view the mail
configuration, ensure that your
[Backend User](/site_administration/backend_administrators/overview) has access.


# High Availability
Source: https://docs.curator.interworks.com/setup/high_availability/high_availability

Configure Curator for high availability infrastructure to ensure reliability and handle increased load

Curator can be configured to run in a high availability (HA) infrastructure to ensure better "up time" for your users
as well as handling more concurrent user load.  The standard components of the HA infrastructure are:

* **Load balancer** - Domain name is pointed here.  Routes user traffic to one of the application nodes.
  Example: AWS Elastic Load Balancer (ELB).
* **Application nodes** (2 or more) - Where Curator is installed.
  Example: AWS Elastic Compute Cloud (EC2).
* **Database** - The application nodes will use this to store data.  Having a single database keeps things synchronized.
  Example: AWS Relational Database Service (RDS).
* **Filesystem** - The application nodes will use this to store thumbnails, backups, etc.
  Example: AWS Elastic File System (EFS).
  <img alt="HA diagram" />
  *Note: the example above shows AWS services but Azure and other cloud providers are viable options.*

## Requirements

Below are the specific requirements for each component of the infrastructure and what needs to be completed prior to the
install.

* **Load Balancer**
  * This is where SSL will need to be handled.  The most common setup is to terminate SSL at the load balancer as
    opposed to having certificates on each application node.
  * **Prior to install:**  You don't need to have the load balancer ready prior to the install.  This can be configured afterwards.
* **Application nodes**
  * The same server requirements for the standard Curator installation exist for each application node.  Those
    requirements can be found here: [https://curator.interworks.com/requirements](https://curator.interworks.com/requirements).
  * **Prior to install:**  The application nodes need to be spun up and have root SSH or admin RDP access.  The SSH or
    RDP access should be tested before the installation.
* **Database**
  * The database should be *separate* from the application nodes.  Although it can be configured inside one of the
    application nodes it defeats the purpose of high availability because if that node goes down none of the others will
    be functional.
  * **Prior to install:**  The database needs to be spun up, an empty database needs to be created (it can be called
    `curator` for simplicity), and it needs to be accessible from each application node.  Test the accessibility from each
    application node with something like this:

    ```bash theme={null}
    sudo mysql -u $DBUSER--password=$DBPASSWORD -h $DBHOST -e "SHOW DATABASES"
    ```

    Replace variables with your credentials and database host.  You should be able to see the empty database you created
    in the output.
* **Filesystem**
  * Like the database, the filesystem needs to be separate from the application nodes to prevent unnecessary downtime.
    Cloud services (AWS, Azure, etc.) have great options for this that have built in redundancy.  If you aren't using a
    cloud service and are using Windows for the infrastructure you can use the database node for the shared filesystem
    with a network drive.
  * **Prior to install:**  The filesystem needs to be spun up and accessible by each application node.  This should be
    tested by creating a simple text file and ensuring it's visible from each application node.

## Other Infrastructures

There are numerous ways to do high availability that include different patterns with the database and filesystem setups.
What's described above is certainly not the only method but it is the simplest for Curator.  We're happy to help
troubleshoot if you take a different route or run into issues with the infrastructure detailed above.  While we're
fully responsible for errors rising from the application code, the success of the infrastructure will be dependent on
your team that manages it.

## Post Install

Once the install and configuration is complete at the server-level make sure to go to the **Curator backend** >
**Settings** > **Curator** > **Worker Nodes** and add each application node to the list.  This will ensure when a
software upgrade is initiated or the application cache is cleared each node will stay synchronized.

### Worker Nodes

Worker nodes are essential for maintaining high availability and load balancing. In Curator's architecture, each worker
node runs a complete, independent installation of Curator that points to the same shared database and filesystem. This
is a **peer-to-peer architecture** where all nodes are equal - there is no master node.

<Warning>
  You must register ALL application nodes in the Worker Nodes list, including the node you're currently
  working on. Do not leave any node out thinking it will act as a "master." Each node shares the load of incoming
  requests, and if one node fails, others can continue to handle traffic, minimizing downtime and improving reliability.
</Warning>

#### Adding Worker Nodes (Command Line)

To register a worker node to your Curator cluster, you can use the  `distributed:addnode`  console command. This command
registers a new node with the cluster, allowing Curator to properly sync changes with it.

* **Open the terminal**  and navigate to the directory where Curator is installed.

* **Run the command**  with the IP address of the new node:

  ```bash theme={null}
      php artisan distributed:addnode {Curator Node IP}
  ```

  Replace  `{Curator Node IP}`  with the actual IP address of the node you want to register.

* **Verify the node addition**: The command will output a confirmation message indicating that the node has been
  registered successfully, and you can find the newly added node in the **Curator backend** >**Settings** > **Curator** >
  **Worker Nodes**.

**Example:**

```bash theme={null}
php artisan distributed:addnode "http://192.168.1.2"
```

This command will register the node with IP address  `192.168.1.2`  to the Curator cluster.

#### Adding Worker Nodes (In the Backend)

You can also register worker nodes directly through the Curator backend interface.

1. **Navigate** to the Curator backend > Settings > Curator > Worker Nodes.
2. **Add a new node**  by entering the URL (e.g.,  `http://192.168.1.2`) in the **URL** field.
3. **Save the changes**  to register the new node with the cluster.


# IIS Installation (Unavailable)
Source: https://docs.curator.interworks.com/setup/installation/iis_installation

Information about IIS installation support status and migration recommendations for Curator.

**Curator no longer supports new installations on IIS.**

Instead, download the installer for [Windows](/setup/installation/windows_installation)

NOTE: *If you already have IIS installed, Curator's support team will continue to support your instance, but any new
installations will require our Apache installation.  It is highly recommended that you migrate to Apache for increased
stability.*


# Linux Installation
Source: https://docs.curator.interworks.com/setup/installation/linux_installation

Instructions for installing Curator on Linux.

The automated installer covers the vast majority of setups, but each server is different and may require
commands specific to your IT infrastructure.

## Installation Steps

If you are using one of the following Linux Operating Systems, follow our simple instruction steps to get started:

* Ubuntu
* CentOS
* RHEL
* Oracle Linux

<Steps>
  <Step title="Run the Installation Script">
    SSH into your web server, ensure you're using a user that has full sudo access, and run the command below:

    ```bash theme={null}
    curl -s -o curator.sh https://api.curator.interworks.com/scripts/linux_install.sh && chmod +x ./curator.sh && ./curator.sh
    ```
  </Step>

  <Step title="Retrieve Your Credentials">
    Locate your license key (sent from InterWorks) and open `/var/www/curator_info.txt` to retrieve your default
    administrator credentials.
  </Step>

  <Step title="Open the Installer">
    Open `http://curatorexample.com/install.php` in a browser - replacing `curatorexample.com` with your site's URL. If
    you're on the server you installed, you may also use `localhost`.

    *This may be an IP address or computer name until your IT team sets up DNS.*
  </Step>

  <Step title="Credentials">
    The installer will generate credentials for use during installation and will store them in a file in the installation
    directory (Default: `/var/www/curator_info.txt` or `C:\InterWorks\Curator\curator_info.txt` in Windows). You will need
    these credentials to complete the installation and to log in to the Curator backend after installation.
  </Step>

  <Step title="License Key">
    Enter your license key when prompted. If you do not have a license key, please contact InterWorks to obtain one.

    <img alt="License key prompt page" />
  </Step>

  <Step title="Database Connection">
    You may be prompted to enter your database connection information if the installer is unable to automatically find the
    database for you.

    <img alt="Database credentials prompt page" />
  </Step>

  <Step title="Success">
    If the installation is successful, you will be redirected to your new Curator homepage

    <img alt="Database credentials prompt page" />

    Using the same auto-generated credentials created in the install script above, you can log into the Curator backend which
    can be accessed from `http://curatorexample.com/backend`. If you're on the server you installed, you may also use localhost.
    Keep in mind this may be an IP address or computer name until your IT team sets up DNS.
  </Step>
</Steps>

## Custom Setup

The install script can take optional parameters to specify values for the installation script. This can be helpful in
distributed setups, or scripted installations.

```bash theme={null}
curl -o curator.sh https://api.curator.interworks.com/scripts/linux_install.sh
chmod +x ./curator.sh
./curator.sh -f -h [database_host] -u [database_username] -p [database_password] -P [database_port] -d [database_name] -l [license_key] -s [persistent_storage_location] -v [curator_version]
```

Arguments:

* `-h` The database hostname *Needed when using an external database host*
* `-u` The database username  *`Default: curator`*
* `-p` The database password *Default: auto-generated password.  Use this when you need to use a connection to a
  database for a user that has already been created with a specific password.*
* `-P` The database port *`Default: 3306`*
* `-d` The database name *`Default: curator`*
* `-l` The License Key for your Curator installation. When performing a full installation, this is required.
* `-s` Path to a persistent storage location *Container-based or distributed installations typically require this.*
* `-v` Sets the version of Curator to install. *Default: most recent version.*

Options:

* `-f` Full Installation, this flag is required in most custom setups to avoid the in-browser installer.

## Key File Locations

These are the default paths for a standard Curator Linux installation. Exact locations may vary based
on your distribution and web server configuration.

<Note>
  To confirm the exact `php.ini` path on your system, check the `php_ini_path` field returned by the
  [/portal/info](/curator_api/api_docs/curator_api#portalinfo) endpoint.
</Note>

### Ubuntu 22.04 / 24.04

* Webroot: `/var/www/html`
* Environment file: `/var/www/html/.env`
* PHP.ini (Apache): `/etc/php/8.3/apache2/php.ini`
* PHP.ini (FPM): `/etc/php/8.3/fpm/php.ini`

### RHEL 9 / CentOS 9 / Oracle Linux 9+

* Webroot: `/var/www/html`
* Environment file: `/var/www/html/.env`
* PHP.ini: `/etc/opt/remi/php83/php.ini`

## Environment Configuration

Optional settings can be added to the environment file (`/var/www/html/.env`) to override Curator's
defaults. Curator ships with sensible values for all of these, so only set them if you need to change
the default behavior. Restart Apache or PHP-FPM after editing the file.

| Variable               | Default                 | Purpose                                                                                                                 |
| ---------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `SESSION_LIFETIME`     | `360`                   | How many minutes a session may stay idle before the user is signed out.                                                 |
| `CACHE_PREFIX`         | Derived from `APP_NAME` | The prefix applied to all cache keys.                                                                                   |
| `FILESYSTEM_DRIVER`    | `local`                 | The disk used for Curator media and uploads.                                                                            |
| `FILESYSTEM_DISK`      | `local`                 | The application-wide default disk used for everything else.                                                             |
| `APP_DEBUG`            | `false`                 | Whether detailed error pages are shown when an error occurs.                                                            |
| `DISABLE_CORE_UPDATES` | `false`                 | Prevents the update gateway from re-downloading core files, for installs where updates are managed via composer or git. |

<Note>
  `FILESYSTEM_DRIVER` and `FILESYSTEM_DISK` are two separate settings, not old and new names for the same
  thing. Curator media and uploads always follow `FILESYSTEM_DRIVER`. If you have only ever set
  `FILESYSTEM_DRIVER`, your media and uploads continue to work unchanged and no action is required.
</Note>

<Note>
  `CACHE_PREFIX` is derived from your `APP_NAME` unless you set it explicitly. Changing either value
  changes the cache keys, so Curator rebuilds its cache on the next page load. This is safe, but the first
  load afterward may be slower than usual.
</Note>

<Note>
  `APP_DEBUG` defaults to `false`, so a generic error page is shown when something goes wrong. Set
  `APP_DEBUG=true` temporarily while troubleshooting an installation to see the detailed error page with a
  full stack trace, then set it back to `false` (or remove it) once you're done -- leaving it enabled can
  expose sensitive information about your application and infrastructure to untrusted users.
</Note>

## Log Locations

* Application Log: `/var/www/html/storage/logs/system-YYYY-MM-DD.log`
* PHP Installer Log: `/var/www/html/assets/install.log`
* Shell Installer Log: `~/iw_install.log`

## AWS EC2 Process

AWS provides a helpful outline on [how to connect to an AWS EC2 instance from Windows using Putty](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html).

## Network Whitelist Requirements

For installations in environments with restricted internet access or firewall configurations, the following URLs
should be whitelisted to ensure proper functionality:

### RHEL/CentOS/Oracle Linux Systems

* InterWorks API
  * `api.curator.interworks.com`
* EPEL Repository
  * `dl.fedoraproject.org`
  * `download.fedoraproject.org` (covers mirrors.fedoraproject.org)
* Remi Repository (PHP packages)
  * `*.remirepo.net` (covers rpms.remirepo.net, repo.remirepo.net, mirrors.remirepo.net)
* Base RHEL/CentOS Repositories
  * `*.centos.org` (covers vault.centos.org, mirror.centos.org)
  * `download.redhat.com`
  * `cdn.redhat.com`
* Oracle Linux Repositories (Oracle Linux only)
  * `yum.oracle.com`
  * `oss.oracle.com`
* CDN Networks
  * `*.akamaiedge.net` (covers `*.akamaitechnologies.com` - same Akamai network)

### Ubuntu Systems

* InterWorks API
  * `api.curator.interworks.com`
* Ubuntu Repositories
  * `*.archive.ubuntu.com` (covers archive.ubuntu.com, us.archive.ubuntu.com, gb.archive.ubuntu.com, etc.)
  * `security.ubuntu.com`
  * `ports.ubuntu.com`
  * `changelogs.ubuntu.com`
* Launchpad PPAs (for ondrej/apache2 and ondrej/php)
  * `*.launchpad.net` (covers ppa.launchpad.net, launchpad.net)
  * `ppa.launchpadcontent.net`
  * `keyserver.ubuntu.com`

### Testing Connectivity

To confirm `api.curator.interworks.com` is reachable through your firewall or proxy before installing or
upgrading, request the same endpoint Curator itself uses to check for new versions:

```bash theme={null}
curl -sS -w '\nHTTP status: %{http_code}\n' https://api.curator.interworks.com/widget/latest
```

A successful response returns an HTTP status of `200` with a body similar to:

```text theme={null}
$('#iw_latest_widget_wrapper').html('<div class="iw-latest-container">    <span>2026.08-03</span></div>');
```

The version shown in the response is the latest Curator build available, so it will differ from the example
above as new builds are released.

<Note>
  If the request times out, fails a TLS handshake, or returns anything other than a `200` status, the
  whitelist entry is not taking effect yet -- recheck your proxy and firewall rules before continuing with
  installation or upgrades.
</Note>


# Windows Installation
Source: https://docs.curator.interworks.com/setup/installation/windows_installation

Instructions for installing Curator on Windows.

## Installation Steps

<Steps>
  <Step title="Download the Installer">
    Log in to the server where you'd like to install Curator and [download the Curator installer for Windows](https://api.curator.interworks.com/CuratorSetup.exe).
  </Step>

  <Step title="Run the Installer">
    Locate your download and right-click the file, then select "Run as Administrator" to begin the installation process.

    <img alt="Run .exe as admin" />

    Click the "Install" button to run initial installation process:

    <img alt="Installer view" />

    Click "Options" to change the installation directory.
  </Step>

  <Step title="Credentials">
    The installer will generate credentials for use during installation and will store them in a file in the installation
    directory (Default: `/var/www/curator_info.txt` or `C:\InterWorks\Curator\curator_info.txt` in Windows). You will need
    these credentials to complete the installation and to log in to the Curator backend after installation.
  </Step>

  <Step title="License Key">
    Enter your license key when prompted. If you do not have a license key, please contact InterWorks to obtain one.

    <img alt="License key prompt page" />
  </Step>

  <Step title="Database Connection">
    You may be prompted to enter your database connection information if the installer is unable to automatically find the
    database for you.

    <img alt="Database credentials prompt page" />
  </Step>

  <Step title="Success">
    If the installation is successful, you will be redirected to your new Curator homepage

    <img alt="Database credentials prompt page" />

    Using the same auto-generated credentials created in the install script above, you can log into the Curator backend which
    can be accessed from `http://curatorexample.com/backend`. If you're on the server you installed, you may also use localhost.
    Keep in mind this may be an IP address or computer name until your IT team sets up DNS.
  </Step>
</Steps>

## Log Locations

These paths are dependant on your installation location, but these are the default paths:

* Apache: `C:\InterWorks\Curator\httpd_errors.log`
* PHP: `C:\InterWorks\Curator\php_errors.log`
* Installation Log (EXE): `C:\InterWorks\Curator\install.log`
* Installation Log (PHP Installer): `C:\InterWorks\curator\htdocs\assets\install.log`

## Network Whitelist Requirements

If you are installing Curator in a restricted network environment, the only external URL that must
be reachable from the Curator server is:

* `https://api.curator.interworks.com`

This single host covers all outbound traffic Curator needs for installation and ongoing operation on
Windows:

* Downloading the installer (`CuratorSetup.exe`)
* Checking for new versions and downloading upgrade packages
* Validating your Curator license key

Unlike the Linux installer, the Windows installer bundles all required dependencies (Apache, PHP, and
MariaDB), so no package repository URLs need to be whitelisted.

### Testing Connectivity

To confirm `api.curator.interworks.com` is reachable through your firewall or proxy before installing or
upgrading, request the same endpoint Curator itself uses to check for new versions:

```powershell theme={null}
Invoke-WebRequest -Uri "https://api.curator.interworks.com/widget/latest" -UseBasicParsing
```

A successful response returns a `StatusCode` of `200` with `Content` similar to:

```text theme={null}
$('#iw_latest_widget_wrapper').html('<div class="iw-latest-container">    <span>2026.08-03</span></div>');
```

The version shown in the response is the latest Curator build available, so it will differ from the example
above as new builds are released.

<Note>
  If the request times out, fails a TLS handshake, or returns anything other than a `200` status, the
  whitelist entry is not taking effect yet -- recheck your proxy and firewall rules before continuing with
  installation or upgrades.
</Note>

## Other Information

These paths are dependant on your installation location, but these are the default paths:

<Note>
  If Curator was installed on a different drive (e.g., `D:\`), all paths below will reflect that drive
  instead. To confirm the exact `php.ini` path on your system, check the `php_ini_path` field returned
  by the [/portal/info](/curator_api/api_docs/curator_api#portalinfo) endpoint.
</Note>

* Webroot: `C:\InterWorks\Curator\htdocs`
* Environment file: `C:\InterWorks\Curator\htdocs\.env`
* HTTPD Config: `C:\InterWorks\Curator\web.conf`
* PHP.ini: `C:\InterWorks\Curator\php.ini`
* Start Process: `C:\InterWorks\Curator\start.bat` (Also desktop shortcut)
* Stop Process: `C:\InterWorks\Curator\stop.bat` (Also desktop shortcut)
* Apache Location: `C:\InterWorks\Curator\libs\Apache24`
* Database Location: `C:\InterWorks\Curator\libs\MariaDB`
* PHP Location: `C:\InterWorks\Curator\libs\PHP`

## Environment Configuration

Optional settings can be added to the environment file (`C:\InterWorks\Curator\htdocs\.env`) to override
Curator's defaults. Curator ships with sensible values for all of these, so only set them if you need to
change the default behavior. Restart Curator using `stop.bat` and `start.bat` after editing the file.

| Variable               | Default                 | Purpose                                                                                                                 |
| ---------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `SESSION_LIFETIME`     | `360`                   | How many minutes a session may stay idle before the user is signed out.                                                 |
| `CACHE_PREFIX`         | Derived from `APP_NAME` | The prefix applied to all cache keys.                                                                                   |
| `FILESYSTEM_DRIVER`    | `local`                 | The disk used for Curator media and uploads.                                                                            |
| `FILESYSTEM_DISK`      | `local`                 | The application-wide default disk used for everything else.                                                             |
| `APP_DEBUG`            | `false`                 | Whether detailed error pages are shown when an error occurs.                                                            |
| `DISABLE_CORE_UPDATES` | `false`                 | Prevents the update gateway from re-downloading core files, for installs where updates are managed via composer or git. |

<Note>
  `FILESYSTEM_DRIVER` and `FILESYSTEM_DISK` are two separate settings, not old and new names for the same
  thing. Curator media and uploads always follow `FILESYSTEM_DRIVER`. If you have only ever set
  `FILESYSTEM_DRIVER`, your media and uploads continue to work unchanged and no action is required.
</Note>

<Note>
  `CACHE_PREFIX` is derived from your `APP_NAME` unless you set it explicitly. Changing either value
  changes the cache keys, so Curator rebuilds its cache on the next page load. This is safe, but the first
  load afterward may be slower than usual.
</Note>

<Note>
  `APP_DEBUG` defaults to `false`, so a generic error page is shown when something goes wrong. Set
  `APP_DEBUG=true` temporarily while troubleshooting an installation to see the detailed error page with a
  full stack trace, then set it back to `false` (or remove it) once you're done -- leaving it enabled can
  expose sensitive information about your application and infrastructure to untrusted users.
</Note>

## Changing the Install Path

This is *not recommended* but may be necessary in rare circumstances. The installer will default to
`C:\InterWorks\Curator` if no changes are made to the install path. If you must change the install path, click the
"Options" button in the installer window

<img alt="Highlight options button" />

then change the Install Location path:

<img alt="Change install path" />

Please note that the paths above may no longer be valid if you change the install path.

## Installing a Specific Version

The Windows installer always installs the latest version of Curator. Unlike the
[Linux installer](/setup/installation/linux_installation), which supports a `-v` flag to specify a
particular version, the Windows installer does not offer a version selection option.

If you need to install a specific older version of Curator on Windows, please contact
[InterWorks support](https://interworks.com/contact/) for assistance.


# Forward Proxy
Source: https://docs.curator.interworks.com/setup/proxy_configuration/forward_proxy

Configure forward proxy settings for internet access and external connectivity

Curator utilizes internet access to connect to Tableau Server as well as Curator's web servers for updates.
When configured without outbound internet access, Curator upgrades must be performed manually and Tableau Server must
be accessible within the LAN.

Often, IT teams prefer to route internet traffic first through a proxy.
When configured to work through a proxy, Curator doesn't send requests directly to the internet.
Instead, it sends requests to the forward proxy, which in turn forwards the request.

To configure a forward proxy, add the following variables to Curator's `.env` file:

```bash theme={null}
proxy_override=http://proxy.example.com:3128
no_proxy_override=localhost,127.0.0.1

HTTP_PROXY=http://proxy.example.com:3128
HTTPS_PROXY=http://proxy.example.com:3128
NO_PROXY=localhost,127.0.0.1

http_proxy=http://proxy.example.com:3128
https_proxy=http://proxy.example.com:3128
no_proxy=localhost,127.0.0.1
```

Replace `proxy.example.com:3128` with the hostname and port of your organization's forward proxy.
Port `3128` is the default port for Squid-based proxies; adjust as required.

<Note>
  **proxy\_override** and **no\_proxy\_override** are read by Curator's own code and apply to all Curator
  processes, including web requests served through Apache and PHP CLI processes such as cron jobs.
  The standard `HTTP_PROXY` / `http_proxy` variables are read by bundled third-party tools such as
  Composer (used during upgrades). Both upper- and lowercase forms are required because different
  tools each read their own convention.
</Note>

## no\_proxy\_override / NO\_PROXY / no\_proxy Values

Common values include `localhost` and `127.0.0.1`. Keep the same bypass list across all three
variables so Curator's own code and bundled tools behave consistently.

If Tableau Server is on the same LAN as Curator, add its hostname so that traffic to Tableau is
not routed through the proxy:

```bash theme={null}
no_proxy_override=localhost,127.0.0.1,tableau.internal.example.com
NO_PROXY=localhost,127.0.0.1,tableau.internal.example.com
no_proxy=localhost,127.0.0.1,tableau.internal.example.com
```

<Note>
  Any other internal services that Curator needs to reach directly, such as an SSO or identity
  provider, should also be added to the bypass list.
</Note>

Since Tableau Cloud is a remote SaaS service, its traffic should flow through the proxy rather than
bypass it.


# Reverse Proxy
Source: https://docs.curator.interworks.com/setup/proxy_configuration/reverse_proxy

Configure reverse proxy and load balancing solutions for Curator

When installing Curator, you may wish to place Curator behind a reverse proxy or load balanced solution.

## Health Checks

Health checks should be run against the `/ping` route instead of simply the base `/` route.
The base / route will often return a 302 redirect, which many load balancers view as a "down" response.
The /ping route will always return a 200 response.

## Headers

When your users access Curator over the reverse proxy, specific "headers" are used to tell Curator how to process the
request.

**X-FORWARDED-FOR** : The IP address of the end user.

**X-FORWARDED-HOST** : The host name of the request.
*Note: A "Forced Domain" in Portal Settings->Security overrides this value.*

**X-FORWARDED-PROTO** :  Whether to use HTTPS or HTTP for routes.

## Unable to adjust headers

Often, reverse proxy solutions are missing some or all of these headers.

To help configure a reverse proxy with Curator, Apache configuration files can be used.

On Windows, the `curator.conf` file is a great place for this configuration.
On Linux, `/var/www/html/.htaccess`, or any of the httpd.conf files can also be utilized.

```conf theme={null}
SetEnv HOST "example.curator.interworks.com"
SetEnv HTTP_X_FORWARDED_HOST "example.curator.interworks.com"

SetEnv HTTPS "on"
SetEnv HTTP_X_FORWARDED_PROTO "https"
```

In addition to these settings, the security settings in **Settings** > **Curator** > **Portal Settings** > **General**
can be used.
In particular, **Forced Domain** and **Force SSL** should be utilized to specify the domain of Curator and to use SSL.

## Forced Domain and SSL

When Curator is behind a reverse proxy or load balancer, the server may not know the public domain name or protocol
that users access it through. This can cause Curator to generate links using the server's internal IP address or
server name (e.g., `10.40.243.235/dashboard/...`) instead of your domain name, or use `http://` instead of
`https://`.

The **Forced Curator Domain** setting overrides whatever host Curator detects, including the `X-Forwarded-Host`
header, and ensures all generated URLs use the specified domain. The **Force SSL** setting ensures all generated
URLs use `https://` instead of `http://`.

### Configuring Forced Domain and Force SSL

1. Navigate to **Settings** > **Curator** > **Portal Settings** > **General** and scroll to the **Security** section.
2. Enter your domain in the **Forced Curator Domain** field (e.g., `curator.example.com`). Do not include `https://`.
3. Enable **Force SSL** to ensure all URLs use HTTPS.
4. Save your changes.

<Note>
  This setting also prevents [Host Header Injection](https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/07-Input_Validation_Testing/17-Testing_for_Host_Header_Injection)
  attacks. Even if your proxy is sending the correct `X-Forwarded-Host` header today, setting a Forced Domain is
  recommended as an additional security measure.
</Note>

### Disabling via Command Line

If you lose access to the Curator UI after enabling these settings (for example, due to a DNS or SSL misconfiguration),
you can disable them from the server's command line:

```bash theme={null}
# Disable Force SSL
php artisan portal:setforcessl 0

# Clear the Forced Domain
php artisan portal:setdomain ""
```

## Trusted Hosts

Curator also ships a `trustedHosts` option in `config/app.php`, which is a second, code-level defense
against [Host Header Injection](https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/07-Input_Validation_Testing/17-Testing_for_Host_Header_Injection).
It rejects any request whose host header does not match an allowed value, before Curator processes it.

It ships disabled (`false`) so that requests arriving through a proxy under an internal hostname or IP
address are not rejected. Most installations should leave it disabled and use **Forced Curator Domain**
above instead, which solves the same problem from the application side and is configurable from the UI.

Enable `trustedHosts` only if your security policy requires host validation at the framework layer. Set
it to `true` to trust the host in `app.url` plus its `www` subdomain, or to an array of domains, IP
addresses, or regular expression patterns:

```php theme={null}
'trustedHosts' => [
    'curator.example.com',           // Matches just curator.example.com
    '^(.+\.)?example\.com$',         // Matches example.com and all subdomains
],
```

<Warning>
  If you enable `trustedHosts` and your proxy forwards a host that is not in the list, Curator rejects the
  request and users cannot reach the site. Confirm which host your proxy actually sends before enabling
  this, and be prepared to revert the change from the server's command line.
</Warning>

## Troubleshooting

### ERR\_TOO\_MANY\_REDIRECTS (redirect loop)

If users see `ERR_TOO_MANY_REDIRECTS` in the browser (or `This page isn't working - redirected you too many times`)
after enabling **Force SSL**, Curator is stuck in a redirect loop with the proxy.

**Root cause:** **Force SSL** tells Curator to redirect any request it sees as `http://` to `https://`. When the proxy
terminates SSL but does not forward the `X-Forwarded-Proto` (or `X-Forwarded-SSL`) header, Curator only sees the
plain HTTP request from the proxy and issues another redirect to HTTPS. The proxy then sends that redirected
request back to Curator as HTTP again, and the loop repeats until the browser gives up.

Clearing browser cookies does not resolve this -- the loop is on the server side.

**Recovering access:** If you can no longer reach the Curator UI, disable Force SSL from the server command line:

```bash theme={null}
php artisan portal:setforcessl 0
```

**Permanent fixes** (pick one):

1. Configure the proxy to forward `X-Forwarded-Proto: https` (and `X-Forwarded-SSL: on`) on every request it
   proxies to Curator. See the **Headers** section above.
2. Set the Apache environment variables described in the **Unable to adjust headers** section above so that
   Curator always treats the request as HTTPS.
3. Leave **Force SSL** disabled and instead enforce HTTPS at the proxy layer (for example, by redirecting all
   port 80 traffic to port 443 at the proxy).


# Basic HTTP Authentication
Source: https://docs.curator.interworks.com/setup/ssl/basic_http_authentication

Set up basic HTTP authentication for additional browser-level security

Basic HTTP Authentication provides a secondary browser-level authentication system. Usually used to secure
non-production setups. To enable the Basic HTTP Authentication:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "General" tab at the top of the main page content.
5. Click to switch on the "Basic HTTP Authentication" setting under the "Security" section and click the "Save" button.


# Force SSL
Source: https://docs.curator.interworks.com/setup/ssl/force_ssl

Configure Curator to enforce SSL/HTTPS connections for enhanced security.

Force SSL (https) will force all HTTP request to be https instead. This will require you to set up SSL certificates
first before enabling the feature. Otherwise, the site will run into an issue. To enable Force SSL (https):

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left navigation.
4. Click on the "General" tab at the top of the main page content.
5. Click to switch on the "Force SSL" setting under the "Security" section and click the "Save" button.


# Linux SSL
Source: https://docs.curator.interworks.com/setup/ssl/linux_ssl

Configure SSL certificates and HTTPS encryption for Curator on Linux systems

1. First, find your `curator.conf` file. For Ubuntu installations, this is located in `/etc/apache2/sites-enabled`. For
   all other Linux distributions, this file is located in `/etc/httpd/conf.d/curator.conf`. If you cannot find this file,
   you may have an old Curator installation. If so,
   [download `curator.conf` here](https://api.curator.interworks.com/file/curator_conf).

2. Upload your SSL certificate, key, and (optionally) chain files to the webserver. This can be done with a secure copy
   (SCP) client, such as FileZilla. Place these certificates in */etc/apache2/certs* for Ubuntu, or */etc/httpd/certs*, for
   all other Linux distributions.

3. Replace the references to SSLCertificateChainFile, SSLCertificateFile, and SSLCertificateKeyFile in the `curator.conf`
   to the location you uploaded them to in Step #2.

4. Save the contents of the file and restart apache with the commands below:

   ```bash theme={null}
   sudo apachectl restart
   ```

5. Navigate to the HTTPS version of the link to your portal in your browser (i.e. `https://curatorexample.com`). You
   should see a lock icon appear in the URL bar after the site loads to indicate that it is successfully encrypted. If you
   don’t see the lock or if you get an error, check your certificate for invalid information, such as incorrect site name
   or missing Subject Alternative Names.

## Debugging SSL

Having issues? It happens! SSL certificates can be uniquely challenging to implement. Here are a few debugging tips:

1. Make sure the certificate and key match. Often these get mismatched. Your server will not start if they do not match.
   If either of these commands errors, you may not have correctly formatted certificates. Make sure you acquired Apache/PEM
   certificates:

   ```bash theme={null}
   openssl rsa -modulus -noout -in yourKeyFile.key | openssl md5
   openssl x509 -modulus -noout -in myServer.crt | openssl md5
   ```

2. The certificate chain file is important, but can cause issues. If your Curator server won't start, try commenting out
   the SSLCertificateChainFile line in `curator.conf` temporarily to ensure that the issue is not the chain file.

3. Check Apache/HTTPD's error log. This can be found in /var/log/apache2/error\_log (Ubuntu) or /var/log/httpd/error\_log
   (All other distros). Also check `/var/www/curator_error.log`, if it exists. If the error message is not detailed enough,
   try increasing "LogLevel" to "debug" in `curator.conf`. (Note: be sure to set this value back to "warn" after you are done!)

## Notes on obtaining SSL certificates

1. Curator uses "Apache" type certificates. These may be referred to as "OpenSSL" or PEM certificates as well.
2. These certificates may in one big bundle, or separated into key, certificate, and chain files.
3. When installing key certificates, many providers require a key-passphrase.
   Once installed on the Curator server and at rest, you may wish to remove this passphrase.
   If the passphrase remains, it will be required anytime there is a restart of the web server.
   **STORE THE PASSPHRASE IN A SAFE PLACE. IF IT REMAINS ON THE KEY AND IS LOST YOU WILL HAVE TO GENERATE NEW CERTIFICATES.**
   To remove the passphrase, use this command.

   ```bash theme={null}
   openssl rsa -in [original.key] -out [new.key]
   ```

## SSL Protocols / Ciphers (Optional)

1. You may wish to update your SSL protocols and cipher suites. To do this, you'll need a little more info about your
   web server. Run the command below to get the Apache and OpenSSL versions:

   ```bash theme={null}
   httpd -V 2>/dev/null | grep version; apache2 -V 2>/dev/null | grep version; openssl version; php -v | grep cli
   ```

2. The expected output will look something like this:

   ```bash theme={null}
   Server version: Apache/2.4.48 ()
   OpenSSL 1.0.2k-fips  26 Jan 2017
   PHP 7.4.21 (cli) (built: Jul  7 2021 17:35:08) ( NTS )
   ```

3. Take the information retrieved in the previous step and use it to fill out the form on this
   [SSL Certificate Generator site](https://ssl-config.mozilla.org/#server=apache).

   * Select **Apache** for "Server Software"
   * Select **Intermediate** for "Mozilla Configuration".
   * Enter your Apache version
   * Enter your OpenSSL version

4. Replace the appropriate areas in the `curator.conf` file with the SSLProtocol and SSLCipherSuite that was generated
   on the SSL Certificate Generator site.

   For example:

   ```conf theme={null}
   SSLProtocol             all -SSLv3 -TLSv1 -TLSv1.1
   SSLCipherSuite          ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
   ```

5. Have a server open to the internet? Qualys has a free tool to test the certificates, protocols/ciphers, and their
   security: [https://www.ssllabs.com/ssltest/analyze.html](https://www.ssllabs.com/ssltest/analyze.html)


# Windows SSL
Source: https://docs.curator.interworks.com/setup/ssl/windows_ssl

Configure SSL/HTTPS for Curator installations on Windows servers with IIS.

## Finding relevant files

1. Find the **`curator.conf`** file (default location is `C:\InterWorks\Curator\curator.conf`).
2. Find the relevant keys. These will either be in a bundle, or separated into key, certificate, and chain files.
3. Put your keys into the correct directory (default location is `C:\InterWorks\Curator\certs\`).

## Converting .pfx / .p12 Certificates

If your certificate was provided in PKCS12 format (a `.pfx` or `.p12` file), you need to convert it to PEM format
before configuring SSL. See [Converting PFX/P12 Certificates to PEM](/setup/ssl/windows_ssl_pfx_to_pem) for
step-by-step instructions.

## Removing Passphrases (Required, if applicable)

If your certificate utilizes a passphrase, you'll need to remove it in order to use the certificate with Curator since
passphrases are not supported by Apache on Microsoft Windows servers.

1. Curator uses "Apache" type certificates. These may be referred to as "OpenSSL" or PEM certificates as well.
2. Windows is unique in that it cannot use certificates with embedded passphrases,
   so these have to be removed if they are present.
   These passphrases would normally be required before a restart of your web server on other operating systems,
   but are not able to be used here.
3. To remove the passphrases, you can use this command in the same directory as the certificates using Powershell.

   ```bash theme={null}
   & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' rsa -in [original.key] -out [new.key]
   ```

## Replacing References

1. Locate the references in the file (listed below) and replace your new .crt, .pem, and .key files where they are
   referenced in the `curator.conf` file.

2. Un-comment the lines (by deleting the `#` at the front of the line) starting at `Listen 443` and ending at
   `</IfModule>`.  See example below:

   ```conf theme={null}
   #Uncomment the lines below for SSL
   Listen 443
   <IfModule mod_ssl.c>
       <VirtualHost _default_:443>
           SSLEngine on
           ServerName www.example.com
           DocumentRoot "C:\InterWorks\Curator\htdocs"
           RewriteEngine on

           SSLCertificateChainFile C:\InterWorks\Curator\certs\chain.crt
           SSLCertificateFile C:\InterWorks\Curator\certs\cert.pem
           SSLCertificateKeyFile C:\InterWorks\Curator\certs\cert.key

           SSLProtocol                 [protocol]
           SSLCipherSuite              [ciphersuite]
           SSLHonorCipherOrder         on
           SSLCompression              off

           <Directory "C:\InterWorks\Curator\htdocs">
               AllowOverride All
               Options Indexes FollowSymLinks
               Require all granted
           </Directory>
   </VirtualHost>
   </IfModule>
   ```

3. After the configuration file has been edited and saved, restart Curator.

## SSL Protocols / Ciphers (Optional)

1. You may wish to update your SSL protocols and cipher suites. To do this, you'll need a little more info about your
   environment. Run the command below to get your Apache and OpenSSL versions, assuming default install locations for both:

   ```bash theme={null}
   & 'C:\InterWorks\Curator\libs\Apache24\bin\httpd.exe' -v; & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' version
   ```

2. The expected output will look something like this:

   ```bash theme={null}
   Server version: Apache/2.4.59 (Win 64)
   OpenSSL 3.3.1 4 Jun 2024 (Library: OpenSSL 3.3.1 4 Jun 2024)
   ```

3. Take the information retrieved in the previous step and use it to fill out the form on this
   [SSL Certificate Generator site](https://ssl-config.mozilla.org/#server=apache).

   * Select **Apache** for "Server Software"
   * Select **Intermediate** for "Mozilla Configuration".
   * Enter your Apache version
   * Enter your OpenSSL version

4. Replace the appropriate areas in the `curator.conf` file with the SSLProtocol and SSLCipherSuite that was generated
   on the SSL Certificate Generator site.

   For example:

   ```conf theme={null}
   SSLProtocol             all -SSLv3 -TLSv1 -TLSv1.1
   SSLCipherSuite          ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:
   ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:
   DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305
   ```

5. Have a server open to the internet? Qualys has a free tool to test the certificates, protocols/ciphers, and their
   security: [https://www.ssllabs.com/ssltest/analyze.html](https://www.ssllabs.com/ssltest/analyze.html)

## Troubleshooting

If Apache fails to start after configuring SSL, see the
[Windows Apache SSL Troubleshooting](/setup/ssl/windows_ssl_troubleshooting) guide for step-by-step diagnostics
and fixes for common issues.


# Windows SSL (IIS)
Source: https://docs.curator.interworks.com/setup/ssl/windows_ssl_iis_deprecated

Legacy SSL configuration for deprecated Windows IIS installations

<Danger>Curator no longer supports IIS on new installations.</Danger>

The information below is for use only for existing installs.  It is *highly* recommended that you reinstall with Apache for
stability, please see our
[Windows Apache Installation](/setup/installation/windows_installation)
documentation for steps on how to achieve the best Curator experience for Windows.

## Enabling SSL

1. In IIS Manager, on the left-hand pane, select the server (note: not the site).

2. On the server Home page double-click **Server Certificates** (in the center pane).

3. On the right-hand pane click the `Complete Certificate Request` link.

4. Follow the steps below in the Complete Certificate Request wizard, then click **OK**:

   **File name containing the certificate authority's response:** Your .cer file

   **Friendly name:** Give your cert a name!  Recommended format: `curator-cert-[expiration-date]`

   **Select a certificate store for the new certificate:** Select *Web Hosting*.

5. In IIS Manager, on the left-hand pane, select the site that is running Curator.

6. On the right-hand pane under *Edit Site*, click **Bindings...**.

7. In the Bindings window, click **Add**

8. Follow the steps below in the  Add Site Bindings window, then click **OK**:

   **Type** Select https.

   **IP address** Select the IP address of the site (or select All Unassigned).

   **Port** Type port 443

   **SSL certificate** 	Select the new SSL cert you created in step #4

9. On the right-hand pane click **Restart**


# Converting PFX/P12 Certificates to PEM
Source: https://docs.curator.interworks.com/setup/ssl/windows_ssl_pfx_to_pem

Convert PKCS12 (.pfx/.p12) certificates to PEM format for use with Curator on Windows.

If your certificate was provided in PKCS12 format (a `.pfx` or `.p12` file), you need to extract the PEM certificate
and private key before configuring SSL. Curator bundles OpenSSL, so you can run these commands directly in PowerShell.

1. Extract the certificate:

   ```bash theme={null}
   & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' pkcs12 -in [yourfile.pfx] -clcerts -nokeys -out [cert.pem]
   ```

2. Extract the private key:

   ```bash theme={null}
   & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' pkcs12 -in [yourfile.pfx] -nocerts -nodes -out [cert.key]
   ```

3. If the `.pfx` file includes a certificate chain, extract it as well:

   ```bash theme={null}
   & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' pkcs12 -in [yourfile.pfx] -cacerts -nokeys -chain -out [chain.crt]
   ```

> **Note:** If the `.pfx` / `.p12` file is password-protected, OpenSSL will prompt you for the import password when
> running these commands. The `-nodes` flag in step 2 produces an unencrypted private key, which is what Curator
> requires. If you omit `-nodes` (or are following a legacy workflow), the extracted key will be passphrase-encrypted
> — see [Removing Passphrases](/setup/ssl/windows_ssl#removing-passphrases-required-if-applicable) to remove it.


# Windows Apache SSL Troubleshooting
Source: https://docs.curator.interworks.com/setup/ssl/windows_ssl_troubleshooting

Diagnose and resolve common Apache SSL startup failures on Windows servers running Curator.

If Apache fails to start after configuring SSL on a Windows Curator installation, work through the steps below
to identify and resolve the issue.

<Note>
  The examples below use the default installation path `C:\InterWorks\Curator`. If Curator was installed on a
  different drive or directory, adjust the paths accordingly (e.g. `D:\InterWorks\Curator`).
</Note>

## Step 1: Test the Configuration From the Command Line

Open PowerShell as Administrator and run:

```bash theme={null}
& 'C:\InterWorks\Curator\libs\Apache24\bin\httpd.exe' -t
```

This validates the configuration and outputs a specific error message pointing to the exact file, line number, and
problem. If everything is valid, it outputs `Syntax OK`.

<Note>
  This is the fastest way to identify the issue. If the output points to a clear problem, skip to
  [Common SSL Issues and Fixes](#common-ssl-issues-and-fixes) for the resolution.
</Note>

## Step 2: Check the Apache Error Log

If Step 1 wasn't sufficient, check the Apache error logs:

```
C:\InterWorks\Curator\httpd_errors.log
C:\InterWorks\Curator\libs\Apache24\logs\error.log
```

Open these in Notepad — the most recent entries at the bottom will show what went wrong during the last startup attempt.

## Step 3: Check the Windows Event Log

1. Attempt to start the **Curator HTTPD Server** service from the Windows Services Manager.
2. After it fails, press **Win + R**, type `eventvwr.msc`, and press **Enter**.
3. Navigate to **Windows Logs** > **Application**.
4. The most recent error entries at the top will be from the failed startup attempt — double-click them and read
   the **Description** field for the actual error message.

## Common SSL Issues and Fixes

<AccordionGroup>
  <Accordion title="Certificate key has a passphrase (most common on Windows)">
    **Error:** `SSLPassPhraseDialog builtin is not supported on Win32` or the service hangs waiting for passphrase input.

    **Fix:** Strip the passphrase from the key:

    ```bash theme={null}
    & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' rsa -in C:\InterWorks\Curator\certs\your_key.key -out C:\InterWorks\Curator\certs\your_key_nopass.key
    ```

    Then update `SSLCertificateKeyFile` in `C:\InterWorks\Curator\curator.conf` to point to the new key.

    See also: [Removing Passphrases](/setup/ssl/windows_ssl#removing-passphrases-required-if-applicable) in the
    Windows SSL setup guide.
  </Accordion>

  <Accordion title="Certificate file path is wrong or file missing">
    **Error:** `SSLCertificateFile: file 'C:\...' does not exist or is empty`

    **Fix:** Verify the paths in `C:\InterWorks\Curator\curator.conf` for these directives all point to files that
    actually exist in `C:\InterWorks\Curator\certs\`:

    * `SSLCertificateFile`
    * `SSLCertificateKeyFile`
    * `SSLCertificateChainFile`
  </Accordion>

  <Accordion title="SSL section not fully uncommented in curator.conf">
    **Error:** Syntax errors referencing lines in the SSL block.

    **Fix:** Open `C:\InterWorks\Curator\curator.conf` and ensure the entire `<VirtualHost *:443>` block and the
    `Listen 443` line are fully uncommented (no stray `#` characters).

    See: [Replacing References](/setup/ssl/windows_ssl#replacing-references) in the Windows SSL setup guide.
  </Accordion>

  <Accordion title="Chain/intermediate certificate file missing">
    **Error:** `SSLCertificateChainFile: file does not exist`

    **Fix:** Ensure the CA intermediate/chain certificate is in the certs directory and referenced correctly. If you
    have a single combined cert, comment out the `SSLCertificateChainFile` directive.
  </Accordion>

  <Accordion title="Certificate and key don't match">
    **Error:** `certificate and private key do not match`

    **Fix:** Verify they match by comparing their modulus hashes:

    ```bash theme={null}
    & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' x509 -noout -modulus -in C:\InterWorks\Curator\certs\your_cert.crt | & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' md5
    & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' rsa -noout -modulus -in C:\InterWorks\Curator\certs\your_key.key | & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' md5
    ```

    Both commands should output the same hash. If they don't, the wrong key or certificate file is being used.
  </Accordion>

  <Accordion title="Port 443 already in use">
    **Error:** `could not bind to address 0.0.0.0:443`

    **Fix:** Check what's using port 443:

    ```bash theme={null}
    netstat -ano | findstr :443
    ```

    If IIS or another service is on port 443, stop it or change the Curator port.
  </Accordion>

  <Accordion title="Certificate in wrong format (DER instead of PEM)">
    **Error:** `error reading certificate` or `PEM routines:get_name:no start line`

    **Fix:** Apache requires PEM format (text starting with `-----BEGIN CERTIFICATE-----`). Convert from DER if needed:

    ```bash theme={null}
    & 'C:\InterWorks\Curator\libs\Apache24\bin\openssl.exe' x509 -inform DER -in your_cert.cer -out your_cert.pem
    ```
  </Accordion>
</AccordionGroup>

## After Fixing

1. Re-run the config test:

   ```bash theme={null}
   & 'C:\InterWorks\Curator\libs\Apache24\bin\httpd.exe' -t
   ```

2. If it says `Syntax OK`, start the **Curator HTTPD Server** service from Services Manager.


# Adding Your First Dashboard
Source: https://docs.curator.interworks.com/setup/trial_quick_start_guide/adding_your_first_dashboard

Step-by-step guide to create your first analytics connection and add dashboards to Curator.

Click on **Integrations → Connections**

Click on **New Connection button**

* **Name**
  * Name your connection
* **Slug**
  * This slug (url extension) will auto-generate but can be customized
* **Description**
* **Platform**
  * Options include: Tableau, Power BI, ThoughtSpot
  * After selecting an option, fill out the platform specific connection information and credentials

## Tableau

### Tableau Server

1. **Enter Site name** (e.g. `https://analytics.acme.com`)
2. **Enter Service Account credentials or Personal Access Token**. To enter Personal Access Token, follow the below steps:
   1. Log onto your Tableau Server
   2. Click account icon on top right of screen (by default, will by a circle with your initials in it)
   3. Select My Account Settings
   4. Scroll to Personal Access Token
   5. Enter a Name for your Token and click Create Token

Additional information on Personal Access Tokens can be found in [Tableau’s documentation](https://help.tableau.com/current/pro/desktop/en-us/useracct.htm#create-and-revoke-personal-access-tokens).

### Tableau Cloud

1. **Select the Tableau Cloud Host region** (found in the server url)
2. **Enter the Site name** (found in the server url after logging in)
3. **Enter your Personal Access Token**
4. **To enter Personal Access Token, follow the below steps:**
   1. Log onto your Tableau Server
   2. Click account icon on top right of screen (by default, will by a circle with your initials in it)
   3. Select My Account Settings
   4. Scroll to Personal Access Token
   5. Enter a Name for your Token and click Create Token

Additional information on Personal Access Tokens can be found in [Tableau’s documentation](https://help.tableau.com/current/pro/desktop/en-us/useracct.htm#create-and-revoke-personal-access-tokens).

#### Power BI

**Enter your Tenant ID in Azure**. To find your Tenant ID, follow this [documentation](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/how-to-find-tenant).

#### ThoughtSpot

1. Enter your ThoughtSpot URL
2. Enter your ThoughtSpot credentials

## Adding a Dashboard From Your Server

Once you have established a connection to your server you can begin adding individual Dashboard connections. For our
example we will follow along with a Tableau Dashboard but the instructions are similar for other BI platforms.

1. **Click Tableau** (or your BI Platform Option) → **Dashboards**
2. **Click the New Dashboard Button**

Select desired Server, Site, Project, Workbook, and Dashboard then click create to establish a connection.

<img alt="Dashboard dropdowns" />

Connect dashboards will be listed in the Tableau → Dashboard menu:

<img alt="Dashboard list" />

## Adding a Menu Link to the Navigation

After a connection to a Dashboard has been established, the simplest method is to add a menu link to the navigation pane
at the top of your environment.

<img alt="homepage hero image and menu" />

Click **Content → Navigation**

1. Select New Menu Link
2. Select your Dashboard Link Type
3. Select your Dashboard
4. Select Create

Once you create the link you will be brought to a page that displays the navigation hierarchy. You can control the
navigation pane’s order and drop down menus here:

<img alt="navigation reorder view" />

After you have decided on hierarchy, navigate to the front end and see your new navigation menu items that lead to your dashboards:

<img alt="homepage hero image and menu" />


# Creating Your First Page
Source: https://docs.curator.interworks.com/setup/trial_quick_start_guide/creating_your_first_page

Learn how to use the page builder to create and customize your first content page in Curator.

Click on **Content → Pages → New Page**

To get started, enter a page title and toggle whether you want to show or hide it.

## Page Builder

To get started with the page builder, click the + button on the empty page builder interface.

<img alt="empty page" />

### Add an Element

An interface will popup which gives you the option to Add an Element.

The default container in your preview represents a single element. These elements can be broken down into 3 different types:

1. **Web Elements** (Text, Banners, etc)
2. **Analytic Elements** (BI Dashboards, SSRS, etc)
3. **Additional Elements** (Unrestricted HTML, Embedded URLS, etc)

After adding an element, select the element and a menu window will appear on the left side with options to change,
delete, and customize your element.

## Example: Creating a Page

Some of our most common elements are listed below

### Add a Hero Element

1. After naming your page, the first step in our sample page will be to add a Hero Element.
2. On the left menu window, select Hero Settings and select one of the template starter images.
3. Add in a Heading (e.g. ACME Sample Page) and Body Texts and Change Text Color if needed
4. Under Row Styles, update the Row Width to Full Width if the Hero Image should go across the full width.
   <img alt="page elements modal hero image highlighted" />

### Add a Dashboard to a Page

Dashboards can be either set up as standalone items or embedded within a page for greater customization on the wider page.

To add a Dashboard to a page, go ahead and add an element, select Analytic Elements and add your desired Dashboard to
replace the element.

**Note:** If the Analytics Element is unavailable to be selected, please add the relevant connection.

<img alt="Analytics Element modal" />

### Add a Text Field

<img alt="page elements modal text highlighted" />

Make updates to your text like bolding, italicizing, strike-through and many more options in the text editor.

<img alt="wysiwyg text editor" />

### Add Buttons

<img alt="page elements modal buttons highlighted" />

#### Buttons

Add externally linking buttons with the buttons component. Under Content Selection, link to different options like:

* Tableau/Power BI Dashboards
* Pages
* Files
* Content Tagged by Keywords
* External URLs
* Manual Selections (Combination of above options)

## Additional Options

Add more elements to customize and complete your page and then select save in the top right. Congrats your first page
has been created!

**TIP:** Clone your pages if you want to have a consistent design and save time when adding dashboards to separate pages


# Getting Started
Source: https://docs.curator.interworks.com/setup/trial_quick_start_guide/getting_started

Comprehensive guide to building your first analytics portal in Curator with step-by-step instructions.

Welcome to our comprehensive guide on building an analytics portal in Curator —a powerful tool that will empower you to
make data-driven decisions and unlock valuable insights within your organization. In today's data-driven world, the
ability to harness and interpret information is crucial for staying ahead of the competition and optimizing business
processes. Whether you're a seasoned developer or a novice enthusiast, this step-by-step tutorial will walk you through
the process of creating an analytics portal, integrating data sources, adding dashboards, and designing an intuitive user
interface. Get ready to transform your data into actionable knowledge and unleash the full potential of analytics with
our easy-to-follow instructions and best practices. Let's embark on this exciting journey of building your very own
analytics portal!

## First Steps

You’ve just reached out to an InterWorks Account Executive and have had a free trial set up.

You should have received an email that looks like this:

<img alt="trial screen" />

## Front End vs Admin

The front-end login will direct you to your portal and show you what your end users will see.  The default URL should
appear as `companyname.portals.interworks.com` and is fully customizable.

The admin login will lead you to administrative settings and the URL should appear as
`companyname.portals.interworks.com/backend`. The administrative settings are where you will build your analytics portal,
control your authentication, and manage your users.

Click on the Admin login and continue to the Admin Settings below.

## Admin Settings

After entering your username and password, you should enter a screen that looks like this:

<img alt="Curator home Dashboard" />

### Admin Menu Options

To the left, you’ll see the menu options. They are categorized into 4 sections.

1. **Content:** Pages, files and navigation
2. **Tableau:** Dashboards, filters and parameters
3. **Integrations:** Tableau Server connections and user group syncs
4. **Settings:** Curator settings, upgrades, security and users

### Update your Account Information and Password

In a Curator trial? Go ahead and navigate to the next page on Setting Up Your Portal. If you change your trial
credentials then we will not be able to easily troubleshoot issues for you!

If you are working on setting up your own instance, then go ahead and update your account information and password from
the defaults.

To do this, click on your icon on the top right, and update your First Name, Last Name, and Password.

<img alt="backend user account page" />

Click the save button to apply your changes.


# Setting Up Your Portal
Source: https://docs.curator.interworks.com/setup/trial_quick_start_guide/setting_up_your_portal

Initial setup and configuration guide to customize your Curator portal theme and frontend access.

Click on **Settings → Curator → Themes → Main Theme**

Click on the Main Theme **Global Theme** to edit our global theme

A live view of your Curator site will appear on the screen. We recommend logging into the front end on a separate screen
before making any changes so that you can see the changes you make on your Curator site. Keep in mind that your admin
account is separate from the front end accounts. Your credentials may be different based on how you choose to
authenticate your users. If you are not able to log into the front end then click **Settings** → **Security** →
**Authentication Settings** to see how your front end user credentials are being pulled in.

**Live preview:**

<img alt="Live preview" />

**On the left-hand side:**

* **Rename your Curator Site** (e.g. ACME Analytics Portal)

* **Upload a logo**
  * File formats supported: .jpg, .png, .gif, .svg
  * Curator is flexible with image sizes but we recommend wider over taller logos
  * Logo padding by entering pixels or percentages (Ex: 15px or 20%)
    * Tip: use negative padding if you are trying to increase the size of your image

* **Upload a favicon**- the icon used in the browser tab

**Favicon example:**

<img alt="favicon example" />

**Logo and Favicon Settings:**

<img alt="Logo and Favicon Settings" />

**Click Save button on the top right or press enter.**

## Updating the Navigation Bar

Click on the **Menu** tab

On the left-hand side you’l see various options.

* **Main Menu**
  * This lets you inter-change different main menu objects you may have created
  * For now, leave this as default
* **Navigation Type**
  * This lets you alter the location of the menu whether Top Navigation, Mega Menu or Side Navigation
* **Navigation Background Color**
* **Navigation Text Color**
* **Navigation Highlight Color**

There’s other navigation options as well below, but for now, we’ll stick to these main ones.

## Other Settings

There’s a whole host of other settings including:

**Brand**- Site Name, Site Logo and Icons

**Home**- Default home page settings

**Global**- Search, Alerts, Mobile Settings

**Fonts**- Customizable font options

**Menu**- Menu design settings

**Titles & Toolbar**- Pages titles and toolbar settings

**Dashboards**- Dashboard tabs

**Pages**- Tile styles, tutorial styles, button options, page margins

**Footer**- Footer options


# Accessing the Backend
Source: https://docs.curator.interworks.com/site_administration/accessing_the_backend

Learn how to access the backend of Curator for configuration and management tasks.

To access the backend administration area of your Curator instance, you will need to log in with an account that has
administrative privileges.  Typically this is created in the [initial setup](setup/installation/linux_installation) of
your Curator instance, or by an [existing administrator](site_administration/backend_administrators/overview).

### Logging into the Backend

1. Open your web browser and navigate to the backend URL of your Curator instance. This is usually in the format:
   `https://www.yourcuratorexample.com/backend`.

   <Frame>
     <img alt="Backend login screen" />
   </Frame>

2. Enter your administrator username and password in the login form.


# Activity
Source: https://docs.curator.interworks.com/site_administration/activity/activity_overview

Explore how much your portal is used, when, by whom, and what content is being viewed or ignored.

The Activity page answers the questions an administrator asks about Curator, in the order they come up: how
much is it used, when, what do people look at, who uses it, and who is being turned away. Every panel responds
to one shared set of filters at the top of the page, and every panel can be read as a table, downloaded as a
CSV file, or fetched from the API.

<BackendNavPath />

<Note>
  The Activity page is available to backend administrators who have been granted at least one core
  Curator permission, for example **Manage Curator Settings**. See
  [Backend Administrator Permissions](/site_administration/backend_administrators/permissions)
  for the full list of permissions and what each one controls.
</Note>

<Note>
  To pull this data into your own reporting instead of reading it here, see
  [Retrieving Usage Data](/site_administration/activity/retrieving_usage_data).
</Note>

<Frame>
  <img
    alt="Activity page showing the filter bar, the headline tiles and views-over-time chart, the weekday
and hour heatmap, the content, audience, and access denied sections."
  />
</Frame>

The page follows your browser's color scheme.

<Frame>
  <img alt="The same Activity page rendered in dark mode." />
</Frame>

## Filtering the view

The filter bar narrows every panel to a time period, a content type, a single content item, or a single user.
All panels update as soon as a filter changes.

* **Date Range** selects a start and end date. When no range is set, the page shows the last 30 days.
* **7d / 30d / 90d / 12m** are quick ranges that end today.
* **Content Type** narrows the page to one platform, for example Tableau dashboards or Pages.
* **Content** narrows the page to one item. The list holds the 100 most viewed items.
* **User** narrows the page to one person.

Click **Reset** to clear every filter.

Two panels cannot honor the content filters, because the data behind them records a requested path or a login
rather than a content item: the **Logins** and **Access denied** figures. When a content filter is active, those
panels show an "All content" note so the number is never read as filtered.

## Reading, downloading, and fetching a panel

Every panel has three buttons in its header:

* **Table** shows the same numbers as a plain table. Click **Table** again to return to the chart.
* **CSV** downloads the table as a CSV file with the current filters applied. The link can be bookmarked or
  shared with another administrator, who must be signed in to the backend to use the link.
* **API** copies the panel's API URL to your clipboard with the current filters applied. Add your API key as
  the `apikey` parameter before you use the URL. See [Activity API](/curator_api/api_docs/activity) for the
  parameters and the response format.

Hover any bar, cell, tile, or line to read its exact value.

## How much is Curator being used?

Four headline figures compare the selected range with the period of the same length that came right before
it. For a 30-day range, the comparison is the 30 days before that.

* **Views** counts every content view, including views by visitors who were not signed in.
* **Viewers** counts distinct signed-in users who viewed something.
* **Logins** counts sign-ins from the usage log.
* **Access denied** counts requests that were sent to the Access Denied page. For this figure, up is bad, and
  the color reflects that.

The **Views over time** chart draws the selected range in teal and the previous period in gray, aligned day
for day so the two lines can be compared directly. Use **Day**, **Week**, and **Month** to change the
aggregation. Week needs a range of at least 7 days and Month at least 30. Hover the chart to read both values
for any point, or click **Table** on any panel to see the same numbers as a table.

## When do people use it?

A weekday by hour heatmap shows the average number of views in each hour slot, in the timezone Curator is
configured to use. Each
cell divides its total by the number of times that weekday falls inside the selected range, so a range that
holds two Mondays and one Sunday does not make Monday look twice as busy. A sentence under the grid names the
busiest slot and the busiest day. Use this panel to choose maintenance windows and extract refresh times.

## What are they looking at?

* **Most viewed content** lists the top 25 items. Click a row to focus the whole page on that item, and click
  the row again to clear the focus.

<Frame>
  <img
    alt="The Most viewed content panel with one row selected, the other rows dimmed, and the Content filter
showing one selected item."
  />
</Frame>

* **Views by content type** shows how views split across platforms, with the count and share for each.
* **Not viewed** counts the items of each content type that received no views in the selected range, and lists
  them in its table with the last time each was ever viewed. Use the panel to find content to retire. This panel
  ignores the content and user filters, because "not viewed" only makes sense across everything.

## Who is using it?

* **Most active viewers** lists the top 10 signed-in users. Click a row to focus the page on that user.
* **Views per viewer** groups signed-in viewers by how many views they made (1, 2 to 5, 6 to 20, 21 or more)
  and shows what share of all signed-in viewing each group carried, so you can tell whether usage is broad or
  carried by a few power users. The user filter does not apply to this panel.
* **Audience** places every account that existed by the end of the range into exactly one group:

  * **New viewers** made their first ever view in the range.
  * **Returning viewers** viewed before the range and again inside the range.
  * **Dormant** viewed before the range but not inside the range.
  * **Never viewed** have no views on record, including accounts that only signed in.

  The headline percentage is new plus returning viewers divided by the accounts that existed by the end of the
  range, so a historical range is not diluted by accounts created later. The figure counts registered accounts,
  not licensed seats. A separate line reports how many accounts were created in the range.

## Who is being turned away?

* **Access denied per day** charts denials over the range. A sudden rise usually follows a permission or menu
  change.
* **Who was denied, and where** groups denials by requested path and user, most attempts first, with the last
  time each pair was seen. Visitors who were not signed in appear as "system (frontend)".

When nobody was denied access in the range, both panels say so.


# Retrieving Usage Data
Source: https://docs.curator.interworks.com/site_administration/activity/retrieving_usage_data

Export Curator usage and activity data programmatically using the Curator API.

The [Activity](/site_administration/activity/activity_overview) page reports on usage inside a single
portal. When you want that same data in your own warehouse, BI tool, or reporting process, read it
through the Curator API instead.

Everything below uses the Data Manager read endpoints, documented in full at
[Data Manager](/curator_api/api_docs/data_manager).

## Before you start

Each portal stores its own data. There is no combined endpoint across portals, so a multi-portal
deployment calls each portal in turn and combines the results downstream.

The set of readable tables is assembled from the plugins installed on a portal, so it varies by Curator
version. Ask a portal what it supports rather than assuming:

```
[your_domain]/api/v1/datamanager/getDataTables?apikey=[your_api_key_here]
```

<Warning>
  Treat an API key like a password. Store it outside your scripts, and never paste a URL containing a
  real key into a support ticket, a shared document, or a source repository.
</Warning>

## Content views

`interworks_usermgmt_content_view` is the table behind the Activity page. One row is written each time a
user opens a piece of content.

```
[your_domain]/api/v1/datamanager/getData?apikey=[your_api_key_here]&table=interworks_usermgmt_content_view
```

**Example Response:**

```JSON theme={null}
    {
        "result": "Success",
        "data": [
            {
                "id": 4821,
                "frontend_user_id": 112,
                "username": "jane.smith",
                "viewable_content_type": "InterWorks\\TableauViz\\Models\\Dashboard",
                "viewable_content_id": 37,
                "request_root": "https://curator.example.com",
                "request_path": "/dashboard/sales-overview",
                "request_query": null,
                "created_at": "2025-02-19 16:11:10",
                "updated_at": "2025-02-19 16:11:10"
            }
        ]
    }
```

The columns that matter for reporting:

| Column                  | What it holds                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `frontend_user_id`      | The Curator user who viewed the content. Join this to `listUsers` below.                  |
| `username`              | The username captured at view time, kept even if the user is later removed.               |
| `viewable_content_type` | The model class of the content, for example `InterWorks\TableauViz\Models\Dashboard`.     |
| `viewable_content_id`   | The ID of the content within that type.                                                   |
| `request_path`          | The path the user requested, useful when the same content is reachable more than one way. |
| `created_at`            | When the view happened. Sort and page on this column.                                     |

`viewable_content_type` and `viewable_content_id` together identify the content. Read the matching
content table, such as `interworks_tableauviz_dashboards` or `interworks_content_pages`, to turn that
pair into a title.

### Summary table

`interworks_usermgmt_content_view_summary` holds one row per user and content item, with a
`last_visited` timestamp instead of individual views. Use it when you want current totals rather than a
full event history, since it is much smaller than the view table.

### Favorites

`interworks_usermgmt_favorite` records which content users have marked as a favorite. It pairs well with
content views when you are measuring engagement rather than traffic.

## Users

Content view rows identify a user by ID and username. Pull the rest from the User API:

```
[your_domain]/api/v1/user/listUsers?apikey=[your_api_key_here]&num=100&pg=1
```

Each user comes back with their groups and their `analytics_id`. That `analytics_id` is the same
non-personal identifier Curator sends to your analytics platform, so it is the key that lets you combine
API exports with the analytics approach described below.

See [User API](/curator_api/api_docs/user_api) for the full endpoint.

<Note>
  `listUsers` covers frontend users and their groups. Backend administrator accounts are not exposed
  by any API endpoint. If you need an inventory of backend administrators, read it from
  [Backend Administrators](/site_administration/backend_administrators/overview) in the portal
  backend.
</Note>

## Administrator activity

Content views cover what your frontend users opened. To see what administrators did in the backend, read
the usage log:

```
[your_domain]/api/v1/datamanager/getData?apikey=[your_api_key_here]&table=interworks_portal_usage_log
```

Filter to `is_frontend = 0` for actions taken in the portal backend. Each row records the action `type`,
the `username` behind it, and a `details` payload describing what changed.

| Column        | What it holds                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `type`        | The action, such as `interworks.portal.api_key.create` or `interworks.portal.upgrade`.                        |
| `username`    | Who acted: a backend login, `system` for scheduled and console work, or `API (...key owner)` for an API call. |
| `is_frontend` | `0` for backend, console, and API activity, `1` for frontend activity.                                        |
| `details`     | Action-specific data, including a `_changes` set on edits.                                                    |
| `created_at`  | When the action happened. Sort and page on this column.                                                       |

<Note>
  Secrets are masked before they reach this table. An API key appears only as its last four characters,
  which is enough to tell two keys apart, and passwords are removed entirely. Older portals stored some
  of these values in full, and the upgrade that introduced the masking also rewrites those earlier rows.
</Note>

Because the usage log records administrator actions, treat an export of it as sensitive and restrict who
can read it, the same way you would the backend itself.

## Paging

The default page size is 1000 rows, and requests carrying an `apikey` are rate limited. Page through a
busy portal rather than requesting everything at once, and sort on `created_at` so paging stays stable
while new rows arrive:

```
[your_domain]/api/v1/datamanager/getData?apikey=[your_api_key_here]&table=interworks_usermgmt_content_view&sort_column=created_at&limit=1000&offset=0
```

Increase `offset` by `limit` on each call until a request returns fewer rows than the limit.

## Reporting across several portals

Curator has no cross-portal roll-up. Two approaches work, and they combine well:

1. **Call each portal and union the results.** Add a portal identifier as you load each response, since
   IDs are only unique within a portal. This gives you the same detail the Activity page shows.
2. **Point every portal at one analytics property.** Configure the same Google Analytics 4, Google Tag
   Manager, or Matomo property on each portal so page views and Dashboard events land in a single place
   already combined. See
   [Analytics Tracking](/site_administration/analytics_tracking/analytics_tracking).

Because Curator sends the user's `analytics_id` with each analytics event, and `listUsers` returns that
same ID, you can map analytics activity back to a named Curator user when you need to.


# Data Manager Notifications 
Source: https://docs.curator.interworks.com/site_administration/admin_email_notifications/data_manager_notifications

Set up email notifications for Data Manager form submissions to stay informed of user data input and feedback.

To stay up-to-date on the data being submitted to Curator you can subscribe multiple users to receive email
notifications immediately after a form has been submitted.  These emails will also contain the data from the
form that has been submitted, allowing you to instantly review anything that comes in: whether it's a Contact
Us form, a Feedback form, or tracking your users favorite pizza, you'll know right away!

**NOTE**: Email configuration on Curator is required to use this email notification system.  If you have not
configured email on your Curator instance, please get in touch with your email administrator and [use these instructions](/setup/email/email_configuration)
to set up email.

## Enabling Data Manager Email Notifications

1. Login to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend` ).
2. Navigate to the **Data Manager** > **Data Groups** section from the left-hand menu.
3. Click on the Group you would like to add an email to.
4. Toggle ON the switch labelled "Email submissions"
5. This will display a repeater that you can add individual emails to.  Populate them one-at-a time.
6. Click the "Save" button.

**NOTE**: If the Data Group has "Send to Webhook" enabled with a webhook selected, new submissions go to that webhook
and are not saved to Curator.  No notification email is sent.  See
[Sending Data to Webhooks](/embedding_using_analytics/data_manager/sending_data_to_webhooks) for details on that
option.


# System Notifications 
Source: https://docs.curator.interworks.com/site_administration/admin_email_notifications/system_notifications

Configure automated email notifications for system alerts, issues, and maintenance updates to improve Curator instance management.

To ensure you are able to easily manage your Curator instance without having to check-in all the time, you
can subscribe to emails that generate from Curator's notification system.  These emails will scan Curator's
running list of issues, suggestions and to-do items that will ensure you have more visibility into your
Curator instance making management easier and increasing stability.

**NOTE**: Email configuration on Curator is required to use this email notification system.  If you have not
configured email on your Curator instance, please get in touch with your email administrator and [use these instructions](/setup/email/email_configuration)
to set up email.

## Enabling Email Notifications

1. Login to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend` ).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the "Notifications" tab at the top of the page.
4. Toggle ON the switch labelled "Send Curator Digests"
5. This will display scheduling options.  Choose your weekly/daily/monthly scheduling options, and whiter or
   not you'd like immediate notifications for new alerts.
6. Click the "Save" button.

## Subscribing to and Un-Subscribing from Email Notifications

There are two ways to manage who receives the admin digest. Subscribing a backend user is always done
from their profile (the first method below); un-subscribing can be done either from the user's profile or
directly from the recipients list on the Notifications tab.

### From the Backend Administrator's profile

1. Login to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend` ).
2. Navigate to the **Settings** > **Curator** > **Backend Administrators** section from the left-hand menu.
3. Click on the User whose settings you would like to change.
4. Check or un-check the "Subscribe to admin digest" checkbox.
5. Click the "Save" button.

   <img alt="Subscribe Image" />

### From the recipients list on the Notifications tab

1. Login to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend` ).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the "Notifications" tab at the top of the page.
4. Under **Backend Admin Recipients** you will see one row for each backend user currently subscribed to
   the admin digest. Click the **X** on a row to un-subscribe that user, then click the "Save" button.

**NOTE**: This list mirrors the "Subscribe to admin digest" setting on each backend user, so removing a
row un-checks that user's checkbox. Adding a recipient is only done from the Backend Administrator's
profile (the first method above). At least one administrator must remain subscribed -- if you try to remove
the last subscribed admin, the save is rejected with a validation error, so subscribe another admin first.

### Recipients without a backend account

Digests can also go to people who do not have a backend account.  Add their address to the "Additional
Non-Curator-Admin Emails" field on the "Notifications" tab of **Settings** > **Curator** > **Portal Settings**.  Click
the "Save" button when you are done.


# Analytics Tracking
Source: https://docs.curator.interworks.com/site_administration/analytics_tracking/analytics_tracking

Configure web analytics tracking in Curator using Google Analytics, Google Tag Manager, or Matomo to monitor user engagement and dashboard interactions.

Curator supports integration with popular web analytics platforms so administrators can track page views, user
engagement, and Dashboard interactions. Analytics tracking is configured in the Curator backend under
**Portal Settings > Analytics**.

## Supported Platforms

Curator supports the following analytics platforms. You can enable one or more simultaneously:

| Platform                               | Tracking Method                                     | User Identification                                        |
| -------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------- |
| Google Analytics (Universal Analytics) | Page views and custom events via `analytics.js`     | Not sent                                                   |
| Google Analytics 4 (GA4)               | Page views and custom events via `gtag.js`          | `user_id` set to non-PII `analytics_id` UUID               |
| Google Tag Manager (GTM)               | Container-based tag management                      | `user_id` pushed to `dataLayer` as the `analytics_id` UUID |
| Matomo                                 | Page views, events, and site search via `matomo.js` | `setUserId` set to non-PII `analytics_id` UUID             |

## Configuration

Navigate to **Portal Settings > Analytics** in the Curator backend. All fields are optional. Fill in only the
fields for the platform(s) you use.

### Google Analytics (Universal Analytics)

**Google Analytics Tracking ID (Universal Analytics)** — Your Universal Analytics tracking ID
(e.g., `UA-XXXXXXXX-X`). Enables the `analytics.js` tracker, which sends an automatic page view on each
page load.

<Note>
  Universal Analytics was sunset by Google in July 2024. If you are setting up analytics tracking for the first
  time, use Google Analytics 4 or Google Tag Manager instead.
</Note>

### Google Analytics 4 (GA4)

**Google Analytics Tracking ID (Google Analytics 4)** — Your GA4 measurement ID
(e.g., `G-XXXXXXXXXX`). Enables the `gtag.js` tracker with automatic page views. If a user is logged in,
their non-PII `analytics_id` UUID is sent as the `user_id` property. See
[Correlating an `analytics_id` Back to a Curator User](#correlating-an-analytics_id-back-to-a-curator-user) for how
to look up the Curator user behind a UUID.

### Google Tag Manager (GTM)

**Google Analytics Tag Manager Container ID** — Your GTM container ID (e.g., `GTM-XXXX`). Loads the GTM
container script on every page. If a user is logged in, their non-PII `analytics_id` UUID is pushed to the
`dataLayer` as `user_id` before the container loads.

<Note>
  When using Google Tag Manager, you manage your analytics tags (including GA4) within GTM itself. You do not
  need to also fill in the GA4 field unless you want a separate, direct GA4 integration outside of GTM.
</Note>

### Matomo

* **Matomo Server URL** — The URL of your Matomo instance (e.g., `//matomo.example.com/`). Must include a
  trailing slash.
* **Matomo Site ID** — The numeric site ID configured in your Matomo instance (e.g., `1`).
* **Enable Matomo Heartbeat** — When enabled (default: on), Matomo tracks actual time spent on the page by
  monitoring whether the browser tab is active and in focus.

Both the Matomo Server URL and Matomo Site ID must be provided for Matomo tracking to activate. If a user is
logged in, their non-PII `analytics_id` UUID is sent via `setUserId`. Matomo link tracking and download
tracking are enabled automatically.

## Tracked Events

When analytics is configured, Curator automatically tracks user interactions as events. All events are sent to
every enabled analytics platform. Events use the category **Dashboard** and include the following actions:

| Event                             | Description                              |
| --------------------------------- | ---------------------------------------- |
| Custom View Applied               | User applied a saved Custom View         |
| Custom View Created               | User created a new Custom View           |
| Custom View Made Private          | User changed a Custom View to private    |
| Custom View Made Public           | User changed a Custom View to public     |
| Custom View Removed               | User deleted a Custom View               |
| Custom View Set as Default        | User set a Custom View as the default    |
| Data-Driven Alert Ceded           | User left a data-driven alert            |
| Data-Driven Alert Joined          | User joined a data-driven alert          |
| Download Workbook                 | User downloaded a workbook               |
| Exported All Summary Data         | User exported all summary data           |
| Exported CSV                      | User exported data as CSV                |
| Exported Data                     | User exported data                       |
| Exported Excel                    | User exported data as Excel              |
| Exported Image                    | User exported a Dashboard as an image    |
| Exported PDF                      | User exported a Dashboard as PDF         |
| Exported Powerpoint               | User exported a Dashboard as PowerPoint  |
| Exported Tableau-based Powerpoint | User exported a Tableau-based PowerPoint |
| Exported Workbook Summary Data    | User exported workbook summary data      |
| Favorited                         | User favorited a Dashboard               |
| Filter Applied                    | User applied a filter                    |
| Fullscreen                        | User entered fullscreen mode             |
| Parameter Applied                 | User applied a parameter                 |
| Paused                            | User paused automatic updates            |
| Powerpoint New Slide              | User added a new PowerPoint slide        |
| Powerpoint Slide Deleted          | User deleted a PowerPoint slide          |
| Powerpoint Slides Cleared         | User cleared all PowerPoint slides       |
| Print Dashboard Image             | User printed a Dashboard image           |
| Refresh Timer Start               | User started an automatic refresh timer  |
| Shared                            | User shared a Dashboard                  |
| Unfavorited                       | User unfavorited a Dashboard             |
| Unpaused                          | User resumed automatic updates           |

### Site Search Tracking

Curator also tracks site searches when a user uses the search feature:

* **Google Analytics 4:** Tracked using the built-in `search` event with a `search_term` parameter.
* **Matomo:** Tracked using the `trackSiteSearch` API with the search term, category, and result count.
* **Google Analytics (Universal Analytics):** Tracked as a page view to `/search?q={searchTerm}`. This only
  applies when Beta Search is enabled, since the `/search` route does not exist under the standard search.

### Custom Dimensions

Events include custom dimensions that provide additional context. These dimensions are sent when available:

| Dimension | GA4 Parameter                | Matomo Dimension |
| --------- | ---------------------------- | ---------------- |
| User      | `custom_parameter_user`      | `dimension4`     |
| Value     | `custom_parameter_value_str` | `dimension3`     |
| Workbook  | `custom_parameter_workbook`  | `dimension1`     |
| Worksheet | `custom_parameter_worksheet` | `dimension2`     |

<Note>
  For Matomo, custom dimensions must be configured in your Matomo instance with matching dimension IDs for the
  data to be recorded correctly.
</Note>

## User Identification with `analytics_id`

Curator sends a stable, non-PII UUID called `analytics_id` to GA4, GTM, and Matomo instead of the Curator
username. Usernames are often email addresses or real names, which Google Analytics' Terms of Service
prohibit sending as `user_id`. The `analytics_id` UUID avoids that restriction while still letting
administrators correlate analytics activity to a specific Curator user.

Key points:

* Every Curator frontend user has exactly one `analytics_id`, generated automatically when the user is
  created.
* The value is stable: it never changes for the life of the user record, so dashboards and audiences in
  GA4/Matomo remain consistent across sessions.
* Existing users were backfilled with an `analytics_id` during the upgrade migration, so no manual setup is
  required.

### Correlating an `analytics_id` Back to a Curator User

When you see a UUID in GA4, GTM, or Matomo and need to identify the underlying Curator user, query the
Curator User API. The `analytics_id` is included in the response of:

* `fetchUser` — current logged-in user
* `getUser` — user by token or `user_id`
* `listUsers` — paginated user list (use this to map UUIDs in bulk)
* `/user/info` — mobile auth response

For example, to pull a single page of users and their `analytics_id` values:

```bash theme={null}
curl -H "Authorization: Bearer <api-key>" \
    "https://curator.example.com/api/user/listUsers?num=100&pg=1"
```

Each user entry in the response includes `frontend_user_id`, `name`, `full_name`, `email`, and
`analytics_id`. Match the UUID you saw in GA4/Matomo to the `analytics_id` field to find the user.

For one-off lookups directly against the database, you can also query the `interworks_usermgmt_front_users`
table:

```sql theme={null}
SELECT id, name, full_name, email
FROM interworks_usermgmt_front_users
WHERE analytics_id = '<uuid-from-analytics>';
```

## Internal Logging

In addition to sending events to external analytics platforms, Curator logs all analytics events internally using
its client-side logging utility. These log entries are visible in the browser developer console when client-side
logging is enabled, which can be helpful for verifying that events are firing correctly during setup.

## Limitations

The events listed under [Tracked Events](#tracked-events) are the Dashboard-category interactions Curator sends to
your analytics platforms. Aside from those events, clicks on top-level primary nav file-type menu items also send
a **File / Download** event (see [Navigation and Menu Clicks](#navigation-and-menu-clicks) below). The vertical
side nav is included because it renders through the primary nav template (`menu::primarynav`); the horizontal side
nav is a separate code path that does not emit this event. Other interactions not in the list above are not
reported as Curator analytics events.

### Link Clicks and File Downloads

Curator does not fire its own analytics events for clicks on standard HTML links. File downloads triggered from
file-type menu items are a special case: Curator sends a **File / Download** event for them to some platforms, as
described below. How these interactions are captured depends on the platform:

* **Google Analytics 4 / Google Tag Manager** — Curator does not send link-click or file-download events to GA4
  or GTM. If your GA4 property has **Enhanced Measurement** enabled, GA4 may automatically capture outbound link
  clicks and file downloads. This is a GA4 property-level feature configured in your Google Analytics account,
  not a Curator feature, and its behavior depends entirely on your GA4 configuration.
* **Google Analytics (Universal Analytics)** — Curator does not send link-click events, but it does send a
  **File / Download** event (category `File`, action `Download`) when a user clicks a top-level primary nav
  file-type menu item — including the vertical side nav, which renders through the primary nav template
  (`menu::primarynav`), but not the horizontal side nav — as long as the Universal Analytics tracker (`ga`) is
  loaded. File-type items nested inside dropdown menus do not fire this event.
* **Matomo** — Curator enables Matomo's automatic link tracking and download tracking. Outbound link clicks are
  recorded by Matomo, and downloads — including clicks on top-level primary nav file-type menu items (and the
  vertical side nav, which renders through the primary nav template `menu::primarynav`, but not the horizontal
  side nav) — are tracked for elements Curator tags with the `tracking_download` CSS class. File-type items nested
  inside dropdown menus are not tagged and are not tracked.

Clicks that originate **inside an embedded iframe** — such as links or controls within a Tableau or Power BI
embed — cannot be captured by any script on the Curator page. Embedded dashboards are served from a different
origin, so the browser's same-origin policy prevents Curator's analytics integration, GA4 Enhanced Measurement,
Matomo link tracking, and any other page-level script from seeing interactions inside the frame.

### Navigation and Menu Clicks

Clicks on standard navigation and menu links are not sent as analytics events. Page views are recorded
automatically on each page load, so movement between pages is still reflected in your analytics, but the click
on the menu item itself is not reported as a separate event.

The exception is **top-level primary nav file-type menu items**: these are tagged with the `tracking_download`
CSS class, so a click fires a **File / Download** event (category `File`, action `Download`) to Matomo and to
Universal Analytics. Google Analytics 4 and Google Tag Manager do not receive this event. The vertical side nav
is included because it renders through the primary nav template (`menu::primarynav`); the horizontal side nav is
a separate code path (`sidenav.htm`) that builds menu items without a `url` key, so its file-type test never
resolves and no **File / Download** event fires for it at any depth.

File-type items nested as children under a primary nav parent are rendered through the dropdown template and do
not receive the `tracking_download` class, so no **File / Download** event fires for them.

## Custom Tracking Scripts (e.g., HotJar, FullStory)

Curator does not have built-in settings for session-recording or heatmap tools such as HotJar or FullStory.
You can still add these tools using either of the two mechanisms below.

### Through Google Tag Manager (recommended)

If you have configured a **Google Analytics Tag Manager Container ID** in **Portal Settings > Analytics**, add
the third-party script as a tag inside your GTM container. This keeps every custom script managed in one place.

1. Confirm a **Google Analytics Tag Manager Container ID** is set in **Portal Settings > Analytics**.
2. In your GTM container, create a new **Custom HTML** tag and paste in the tool's tracking snippet.
3. Set the tag's trigger to **All Pages**.
4. Submit and publish the GTM container.

### Through the theme Head Insert

If you are not using Google Tag Manager, you can paste a tracking snippet directly into the **Head Insert** field
found under the theme's custom styles settings in the Curator backend. The contents of this field are rendered
inside the `<head>` of every page. This is a good fit when you only need to add a single script and do not want
to set up a GTM container.

1. On the theme's **Global** tab, turn on **Enable Custom Styles (CSS / HTML inserts)**. This toggle is off by
   default. While it is off, the **Head Insert** field's label gains a **(Disabled)** suffix and a warning comment
   is shown beneath it; content pasted there is still not applied to the page until the toggle is on.
2. Open the **Custom Styles** tab (it is always visible) and paste the tool's tracking snippet into the
   **Head Insert** field.
3. Save the theme.

<Note>
  The **Head Insert** field is parsed as Twig before it is emitted into the page, so any `{{`, `{%`, or `{#`
  sequences in a pasted vendor snippet are interpreted as Twig rather than passed through as literal text. If your
  snippet contains those sequences (for example, a templating library's own placeholder syntax), it will not render
  verbatim and may fail silently. Add the script through Google Tag Manager instead, or escape the Twig delimiters
  using `{% verbatim %}...{% endverbatim %}`.
</Note>

<Note>
  Both approaches inject the tool's own script into the page. As with Curator's built-in analytics, these scripts
  run on the Curator page itself and cannot observe interactions inside embedded Tableau or Power BI iframes.
</Note>


# Overview
Source: https://docs.curator.interworks.com/site_administration/backend_administrators/overview

Manage backend administrator accounts, permissions, and access levels separate from Tableau Server users.

Backend Administrators accounts are separate from Tableau Server users and only exist on Curator.
Permissions can be customized for a backend user to allow for a range of access.
New permissions become available as you enable "Features" and must be enabled for older users if applicable.

**To manage backend users:**

1. If a backend user is unable to view menu items, it is possible they do not have the appropriate backend
   permissions. These permissions can be edited using the following steps. If the "Backend Administrators" menu
   item is not visible, it is likely that user does not have the necessary permissions. A backend admin with
   access to "Backend Administrators" will need to update the permissions for the other user.
2. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
3. Log in if prompted.
4. Click on **Settings** > **Curator** > **Backend Administrators** in the left navigation.
5. Click on the "New Backend User" button to create a new user, or click on an existing user to modify user details or permissions.

<Warning>
  When creating a new user, the **Send Account Creation Email** toggle (enabled by default) sends a notification
  email to the new administrator with their account details. Disable it to skip the email for that user, which is
  useful when you intend to share credentials with the new administrator out-of-band.
</Warning>

<Note>
  The **Password** and **Confirm Password** fields each have an eye icon at their right edge. Click it to reveal what
  you have typed, and click it again to hide it. This only ever shows text you typed in the current session --
  both fields are always empty when the form loads, so an existing password is never revealed.
</Note>

## SAML Integration

Curator can integrate backend users with the same SAML authentication that is being used on the front-end.
In order for this to work, set up your environment following the steps below:

1. Ensure your [SAML authentication](/setup/authentication/okta_saml)
   has been set up properly.
2. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
3. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
4. Click on the **General** tab and expand the Security section.
5. Toggle the switch to enable "Force Backend Users to Login Via Frontend Authentication Forms" then click save

After this you can create users normally, and when they visit the backend of Curator they will be redirected
to log in via SAML, then re-routed to the backend.
*Note:* You can create backend users as normal following the steps above (including a password)
however users will not be able to log in via these credentials due to *Force Backend Users to Login Via
Frontend Authentication Forms* being enabled.
Only backend usernames matching frontend usernames will be able to access Curator's administrative interface.
Compare the two by checking the Frontend User section and Backend User section.

### Using Frontend Users as Backend Users

Curator can use the same Portal Settings as SAML to allow Frontend Users to login to the backend as well.
This will restrict backend users who don't have a corresponding frontend user.
In order for this to work, set up your environment following the steps below:

1. Ensure your chosen Authentication Type is set up properly, and sign in with a frontend user of your choice.
2. Create a backend user with account info that matches the frontend user you just used.
3. Sign out of both the frontend and the backend.
4. Login to only the frontend with the corresponding account.
5. Go to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
6. It should sign you in automatically.  You should then enable *Force Backend Users to Login Via
   Frontend Authentication Forms*.
7. This should enable frontend users to sign into the backend automatically with the same account.
   *Note:* In order to access the backend, a given frontend user will have to have a backend account manually made
   by an existing backend user.

## Backend Preferences

Each backend administrator has personal preferences that can be configured by clicking on their name in the top-right
corner of the backend and selecting **My Account**, then navigating to the **Preferences** tab.

### Timezone

The **Timezone** preference controls how dates and times are displayed in the backend interface for that specific
administrator. For example, datetime picker fields (such as the Cron Debug Mode expiration) will display times
converted to this timezone.

<Warning>
  This setting only affects the display of dates and times in the backend UI. It does not affect when cron jobs run or
  when Scheduled Reports are delivered. Those are controlled by the
  [Cron Timezone](/embedding_using_analytics/report_builder/scheduled_reports#global-cron-timezone) setting in Portal
  Settings.
</Warning>

### Locale

The **Locale** preference controls the language used in the backend interface for that administrator.

### Appearance

The **Appearance** control sets whether the backend uses a light or a dark color scheme. Unlike Timezone and Locale,
it lives in the account dropdown itself rather than the **Preferences** tab: click your name in the top-right corner
of the backend and the control appears above **Sign out**.

It offers three options, and clicking one applies it immediately:

| Option     | Behavior                                                                         |
| ---------- | -------------------------------------------------------------------------------- |
| **System** | Follows the light or dark setting of your operating system. This is the default. |
| **Light**  | Always uses the light color scheme, whatever your operating system is set to.    |
| **Dark**   | Always uses the dark color scheme, whatever your operating system is set to.     |

<Note>
  This choice is remembered per browser rather than on your administrator account, so it does not follow you to a
  different browser or device. Setting it on your laptop will not change the backend's appearance when you sign in from
  another computer.
</Note>


# Password Reset 
Source: https://docs.curator.interworks.com/site_administration/backend_administrators/password_reset

Reset backend administrator passwords through self-service or administrative override when access is lost.

Forget your backend administrator password?

A Curator backend administrator user's password can easily be reset by other users who have Backend User access.

## No one left to reset your password?

If there is no one else with administrative access to the system, the account can also be reset using the steps below.

1. Connect to the server running Curator. (Windows: RDP, or with Linux: SSH)

2. Open a command prompt \[Windows Only, Linux will start in a command prompt.]

3. Change to the webroot directory where Curator is installed.
   Here are some examples:

   * **Windows (Apache: Standard):**

     ```Apache theme={null}
     cd C:\InterWorks\Curator\htdocs;
     ```

   * **Windows (IIS: Legacy):**

     ```Windows theme={null}
     cd C:\InterWorks\Curator\wwwdata;
     ```

   * **Linux:**

     ```Linux theme={null}
     cd /var/www/html;
     ```

4. Run "artisan" to reset the administrative user:

   ```PHP theme={null}
   php artisan winter:passwd
   ```


# Backend Administrator Permissions
Source: https://docs.curator.interworks.com/site_administration/backend_administrators/permissions

Reference for all available backend administrator permissions and what each one controls.

Each backend administrator can be assigned a subset of permissions to limit their access to only the areas they need.
Permissions are set per-user from **Settings** > **Curator** > **Backend Administrators**.

Some permissions are only visible when certain features or integrations are enabled on your Curator instance. So in
case you don't see the corresponding menu item on the left-hand navigation, it is because you don't have that feature currently enabled.

## Central Dispatch

| Permission                         | Description                                                                              |
| ---------------------------------- | ---------------------------------------------------------------------------------------- |
| **Central Dispatch Administrator** | Full access to all Central Dispatch features for managing distributed Curator instances. |
| **Managed Instance Cache**         | Manage cache operations across managed Curator instances.                                |
| **Managed Instance Upgrades**      | Manage software upgrades across managed Curator instances.                               |

## Content

| Permission                  | Description                                                    |
| --------------------------- | -------------------------------------------------------------- |
| **Manage External Feed**    | Configure external data feeds.                                 |
| **Manage Files**            | Upload and manage media files and documents.                   |
| **Manage Fonts**            | Upload and manage custom fonts.                                |
| **Manage Keywords**         | Manage searchable keywords and tags.                           |
| **Manage Loading Screens**  | Configure loading screen messages and visuals.                 |
| **Manage Navigation**       | Configure menus and navigation structure.                      |
| **Manage Notices**          | Create and manage system-wide notices shown to frontend users. |
| **Manage Pages**            | Create and edit static content pages in the portal.            |
| **Manage Terms of Service** | Edit and publish the Terms of Service agreement.               |
| **Manage Tutorials**        | Create and manage in-portal tutorial content.                  |

## Data Manager

| Permission                | Description                                                   |
| ------------------------- | ------------------------------------------------------------- |
| **Manage Data**           | View, add, edit, and delete Data Manager records.             |
| **Manage Data Structure** | Define and modify Data Manager schemas and field definitions. |

## Integration

| Permission             | Description                                                     |
| ---------------------- | --------------------------------------------------------------- |
| **Manage API Relay**   | Configure the API relay for proxying requests to external APIs. |
| **Manage Commands**    | Create and configure scheduled or event-driven commands.        |
| **Manage Connections** | Configure connections to external services.                     |
| **Manage Scripts**     | Create and edit integration scripts.                            |
| **Run Commands**       | Execute commands manually.                                      |
| **Run Scripts**        | Execute integration scripts manually.                           |

## Security

| Permission                         | Description                                              |
| ---------------------------------- | -------------------------------------------------------- |
| **Manage Authentication Settings** | Configure authentication methods including SSO and SAML. |

## Curator

| Permission                  | Description                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| **Manage API Keys**         | Create, view, and revoke API keys for external integrations.                                   |
| **Manage Curator Settings** | Edit global platform settings, including general configuration, branding, and feature toggles. |
| **Manage Curator Updates**  | View and apply software updates.                                                               |
| **Manage URL Redirects**    | Configure URL redirect rules within the portal.                                                |

### MCP Tokens

MCP tokens need no dedicated permission. Every backend user can generate, edit, and revoke their own tokens
from **MCP Tokens** in the username dropdown. A token can only do what its owner can do, and each MCP tool
checks the owner's permissions when it runs. See [MCP](/curator_api/api_docs/mcp).

## Power BI

| Permission                 | Description                                       |
| -------------------------- | ------------------------------------------------- |
| **Power BI Administrator** | Full access to all Power BI integration features. |

## Sigma

| Permission              | Description                                    |
| ----------------------- | ---------------------------------------------- |
| **Sigma Administrator** | Full access to all Sigma integration features. |

## Tableau

| Permission                    | Description                                                           |
| ----------------------------- | --------------------------------------------------------------------- |
| **Manage Tableau Dashboards** | Add, edit, and organize Tableau content in the portal.                |
| **Manage Tableau Settings**   | Configure the Tableau Server or Tableau Cloud connection.             |
| **Manage Tableau Users**      | Manage Tableau user provisioning and portal-to-Tableau user mappings. |
| **Tableau Status**            | View the Tableau server status page.                                  |

## ThoughtSpot

| Permission                    | Description                                          |
| ----------------------------- | ---------------------------------------------------- |
| **Manage ThoughtSpot Users**  | Manage ThoughtSpot user provisioning and access.     |
| **ThoughtSpot Administrator** | Full access to all ThoughtSpot integration features. |

## Translator

| Permission                   | Description                                         |
| ---------------------------- | --------------------------------------------------- |
| **Translator Administrator** | Full access to all Translator integration features. |

## User Management

| Permission                   | Description                                                                                                     |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Manage Backend Users**     | Create, edit, and delete backend administrator accounts and their permissions. Required to manage other admins. |
| **Manage Frontend Users**    | Create, edit, and delete frontend (end-user) accounts.                                                          |
| **Manage SAML IdP Settings** | Configure SAML Identity Provider settings for single sign-on.                                                   |

## System

| Permission                     | Description                                                       |
| ------------------------------ | ----------------------------------------------------------------- |
| **Manage Backend Preferences** | Manage backend preferences and settings like Locale and timezone. |
| **Manage Mail Settings**       | Configure outgoing mail server settings.                          |
| **Manage Mail Templates**      | Edit email templates used for system notifications.               |
| **View System Logs**           | Access system, event, and error logs.                             |


# Updating License Key 
Source: https://docs.curator.interworks.com/site_administration/license_key/updating_license_key

Update or add your Curator license key for new installations, migrations, or license renewals.

Adding or updating your license key is only required for new installations, or migrations that have failed to
carry over your license key.  Typical license keys are allowed on up to 3 instances so long as only one
instance is used for Production.  If you'd like to deploy multiple Curator sites, please talk to your Account
Executive about our Enterprise offering.

<Note>
  If you are reactivating your license as part of moving Curator onto new server hardware, see
  [Moving Curator to a New Server](/upgrading_migration/migration/moving_to_a_new_server) for the full sequence
  this step belongs to.
</Note>

## How to Update your License Key

In order to add or update your license key, follow the steps below:

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).

2. Navigate to the **Settings** > **Curator** > **System Upgrade** section from the left-hand menu.

3. Click on the pencil "Update Key" link

   <img alt="update key link" />

4. Enter your license key and click "Save".

## Troubleshooting

If the license key fails to activate, work through the following checks to ensure your license is valid:

1. **Check your active instance count.** Standard license keys cover up to 3 instances (with only one in Production).
   If you have retired an older instance — for example after a server migration — it may still count against the
   limit.
   <Tip>Contact support to deregister the retired instance, or talk to your Account Executive about upgrading to our Enterprise offering if you need to run more than 3 instances concurrently. </Tip>
2. **Copy and paste the key exactly.** Retyping the key by hand is the most common cause of activation failures.
   Paste the key directly from the email or portal where you received it, and confirm there are no leading or
   trailing spaces.
3. **Verify via CLI.** If the Curator backend is unavailable or inaccessible — for example on a fresh install that
   has not yet been fully configured — set the key from the command line instead:

   ```bash theme={null}
   php artisan curator:setkey your-license-key
   ```

If none of the above resolves the issue, [contact support](http://interworks.com/help). Please make sure to
include your Curator version, the license key you are attempting to activate, the URL of the instance,
and a screenshot of any error messages shown in the backend.


# Backend Logs
Source: https://docs.curator.interworks.com/site_administration/logging/database_logs

Database-stored logs accessible through the Curator backend including Usage Log, Event Log, Access Log, and Alert Log.

Backend logs are stored in the Curator database and can be viewed through the Curator backend interface. These
logs are designed for day-to-day monitoring and auditing by administrators who may not have direct server access.

## Usage Log

The Usage Log serves as an audit trail for your Curator instance, tracking who made what changes and when.
This includes configuration changes, content modifications, user management actions, and administrative
operations. The Usage Log is essential for compliance, security auditing, and troubleshooting issues
caused by configuration changes.

### Viewing the Usage Log

1. <BackendNavPath />
2. Use the filters to search for specific users, date ranges, or action types.

### Usage Log Retention

The Usage Log retention period can be configured in Portal Settings:

1. <BackendNavPath />
2. Find the **Usage Log Retention** setting.
3. Select the desired retention period (1 Month, 3 Months, 6 Months, or 12 Months).
4. Click **Save**.

Older usage log entries will be automatically purged based on this setting.

## Event Log

The Event Log records system events including errors, warnings, informational messages, and debug output.
This is the primary log for troubleshooting issues with your Curator instance.

<Tip>
  The Event Log is stored in the database and mirrors the file-based System Log. In rare cases where
  event log entries appear to be missing, the [System Log](/site_administration/logging/file_based_logs#system-log)
  may contain additional information.
</Tip>

### Debug Modes

Curator provides several debug modes that can drastically increase the amount of logging in the Event Log.
These modes are useful for troubleshooting specific integrations or features:

* [Tableau Debug Mode](/creating_integrations/tableau_connection/tableau_connection_troubleshooting#how-to-enable-debug-mode) - Detailed logging for Tableau Server/Cloud communication
* [Power BI Debug Mode](/creating_integrations/power_bi_connection/troubleshooting_power_bi_access#enable-debug-mode) - Detailed logging for Power BI integration
* **Cron Debug Mode** - Detailed logging for scheduled tasks
* And others depending on your enabled features

Debug modes should typically only be turned on temporarily while troubleshooting, as they can
significantly increase the volume of log entries.

### Viewing the Event Log

1. <BackendNavPath />
2. Click on any entry to view its details, including the full message and any associated context data.

### Redacted Values

Curator automatically removes sensitive values from Event Log entries before they are saved. Passwords,
password reset keys, session cookies, API keys, and authorization headers are replaced with `[redacted]`
in both the entry message and its detail data.

This happens for every entry, whichever part of Curator recorded it, so `[redacted]` appearing in place of
a value is expected and does not indicate a problem. If you are troubleshooting an issue that depends on
one of these values, reproduce it with a test account rather than looking for the original value in the log.

<Note>
  Redaction was added in Curator **2026.08-03**. Entries recorded before you upgraded may still contain
  sensitive values.
</Note>

### Download Debug Package

The Event Log page includes a **Download Debug Package** button that bundles various logs and system
information into a single downloadable archive. This package is useful when reporting issues to
InterWorks Support, as it includes:

* Recent event log entries
* System log files
* System configuration information

To download the debug package, click the **Download Debug Package** button in the toolbar on the Event Log page.

The logs in this package carry the same redaction described above, so credentials are not included in what
you send to InterWorks Support.

### Event Log Retention

The Event Log retention period can be configured in Portal Settings:

1. <BackendNavPath />
2. Find the **Event Log Retention** setting.
3. Select the desired retention period:
   * **Never (Manual)** - Logs are not automatically purged; use the Event Log interface to manually clear entries
   * **1 Week** - Entries older than 7 days are automatically purged
   * **2 Weeks** - Entries older than 14 days are automatically purged
   * **1 Month** - Entries older than 30 days are automatically purged
   * **3 Months** - Entries older than 90 days are automatically purged
4. Click **Save**.

When automatic purging is enabled, old event log entries are removed daily at 2:00 AM (server timezone).

## Access Log

The Access Log tracks backend administrator logins and activity. This is useful for security auditing and
compliance purposes.

### Viewing the Access Log

1. <BackendNavPath />
2. Review administrator access history including login times and IP addresses.

## Alert Log

The Alert Log aggregates recurring system alerts into a single, manageable view. Rather than creating
duplicate event log entries for the same recurring issue, the Alert Log consolidates these alerts and
tracks how many times they have occurred.

### Viewing the Alert Log

Alert Log entries are displayed in two locations:

1. **Status Page** - <BackendNavPath /> Here you can see active alerts alongside other system health information.

2. **Alert Log List** - <BackendNavPath /> This provides a detailed view where you can:
   * View all active, resolved, and suppressed alerts
   * See occurrence counts and timestamps
   * Mark alerts as resolved or suppressed
   * Clear alerts in bulk

### Alert Statuses

* **Active** - The alert is current and requires attention
* **Resolved** - The underlying issue has been addressed
* **Suppressed** - The alert has been acknowledged but hidden from the active view

## Tracking end-user content views

The logs above are scoped to administration. The Usage Log records configuration and content changes, the
Event Log records system events and errors, and the Access Log records backend administrator logins. None of
them record which frontend user opened which Tableau, Power BI, or other BI Dashboard. If you are asked for
a "who viewed what" report, use one of the sources below instead.

### Curator Activity page

Curator writes one content view record each time a frontend user opens a piece of content, including Tableau
Dashboards, Power BI Reports, Pages, and Files. The [Activity](/site_administration/activity/activity_overview)
page charts those records and can be filtered by date range, content item, and user.

<BackendNavPath />

To export the underlying records, read the `interworks_usermgmt_content_view` table through the Curator API.
Each row holds the username, the content type and ID, the requested path, and a timestamp. See
[Retrieving Usage Data](/site_administration/activity/retrieving_usage_data).

### Analytics Tracking

If you already use Google Analytics 4, Google Tag Manager, or Matomo, connect it under
**Portal Settings > Analytics**. Curator then sends page views and Dashboard interaction events, such as
filter changes and exports, to that platform and tags each one with the logged-in user's `analytics_id`.
That value is a non-personal UUID rather than the username, and the User API lets you map it back to a
Curator user. See [Analytics Tracking](/site_administration/analytics_tracking/analytics_tracking).

### BI platform audit logs

The BI platform keeps its own access records, and those cover every client, not only Curator. For Tableau,
the administrative views and the Tableau Server repository report which user viewed which view or workbook.
For Power BI, the Power BI activity log and the Microsoft Purview audit log record per-user report access.
Depending on how Curator authenticates to the BI platform, those records may attribute a view to the account
Curator embeds with rather than to the individual user, so use Curator's own content view records when you
need the Curator username.


# Server Logs
Source: https://docs.curator.interworks.com/site_administration/logging/file_based_logs

File-based logs on the Curator server including the System Log, PHP error log, and Apache error log.

Server logs are stored as files on the Curator server and require direct server or file system access to view.
These logs are typically used for deeper troubleshooting, especially when database connectivity issues prevent
backend access or when investigating web server configuration problems.

## System Log

The System Log is Curator's primary application log, recording system events, errors, warnings, and debug
information. This log mirrors much of the same information found in the
[Event Log](/site_administration/logging/database_logs#event-log), but writes directly to disk rather than
the database.

<Note>
  The System Log can be particularly useful when the Event Log is unavailable (such as during database
  connectivity issues) or when troubleshooting errors that may not appear in the Event Log. In some cases,
  database transaction rollbacks can prevent Event Log entries from being saved, but the corresponding
  System Log entries will still be present.
</Note>

### Log File Location

The default System Log locations are:

| Operating System | Default Path                                 |
| ---------------- | -------------------------------------------- |
| Linux            | `/var/www/html/storage/logs/`                |
| Windows          | `C:\InterWorks\Curator\htdocs\storage\logs\` |

<Note>
  These paths may vary based on your installation. Central Dispatch installations, custom installation
  directories, or different Windows drive letters will affect the actual location. The log files are
  always located in the `storage/logs/` directory relative to your Curator installation root.
</Note>

### Log File Format

By default, Curator uses daily log rotation, creating files named `system-YYYY-MM-DD.log`. For example:

* `system-2025-01-15.log`
* `system-2025-01-14.log`

### Redacted Values

Curator automatically removes sensitive values before they are written to the System Log. Passwords,
password reset keys, session cookies, API keys, and authorization headers are written as `[redacted]`,
whether they appear in the log message itself or in the context data recorded alongside it.

The same redaction is applied to the [Event Log](/site_administration/logging/database_logs#event-log), so
a value hidden in one log is hidden in the other. Seeing `[redacted]` in place of a value is expected and
does not indicate a problem.

<Note>
  Redaction was added in Curator **2026.08-03**. Log files written before you upgraded may still contain
  sensitive values.
</Note>

### Log Rotation Configuration

File-based log retention is configured separately from the database log retention settings. The number of
log files retained and other logging behavior is controlled by the `config/logging.php` configuration file.

If your log files are consuming excessive disk space or not rotating properly, refer to the
[Updating Curator Logging](/server_management/system_administration/updating_curator_logging) guide for
configuration instructions.

## PHP Error Log

The PHP error log captures PHP runtime errors, warnings, and notices that occur outside of Curator's
application logging. This can include syntax errors, memory issues, and extension-related problems that
may prevent Curator from starting properly.

### Log File Location

The PHP error log location depends on your server configuration:

| Operating System | Default Path                                                 |
| ---------------- | ------------------------------------------------------------ |
| Linux            | `/var/log/php-fpm/www-error.log` or `/var/log/php/error.log` |
| Windows          | `C:\InterWorks\Curator\php_error.log`                        |

<Note>
  The actual location may vary based on your PHP and web server configuration. To find the exact path,
  check the `php_ini_path` field returned by the
  [/portal/info](/curator_api/api_docs/curator_api#portalinfo) endpoint.
</Note>

### Common PHP Errors

| Error Type  | Description                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------ |
| Fatal Error | Critical errors that halt script execution (e.g., missing required files, syntax errors)         |
| Warning     | Non-fatal issues that may indicate problems (e.g., missing optional files, deprecated functions) |
| Notice      | Minor issues that don't affect functionality (e.g., undefined variables)                         |

### Viewing PHP Configuration

To find your PHP error log location and other settings:

```bash theme={null}
# Linux
php -i | grep error_log

# Or check the loaded php.ini file
php --ini
```

## Apache Error Log

The Apache error log records web server errors, including failed requests, configuration issues, and
module errors. This log is essential for diagnosing issues with SSL certificates, URL rewrites, and
server connectivity.

### Log File Location

| Operating System | Default Path                                               |
| ---------------- | ---------------------------------------------------------- |
| Linux            | `/var/log/httpd/error_log` or `/var/log/apache2/error.log` |
| Windows          | `C:\InterWorks\Curator\libs\apache\logs\error.log`         |

<Note>
  The location varies based on your Linux distribution. RHEL/CentOS typically use `/var/log/httpd/`,
  while Debian/Ubuntu use `/var/log/apache2/`.
</Note>

### Apache Access Log

In addition to the error log, Apache maintains an access log that records all HTTP requests to the server.
This can be useful for:

* Tracking request patterns
* Identifying slow requests
* Debugging authentication issues
* Monitoring for suspicious activity

| Operating System | Default Path                                                 |
| ---------------- | ------------------------------------------------------------ |
| Linux            | `/var/log/httpd/access_log` or `/var/log/apache2/access.log` |
| Windows          | `C:\InterWorks\Curator\libs\apache\logs\access.log`          |

### Common Apache Errors

| Error                     | Description                                  |
| ------------------------- | -------------------------------------------- |
| 403 Forbidden             | Permission denied to access a resource       |
| 404 Not Found             | Requested file or page does not exist        |
| 500 Internal Server Error | Server-side error, often a PHP fatal error   |
| 502 Bad Gateway           | PHP-FPM or backend service not responding    |
| 503 Service Unavailable   | Server temporarily unable to handle requests |

## Troubleshooting Workflow

When troubleshooting issues with Curator, check logs in this order:

1. **Event Log** - Start with the backend Event Log for application-level errors
2. **System Log** - Check for entries that may not have been saved to the Event Log
3. **PHP Error Log** - Look for PHP runtime errors that prevent Curator from functioning
4. **Apache Error Log** - Check for web server configuration or connectivity issues

<Tip>
  When reporting issues to InterWorks Support, providing relevant excerpts from all applicable logs
  can significantly speed up diagnosis and resolution.
</Tip>


# Log Rate Limiter
Source: https://docs.curator.interworks.com/site_administration/logging/log_rate_limiter

How Curator prevents the Event Log from being flooded by repeated identical messages, and what to expect when rate limiting is active.

Curator automatically prevents the Event Log from being flooded by repeated identical errors or warnings.
When the same message occurs many times in a short period, Curator begins suppressing duplicates and
periodically logs a summary entry instead. This keeps the Event Log readable and performant without
losing visibility into ongoing issues.

## How it works

1. **First 20 occurrences are always logged** — every unique message is allowed through at least 20 times.
   A full page of identical entries in the Event Log is a clear signal that something is actively failing.
2. **Suppression begins after the 20th occurrence** — if the same message keeps appearing, Curator starts
   holding back duplicates.
3. **Periodic summary entries** — rather than silently discarding messages, Curator logs a summary at
   increasing intervals. Each summary entry is prefixed with `[Grouped]` and includes a count of
   how many duplicate entries were hidden and when the message first appeared. That count covers only
   the hidden duplicates, not the occurrences that were logged normally.
4. **Intervals double over time** — summaries appear at 2 minutes, then 4, 8, 16, 32, and cap at every
   60 minutes for as long as the issue persists.

Rate limiting state resets after 24 hours of inactivity per message type.

## What a rate-limited entry looks like

A normal Event Log entry:

```
[error] Connection to upstream API failed
```

Once rate limiting is active, subsequent entries look like this:

```
[error] [Grouped] Connection to upstream API failed
        _grouped_summary: "Curator hid 239 duplicate Event Log entries for this message since
        2026-03-11 09:00:10, so this entry stands in for them. Grouping duplicates keeps the log
        readable; the activity itself was not blocked or limited."
```

The `[Grouped]` prefix is searchable in the Event Log. Use it to quickly find any messages
that have been suppressed.

<Note>
  `[Grouped]` describes the Event Log entry, not the activity it reports. It means Curator folded the
  duplicate lines into a single entry with a count. Nothing about the underlying operation is blocked,
  throttled, or limited, and there is no setting to raise or lower.
</Note>

## Examples

### Runaway error

Without rate limiting, a continuous error at 2 per second would produce 7,200 Event Log entries per hour.
Here is what you would actually see:

| Elapsed            | What appears in the Event Log                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| 0 – 10 s           | Occurrences 1–20 logged normally. A full page of identical entries signals a problem.                              |
| 10 s               | First `[Grouped]` entry logged. Suppression window: **2 min**.                                                     |
| 10 – 130 s         | \~239 occurrences suppressed.                                                                                      |
| 130 s              | Summary logged: "Curator hid 239 duplicate Event Log entries … since 09:00:10". Window: **4 min**.                 |
| 370 s              | Summary logged. Window: **8 min**.                                                                                 |
| 850 s              | Summary logged. Window: **16 min**.                                                                                |
| 1,810 s            | Summary logged. Window: **32 min**.                                                                                |
| 3,730 s            | Summary logged. Window caps at **60 min**.                                                                         |
| Every 60 min after | One summary per window; the count grows each window — it is the cumulative total since the message first appeared. |

**Result:** 7,200 entries/hour reduced to \~26, with each summary carrying the full suppression details.

### Intermittent error

If the same message appears only occasionally — say, 10 times over 10 minutes — it will never hit the
suppression threshold. All 10 occurrences are logged normally and the `[Grouped]` prefix will never appear.

| Error frequency | Threshold reached  | Rate limiting active?              |
| --------------- | ------------------ | ---------------------------------- |
| 2 / second      | After \~10 seconds | Yes                                |
| 1 / minute      | After \~20 minutes | Yes, if it continues               |
| 1 / hour        | After \~20 hours   | Yes, just before the 24-hour reset |
| 1 / day         | Never              | No                                 |

## Limitations and caveats

* **The Event Log is not a complete audit trail** — because suppressed occurrences are not stored, the
  Event Log should not be used to count how many times something happened or as an authoritative record
  of security-related events. Use Curator's Usage Log or an external audit system for that purpose.
* **Some messages are never rate-limited** — errors that include dynamic information (such as a user
  name, record ID, or timestamp) in the message text are treated as distinct messages and are each
  logged individually, regardless of frequency. This is expected behavior.


# Logging Overview
Source: https://docs.curator.interworks.com/site_administration/logging/logging_overview

Understanding Curator logging systems including usage logs, event logs, access logs, and alert logs.

Curator provides several logging systems to help administrators monitor, troubleshoot, and audit their Curator
instance. Logs are available through both the Curator backend interface and directly on the server file system.

## Types of Logs

Curator maintains several different log types, each serving a specific purpose:

| Log Type                                                                          | Purpose                                     | Access             |
| --------------------------------------------------------------------------------- | ------------------------------------------- | ------------------ |
| [Usage Log](/site_administration/logging/database_logs#usage-log)                 | Audit trail of who made what changes        | Curator Backend    |
| [Event Log](/site_administration/logging/database_logs#event-log)                 | Records system events, errors, and warnings | Curator Backend    |
| [Access Log](/site_administration/logging/database_logs#access-log)               | Logs backend administrator access           | Curator Backend    |
| [Alert Log](/site_administration/logging/database_logs#alert-log)                 | Aggregates recurring system alerts          | Curator Backend    |
| [System Log](/site_administration/logging/file_based_logs#system-log)             | Detailed application logs for debugging     | Server File System |
| [PHP Error Log](/site_administration/logging/file_based_logs#php-error-log)       | PHP runtime errors and warnings             | Server File System |
| [Apache Error Log](/site_administration/logging/file_based_logs#apache-error-log) | Web server errors and access information    | Server File System |

## Backend Logs vs Server Logs

**[Backend Logs](/site_administration/logging/database_logs)** are stored in the Curator database and accessible
through the Curator backend interface. These logs are designed for day-to-day monitoring and auditing by
administrators who may not have direct server access.

**[Server Logs](/site_administration/logging/file_based_logs)** are stored as files on the server and require
direct server or file system access. These logs are typically used for deeper troubleshooting, especially when
database connectivity issues prevent backend access or when investigating web server configuration problems.

## API Access

Curator provides API endpoints for programmatic access to log data. All API endpoints require a valid API key.
For general information about using the Curator API, see the
[Curator API Overview](/curator_api/getting_started/curator_api_overview).

### List Event Log

Returns event log entries with pagination support.

```
GET /api/v1/portal/listEventLog?apikey=YOUR_API_KEY
```

**Parameters:**

* `limit` (optional) - Maximum number of results to return (default: 1000)
* `offset` (optional) - Number of results to skip for pagination (default: 0)

### List Usage Log

Returns usage log entries with filtering options.

```
GET /api/v1/portal/listUsageLog?apikey=YOUR_API_KEY
```

**Parameters:**

* `limit` (optional) - Maximum number of results to return (default: 1000)
* `offset` (optional) - Number of results to skip for pagination (default: 0)
* `username` (optional) - Filter results by username
* `is_frontend` (optional) - Filter by frontend (`true`), backend (`false`), or both (omit parameter)

### List Alert Log

Returns alert log entries with filtering options.

```
GET /api/v1/portal/listAlertLogs?apikey=YOUR_API_KEY
```

**Parameters:**

* `limit` (optional) - Maximum number of results to return (default: 1000)
* `offset` (optional) - Number of results to skip for pagination (default: 0)
* `status` (optional) - Filter by status: `active`, `resolved`, `suppressed`
* `level` (optional) - Filter by level: `error`, `warning`, `info`

### Download System Log

Downloads the current system log file.

```
GET /api/v1/portal/downloadLog?apikey=YOUR_API_KEY
```

This endpoint returns the `storage/logs/system.log` file as a downloadable attachment.

## Best Practices

1. **Set appropriate retention periods** - Balance the need for historical data against database storage
   requirements. For most installations, 1-3 months of event log retention is sufficient.

2. **Monitor the Alert Log** - Regularly review the Status page to catch recurring issues early.

3. **Archive logs before purging** - If compliance requirements mandate long-term log retention, use the API
   endpoints to export log data before automatic purging occurs.

4. **Review Access Logs periodically** - Regular review of administrator access helps identify unauthorized
   access attempts.

5. **Check multiple log sources** - When troubleshooting issues, check both backend logs and server logs for
   a complete picture. The System Log may contain entries not present in the Event Log.


# Cache Warming 
Source: https://docs.curator.interworks.com/site_administration/performance/cache_warming

Configure cache warming to improve initial page load times for designated user groups through automated cache preloading.

Later page load times are much quicker than the first load due to caching. The "Cache Warming" feature allows
a group of users to have their cache warmed every hour. This improves their first page load and avoids that
initial long wait for the page to render when logging in.

## Enabling the Cache Warming Feature

1. Navigate to your Curator backend > Settings > Curator > Portal Settings > Features tab.
2. Enable the “Cache Warming” feature at the top of the Functionality section.
3. In the "Priority Group for Cache Warming" field, choose a Frontend Group with less than 200 members. The
   options should already be limited to applicable groups. For more information about creating Frontend Groups,
   visit [the doc](/users_groups/user_management/users_and_groups_overview).
4. Hit "Save."

## Notes

* Every hour the members of the chosen group will have their cache warmed. This is ran every hour in case
  another process has cleared the cache such as logging out or making a configuration change.
* The group has to contain less than 200 members because the process to warm the cache is intensive. Warming
  for more than 200 members might bog down the queue that runs scheduled processes, preventing other important
  functions to run.

## Common Cache Log Errors

Cache warming runs asynchronously for each user in the Priority Group, so it is normal to see warming-related
entries in the [System Log](/site_administration/logging/file_based_logs#system-log). The entries below cover
what is non-fatal and what requires action.

### "Failed to warm cache for user X"

A single `Failed to warm cache for user X` entry is non-fatal and affects only that user's next page load.
The most common cause is a transient platform API timeout (for example, a slow response from Tableau Server,
Power BI, or ThoughtSpot during the warming pass). The affected user will simply experience the normal
uncached first-page-load time on their next visit, after which their cache will be populated as usual.

No action is required unless the same user fails to warm on multiple consecutive runs, in which case
investigate the upstream platform's availability and response times for that user's content.

### Repeated OOM (Out Of Memory) Failures During Warming

If the System Log contains repeated out-of-memory failures originating from the cache warming job — for
example, PHP fatal errors mentioning `Allowed memory size of N bytes exhausted` inside the warming
schedule — the configured Priority Group for Cache Warming exceeds the memory budget available to the
queue worker on this server.

To resolve this, do one of the following:

1. Reduce the size of the Priority Group for Cache Warming so the cumulative cost of warming all members
   fits within the queue worker's memory budget.
2. Move only the highest-priority users into the group and accept the normal uncached first-page-load
   time for everyone else.
3. As a temporary measure while right-sizing the group, enable the **Disable All Cache Warming** toggle on
   the same Portal Settings screen so the warming job stops running entirely until the group is reduced.


# Performance Diagnostics
Source: https://docs.curator.interworks.com/site_administration/performance/performance_diagnostics

Guide for collecting system performance data to help the Curator support team diagnose and resolve slow performance issues.

When experiencing slow performance with Curator, collecting detailed system information helps the support team identify
the root cause. Follow these steps to gather the necessary diagnostic files.

## Step 1: Collect Server Performance Data

Connect to your Curator server via SSH (Linux) or RDP (Windows), then run the performance script for your operating
system to generate a comprehensive report of your server's configuration, performance metrics, and usage statistics.

<Tabs>
  <Tab title="Linux Servers">
    ```bash theme={null}
    curl -o /tmp/curator_server_info.sh "https://api.curator.interworks.com/scripts/curator_server_info.sh";
    chmod +x /tmp/curator_server_info.sh && /tmp/curator_server_info.sh
    ```
  </Tab>

  <Tab title="Windows Servers">
    ```powershell theme={null}
    Invoke-WebRequest -Uri "https://api.curator.interworks.com/scripts/curator_server_info.ps1" -OutFile "$env:TEMP\curator_server_info.ps1";
    PowerShell -ExecutionPolicy Bypass -File "$env:TEMP\curator_server_info.ps1"
    ```
  </Tab>
</Tabs>

<Note>
  The generated file will contain system information including server configuration, performance metrics,
  and usage statistics needed for performance analysis.
</Note>

<Tip>
  If the problem is CPU spikes on a Windows server rather than general slowness, also run the
  [CPU investigation script](/server_management/system_administration/windows_cpu_investigation), which builds a
  timeline of what the server was doing when the CPU spiked.
</Tip>

## Step 2: Access API Keys Settings

<BackendNavPath />

<Note>
  You'll use the **REST API Explorer** section on this page to generate diagnostic endpoint URLs.
</Note>

## Step 3: Collect Portal Info Endpoint

1. Under **REST API Explorer**, use the dropdowns to select:
   * **API Section:** Portal
   * **API Method:** Info
2. Click the **REST API Access URL** link to open the endpoint in a new tab.
3. You should see raw JSON data.
4. Right-click on the page and select **Save As** to save the output to a file.
5. Save the file as `info.json` (save as JSON format, **not PDF**).

## Step 4: Collect Portal PHPInfo Endpoint

1. Return to the API Keys page and change the **API Method** dropdown to **PHPInfo** (keep Portal selected).
2. Click the **REST API Access URL** link to open the PHPInfo page.
3. Right-click on the page and select **Save As** to save the output to a file.
4. Save the file as `phpinfo.html` (save as HTML format, **not PDF**).

## Send Files for Analysis

Email the following files to the Curator support team for analysis:

* Server performance data (markdown file from Step 1)
* `info.json` (from Step 3)
* `phpinfo.html` (from Step 4)
* Feel free to include screenshots of any relevant system information.

The support team will analyze these files and provide specific recommendations to improve your system's performance.


# Queued Processes 
Source: https://docs.curator.interworks.com/site_administration/performance/queued_processes

View, cancel, and clear background jobs running in Curator from the Queued Processes backend list.

Curator runs many tasks in the background -- syncing users, warming caches, importing data, cleaning up old
records, and more. Each background task is recorded as a "queued process" so you can see what is currently
running, what is waiting to run, and what has errored out. The Queued Processes list is the place to monitor
and manage that queue.

## Viewing Queued Processes

1. Navigate to your Curator backend > Settings > Curator > Queued Processes.
2. The list displays each job with its type, status (for example, "Pending", "Running", "Complete", or an
   error status), and timestamps for when it was created and last updated.
3. Use the "Refresh List" button in the toolbar to reload the list and see the latest status.

## Clearing Queued Processes

The toolbar above the list provides three actions for removing jobs from the queue:

| Action          | What it does                                                                               |
| --------------- | ------------------------------------------------------------------------------------------ |
| Cancel Selected | Deletes the jobs you have checked in the list. Disabled until at least one row is checked. |
| Clear Pending   | Removes every job currently in the "Pending" status.                                       |
| Clear Errors    | Removes every job currently in an error status.                                            |

Use "Cancel Selected" when you want to remove a small number of specific jobs without affecting the rest of
the queue. Use "Clear Pending" when pending jobs are stuck or piling up and you want a clean slate before the
next scheduled run. Use "Clear Errors" once you have reviewed the failures and no longer need the records for
troubleshooting.

Each button asks for confirmation before deleting. Removing a job only deletes the queue record -- it does not
undo any work the job already performed.

## Automatic Cleanup

Curator automatically prunes old queued process records once per day so the list does not grow indefinitely.
The daily cleanup task removes any job whose last update was more than three days ago, regardless of status.
Recent jobs -- including pending ones -- are left in place so that in-flight work is not interrupted.

If you want to remove jobs sooner than the three-day window, use the toolbar actions described above.

## Troubleshooting a Queue That Is Not Processing

A healthy queue empties quickly. Curator's scheduled task runs once a minute, picks up every job whose "Run After"
time has passed, and works through them one at a time. Pending jobs normally disappear within a minute or two of
being created. If the Pending count keeps growing, work through the steps below in order.

### Step 1: Confirm the scheduled task is firing

Every background job in Curator depends on a server-level scheduled task (cron on Linux, Task Scheduler on
Windows) that runs `artisan schedule:run` once a minute. If that task stops, nothing in the queue moves.

1. Open the backend Dashboard and find **Last Cron Run** in the **Curator Status** widget. It should read a minute
   or two ago. A warning icon appears once the value is more than 24 hours old, and the Dashboard also shows a
   "Curator's Job System (cron) is not correctly configured" warning.
2. If the timestamp is old or missing, fix the scheduled task before doing anything else. See
   [Linux Cron Troubleshooting](/server_management/system_administration/linux_cron_troubleshooting) or
   [Windows Cron Troubleshooting](/server_management/system_administration/windows_cron_troubleshooting).

Firing the **Portal** > **cron** API endpoint by hand (see "Test Cron" in the Linux guide) runs a single pass of
the schedule. A "success" response only means Curator received the request and finished that pass. It does not
prove the server task is firing on its own, and one pass processes about a minute of queued work at most. Use
the **Last Cron Run** timestamp, not the endpoint response, to judge whether the schedule is healthy.

### Step 2: Check whether one job is holding the queue

Only one queue worker runs at a time, and it processes jobs one after another. A single long job, such as a full
backup of a large webroot, a large user sync, or a big import, keeps every job behind it in Pending until it
finishes.

1. Look for a job whose status is not "Pending". A job the worker has picked up shows "Claimed", a step
   description such as "Step 1 of 3: Backing up the Curator filesystem.", or a percentage.
2. Watch its **Updated At** value across a few refreshes. If it keeps advancing, the job is still working. Leave
   it alone; the Pending jobs follow once it finishes. Some jobs, such as backups, only update their status when
   they move to the next step, so a long gap on its own does not mean the job is dead.
3. If the job appears stuck, open the Event Log (**Settings** > **Logs** > **Event Log**) and search for
   "Curator's queue shut down prematurely". That entry means the worker died while running the job, for example
   because it ran out of memory or was killed by the operating system, and it includes the underlying error. Fix
   the cause if the entry names one, then remove the dead job with **Cancel Selected**. Curator requeues import
   jobs on its own; every other job type keeps its last status until you remove it or the daily cleanup does. A
   dead job does not block the queue by itself, so the remaining Pending jobs continue on the next pass.

### Step 3: Wait out the queue lock

Curator uses a lock to stop two queue workers from running at the same time. When a worker is killed without
warning, the lock can outlive it, and every pass until it expires skips the queue even though the scheduled
task is firing. The lock expires on its own, normally 60 minutes after the run started.

If you cannot wait, you can release the lock yourself, but only once you have confirmed that the worker that
took it is no longer running. Use the checks in Step 2: the job it was running has stopped advancing its
**Updated At** value, and the Event Log holds a "Curator's queue shut down prematurely" entry for it. If either
check fails, the worker may still be working, so wait for the lock to expire instead.

Once you are sure the worker is dead, call the
[/portal/flushAllCache](/curator_api/api_docs/curator_api#portalflushallcache) API endpoint. **Clear Cache**
in the backend does not release the lock; this endpoint does. It works on both Curator SaaS and On-Prem:

```text theme={null}
[your_domain]/api/v1/portal/flushAllCache?apikey=[your_api_key_here]
```

To generate the link with your key filled in, follow the
[Auto Generate API Links](/curator_api/getting_started/curator_api_overview) instructions and set the dropdowns
to **Portal** and **flushAllCache**. The next scheduled pass, normally within a minute, starts a fresh worker.
The endpoint flushes the whole cache, so the next few page loads are slower while Curator rebuilds it and
compiles the theme CSS again.

<Warning>
  Do not remove the lock while a worker is still active. The next scheduled pass would start a second worker
  beside it. The two workers never pick up the same job, because each job is claimed with a single atomic
  database update, but they do process different jobs at the same time, which is exactly what the lock exists
  to prevent. Two backups, for example, could then run at once.
</Warning>

### Step 4: Turn on Cron Debug Mode

If the schedule is firing and nothing above explains the backlog, turn on Cron Debug Mode to see what the
worker does on each pass.

1. Navigate to **Settings** > **Curator** > **Portal Settings** and open the **General** tab.
2. In the **Debug Settings** section, turn on **Cron Debug Mode** and click **Save**. The mode turns itself off
   after 24 hours unless you change **Expiration of Cron Debug Mode**.
3. Wait a couple of minutes, then open the Event Log and look for entries that begin with "CRON DEBUG MODE".

Each pass logs "Updating cron last run timestamp" when the schedule fires and "Running queued task" each time
the worker picks up a job. If the timestamp entries appear but no "Running queued task" entries follow, the
worker is not reaching the queue and the lock in Step 3 is the most likely cause. If a "Running queued task"
entry appears and nothing follows it, that job is the one holding the queue.

### Step 5: Clear the backlog

When a job fails with an error, Curator writes the full error to the Event Log as "Error while running queued
process" and, for most job types, removes the job from the list. Jobs that stay in the list with a status
beginning with "Error:" can be removed with **Clear Errors** once you have read the log.

If the queue is draining again but the backlog is too large to be useful, or the pending work is no longer
wanted, use **Clear Pending** to remove every Pending job and start fresh.

<Warning>
  **Clear Pending** deletes every Pending job. Work that a schedule queued, such as a scheduled backup, a user
  sync, or cache warming, is queued again at its next scheduled time. Work that a person started, such as an
  import or a backup taken with **Take New Backup**, is not, so start it again once the queue is draining.
</Warning>

## Troubleshooting Backups That Stay Pending or Never Appear

Curator runs every full backup through this queue. A scheduled backup adds a "Curator Backup" job at the
configured time, and **Take New Backup** on the Backups page adds the same job immediately. If the queue is not
processing, the backup waits in Pending with everything else, so work through the section above first. Two
backups queued back to back run one after the other, never at the same time.

While a backup runs, its status moves through "Step 1 of 3: Backing up the Curator filesystem.", "Step 2 of 3:
Backing up the Curator database." and "Step 3 of 3: Packaging the full backup file." Step 1 can take a long time
on a large webroot. When the backup finishes, the job is removed from the list and the new file appears under
**Settings** > **Curator** > **Backups**.

If the job disappears from the list but no new backup appears, or the new file name ends in `_NO_DATABASE`, the
backup failed part way through. Curator writes the reason to the Event Log. The common causes are:

**`ERROR: Not enough space for full backup.`**

Free disk space on the server is smaller than the size of the last backup. Free up space or lower
**Backup Retention**, then take a new backup. See [Curator Backup](/upgrading_migration/backups/curator_backup).

**`ERROR: Unable to backup Curator files: <path> is not writable.`**

The web-server user cannot write to the **Backup Location** (`<web root>/storage/temp` by default). Grant the
web-server user write permission to that folder, or point **Backup Location** at a folder it can write to.

**`Unable to find mysqldump executable. Check that it has been added to PATH environment variable.`**

`mysqldump` is not on the PATH of the account that runs the scheduled task. The backup still completes, but
without the database, and the file name ends in `_NO_DATABASE`. Install the MySQL client tools and add them to
the PATH of the account that runs `schedule:run` (the Task Scheduler account on Windows), then take a new
backup.

**`ERROR: Unable to dump Curator database during backup`**

`mysqldump` ran but failed, or produced a file smaller than 100 KB. The log entry lists the dump file path and
size. Confirm the database credentials in Curator's configuration work from the Curator server, and that the
installed `mysqldump` matches the database server version.

A backup whose name ends in `_NO_DATABASE` shows "Does not include a database export!" in the Backups list and
cannot restore the database. Fix the database cause and take a new backup.

On Curator SaaS, InterWorks manages the server, its disk space, and backup storage. If a scheduled backup stays
Pending after the queue is confirmed healthy, or the Event Log shows one of the errors above, contact InterWorks
support.


# Troubleshooting Load Times 
Source: https://docs.curator.interworks.com/site_administration/performance/troubleshooting_load_times

Diagnose and resolve slow loading issues using Curator debug mode for performance optimization.

When determining the root-cause of latency issues on Curator, using the debug mode for Curator is the fastest
way to rule out a number of issues that may be causing slow loading times.  This can come from the location
of your servers and/or networking issues, custom code, internal Curator issues or slow Dashboard load times.
Curator's debug mode provides the Curator team with enough information to know where to start looking when
addressing these issues.  Follow the steps below to view Curator's debug data, and download the debug file
and send it to the Curator support team if you have any concerns.

## Enabling Debug Mode

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the "General" tab at the top of the main page content.
4. In the "Debug" section, turn ON *Enable Frontend Debug* and click the "Save" button.

## Using the Debug Mode

1. Append `?debug=1` to the end of any url (unless there is already a `?` in the url, in which case append `&debug=1`)\*
2. Click the arrow on the bottom tray to expand the debug menu, then navigate between the tabs to view the debug output.
   \*NOTE: If you are debugging slow login times, be sure to logout first, and then add the debug parameter to
   your URL (e.g. `http://curatorexample.com/backend`?debug=1)

## Capturing Debugging Results

1. Once you have followed the **Using the debug mode** steps above, you can download the results of your
   debugging session using the export button on the debugging tray:

   <img alt="debug download" />

2. This will output a `.iw` file which you can send to Curator support for assistance with slow load times.


# Web Accessibility
Source: https://docs.curator.interworks.com/site_administration/standards_compliance/web_accessibility

Scan and evaluate Curator portal for WCAG web accessibility compliance using browser extensions and tools.

This document provides instructions on how to scan your Curator portal for compliance with the Web Content
Accessibility Guidelines (WCAG)

## Prerequisites

Install the [WAVE Accessibility Extension for Mozilla Firefox](https://addons.mozilla.org/en-US/firefox/addon/wave-accessibility-tool/).

Similar extensions may exist in other browsers, but those are outside of the scope of this document.

## What to Scan

There are 3 main sections you'll need to check about when scanning your Curator portal.

1. Login Page
2. Global Structure
3. Page Content

### Login Page

Depending on which authentication type your Curator portal uses, you will likely need to scan the login page
and any related pages shown during the authentication process.  If you utilize a third-party authentication
source, any accessibility issues found with it will need to be fixed within that third-party product.

### Global Structure

Once authenticated to Curator, there are elements shared across all pages, such navigation, search, theme,
logo, and footer.  Any issues found with these elements will be found on each page you test, so it's worth
tracking these separately.

### Page Content

Each page on your site is by nature unique in some aspect.  Whether a page has simple static text, images,
embedded content, or multiple elements of varying content types, each page will need to be checked
individually to verify that all of the content on the page meets accessibility standards.

It should be noted that any issues found with embedded content will need to be addressed in their source
system.  For instance, if you determine there are accessibility issues with a Tableau Dashboard, you'll need
to correct those issues within your Tableau workbook and then republish it.

## How to Scan

Loop through each section and page listed above in Mozilla Firefox.  For each one, right-click on the page
and select **WAVE this page**.

As of the time of this writing, a pane will show up in your browser that lists errors, alerts, contrast
errors, and other elements that were checked for WCAG compliance.  Address the errors and contrast errors
first by clicking on the **Details** tab.  After addressing those, then focus on the alerts.

You should be able to click on each issue to show the element in question and a description of the issue.  If
the element is covered by the WAVE pane, you may need to toggle the styles off.

Most of the issues you may encounter will likely be:

* **Missing alternative text for images:** Each image should have some sort of alternative text to describe
  the image for people with visual impairments.  For instance, an image may just be a logo, but it also might
  be a chart with important information being conveyed.
* **Missing title/label text for page elements:** Some elements on a page, such as buttons, form fields, etc.
  require title text (often displayed as tooltips) or an explicit label in order for people to understand their
  use.  For instance, have you ever tried to use an app where the buttons only show an icon you've never seen
  before?  This issue is exacerbated if you must consume the entire page through a screen reader.
* **Low contrast:** Certain visual impairments make it difficult to discern elements that are too similar
  with respect to contrast.  For instance, try reading light grey text on a white background.
* **Tab order:** The order that elements are highlighted when tabbing through the site makes a big difference
  of how usable or frustrating your site is.  Imagine that your mouse stopped working and you had to use your
  site with nothing more than your keyboard's tab key.  This is how many people must navigate the web.

## Implementation vs. Core Issues

Curator provides a content management platform.  Accessibility issues may exist in the core Curator
functionality or in your actual content or implementation.  Issues found related to your content or
implementation will need to be fixed in your portal.  The Curator development staff make a good faith effort
to routinely check that core features meet accessibility standards, but issues may still slip through.  If
you find an accessibility issue in a core feature, please report it to Curator support so we can address it
in a future version.


# Session Expiration Warning
Source: https://docs.curator.interworks.com/site_administration/user_notifications/session_expiration_warning

Notifies logged-in users before their server-side session expires, giving them a chance to stay logged in or reload the page.

Curator shows a modal to logged-in users shortly before their server-side session expires. This prevents
embedded content (such as Power BI reports that rely on cached authorization tokens) from quietly breaking
when a user has left a page idle for a long time.

The warning is enabled automatically for all logged-in users. There is no setting to toggle it on or off —
the only thing you control is when it appears, via the session lifetime.

## How it works

The modal has two states:

1. **Warning** — appears before the session expires, with two buttons:
   * **Continue** sends a lightweight request to the server, refreshes the session, and dismisses the modal. If the request fails (session has already expired), the modal switches to the **Expired** state with a **Reload** button instead of closing silently.
   * **Log Out** redirects the user to the logout page.
2. **Expired** — if the user does not act in time, the modal switches to an expired state with a single
   **Reload** button that refreshes the page so the user can log in again.

The timer also resets automatically whenever the page makes any background request to the server, so users
who are actively interacting with Curator (loading dashboards, navigating, etc.) will not see the warning.

## When the warning appears

The warning timing is derived from the session lifetime:

| Session lifetime     | Warning appears                     |
| -------------------- | ----------------------------------- |
| 20 minutes or longer | 10 minutes before expiry            |
| Less than 20 minutes | At the halfway point of the session |
| Less than 5 minutes  | Not shown                           |

## Configuring the session lifetime

The session lifetime is controlled by the `SESSION_LIFETIME` value in your `.env` file, expressed in
minutes. The default is 360 minutes (6 hours).

```bash theme={null}
SESSION_LIFETIME=360
```

Lowering this value will cause the warning to appear sooner; raising it will delay the warning. Changes
take effect on the next request after the configuration cache is cleared.

## Relationship to automatic logout

This feature is separate from Curator's automatic logout. Both can be active at the same time:

* **Automatic logout** tracks user activity in the browser (mouse, keyboard, scrolling). It exists to log
  out users who have stepped away from their desk.
* **Session expiration warning** tracks the server-side session. It exists to warn users whose session is
  about to expire on the server even though they may still have the page open.

## Browser sleep and session expiry

The warning is driven by timers running in the browser, and browsers pause those timers while the computer
is asleep or the laptop lid is closed. The server-side session keeps counting down regardless. If a machine
sleeps for longer than the session lifetime, the session ends on the server first, and the warning modal
only appears once the machine wakes up and the paused timer catches up — by which point it is too late to
extend anything.

Clicking **Continue** in that situation cannot bring the session back. Continue works by sending a
lightweight request to the site, and it only switches the modal to the **Expired** state when that request
fails outright. A request made after the session has already ended can still come back as a successful
response, so the modal closes as though nothing went wrong even though the user is no longer authenticated.

The visible result is that the modal disappears, but embedded content — such as Power BI or Tableau
reports — stays blank or broken, and interacting with a report produces the same authorization error again.

**What to do:** if embedded content is still broken after clicking **Continue**, reload the page manually
(press **F5** or use the browser's refresh button). Curator will prompt for login again if needed, and
embedded content will load normally once you are signed back in.

<Note>
  This is a limitation of browser timers rather than a fault in the report or the analytics platform. A
  proactive refresh — clicking **Continue** while the session is still alive — works seamlessly. Recovering
  after the machine has slept past the session lifetime always requires a full page reload.
</Note>


# Third Party Cookies 
Source: https://docs.curator.interworks.com/site_administration/user_notifications/third_party_cookies

Configure third-party cookie warnings and troubleshoot embedded visualization login issues in Safari browsers.

Embedding visualizations within Curator requires third party cookies to be enabled.  By default Chrome and
Firefox allow this but Safari does not.  When you encounter this issue,
**the embedded visualization (e.g.Tableau) login prompt might continue to appear inside of Curator even after
successfully logging in to Curator**.

## Warning Users About Third-Party Cookie Embedding Issues

Since your Curator users may not be aware this setting is preventing them from being able to use the embedded
view in Curator, you can enable an alert that tells them if this is preventing them from being able to
seamlessly log in to their embedded visualization.  To enable this warning follow the steps below:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`) and log in if prompted.
2. Navigate to **Settings** > **Curator** > **Portal Settings**.
3. Click on the "Features" tab.
4. Scroll down to the "Usability" section and enable *3rd Party Cookies Enabled Check*.

## Information on How to Enable Third-Party Cookies

See the steps here to allow cookies on devices that use Safari:

* [Unblocking cookies on iOS](https://support.apple.com/en-us/HT201265)
* [Unblocking cookies on MacOS](https://support.apple.com/guide/safari/manage-cookies-and-website-data-sfri11471/mac)


# Favorites
Source: https://docs.curator.interworks.com/site_content_design/content_discovery/favorites

Enable user favoriting functionality to personalize homepages and prioritize frequently accessed content.

Curator has the ability to mark dashboards as favorites.  Favorited dashboards will show up first on the home page once
the user logs in.

This functionality requires any authentication method other than "Pass-Through".  See the [Authentication Methods](/setup/authentication/overview)
section for more information.

If you have a [Tableau Connection](/creating_integrations/tableau_connection/creating_a_connection)
the favorites will also synchronize across to Tableau Server/Cloud.

You can also display the number of favorites a Dashboard has. This number shows up in both the Dashboard action-buttons
area when viewing a Dashboard and on the homepage when showing Dashboard tiles.

## Enabling Favorites

1. <BackendNavPath />
2. Find the "Favorites" setting and toggle it on.
3. Be sure to save your changes.

## Favoriting a Dashboard

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. Click on the star icon at the top right portion of the screen. Normally this is displayed on the right side of the
   title bar in the Dashboard.

## Showing the Number of Favorites

1. <BackendNavPath />
2. Find the "Favorites" setting and toggle it on.
3. Be sure to save your changes.

## Troubleshooting

If a user reports that their favorites are not persisting between sessions, work through the following
checklist to identify the root cause.

### Pass-Through Authentication Is Active

Favorites require a persistent frontend user record. When the active authentication method is
[Pass-Through](/setup/authentication/pass_through_authentication), Curator does not create or maintain
persistent user records, so there is no account to attach favorites to and the star icon's state cannot
be carried across sessions.

To resolve this, switch to any authentication method other than Pass-Through. See the
[Authentication Methods](/setup/authentication/overview) overview for the available options.

### Tableau Favorites Sync Is Overwriting Curator Favorites

When a [Tableau Connection](/creating_integrations/tableau_connection/creating_a_connection) is configured,
favorites synchronize in both directions between Curator and Tableau Server/Cloud. If a Dashboard is
favorited in Curator but is later un-favorited directly in Tableau Server/Cloud (or vice versa), the next
sync will reconcile the two systems and the user may perceive their Curator favorite as having been lost.

To resolve this, confirm the user's favorites in Tableau Server/Cloud match what they expect to see in
Curator. If the favorites should only be managed inside Curator, remove the Tableau Connection or have the
user manage their favorites exclusively from one side.

### SSO Username Attribute Mismatch Creates Duplicate User Records

Favorites are stored against a single frontend user record. When SSO is configured with an inconsistent
username attribute — for example, an attribute that sometimes returns the email address and sometimes
returns the user principal name — each variation creates a separate frontend user record. The favorites
saved against one record will not appear when the user is logged in under the other record, giving the
impression that favorites are not persisting.

To resolve this, verify in the Identity Provider that the attribute mapped to the Curator username claim
returns the same value for the same user on every sign-in. Then, in the Curator backend under **Users**,
look for duplicate frontend user records for the affected user and remove the extra records so that
only one persistent record remains.

### A Tableau Cloud User's Favorites Stop Syncing

On Tableau Cloud, Curator determines which site to sync a user's favorites from by reading the site portion
of each Dashboard's Tableau URL — the `/t/<site-name>/` segment. If a Dashboard's stored URL is missing that
segment — for example, if the URL was edited or pasted without it — Curator cannot resolve which site the
Dashboard belongs to, and the favorites sync for that site is skipped. The user's Tableau Cloud favorites
then stop updating, and because the sync is skipped rather than failing, no error is shown.

To resolve this, open the affected Dashboard in the Curator backend and correct its Tableau URL so that it
includes the full site path — for example, `https://your-site.online.tableau.com/t/site-name/views/...`
rather than `https://your-site.online.tableau.com/site-name/views/...`. Once every Dashboard on the site has
a valid URL, the site resolves correctly and favorites sync resumes on the next run.


# Featuring Content 
Source: https://docs.curator.interworks.com/site_content_design/content_discovery/featuring_content

Promote and highlight important content using featuring options to increase visibility and user engagement.

The landing page typically shows an assortment of many different dashboards from the site. These displays will show
favorited and featured dashboards first before others. While Favorited dashboards is a feature that is driven by the user
we provide the ability to bump certain dashboards to the top using the Feature switch (requires a tiled homepage). The
dashboards that are shown will only ever be dashboards the user has permission to see.

***To feature a Dashboard:***

1. While editing the Dashboard, click on the "Misc" tab.
2. Scroll to the "Discovery" section.
3. Toggle on the switch labeled "Featured".
4. Click the "Save" button.


# Hidden Content
Source: https://docs.curator.interworks.com/site_content_design/content_discovery/hidden_content

Control visibility by hiding dashboards and other content from tiles, explorer, and search results while maintaining direct access and navigation visibility.

## Hidden and Hidden from Search Toggles

You can now control where content appears throughout Curator using the **Hidden** and **Hidden from Search** toggles.
These toggles are available for most content types and allow fine-grained control over how users discover content.

### Availability

| Content Type          | Hidden |  Hidden from Search  |
| --------------------- | :----: | :------------------: |
| File                  |   Yes  |          Yes         |
| Page                  |   Yes  |          Yes         |
| Menu                  |   Yes  | No *(not available)* |
| Power BI Dashboard    |   Yes  |          Yes         |
| Power BI Report       |   Yes  |          Yes         |
| Tableau Dashboard     |   Yes  |          Yes         |
| Tableau Metrics       |   Yes  |          Yes         |
| Sigma Workbooks       |   Yes  |          Yes         |
| ThoughtSpot Liveboard |   Yes  |          Yes         |
| ThoughtSpot Search    |   Yes  |          Yes         |

***

### Behavior

#### Hidden

* Removes the item from **all content displays**, including tiles and Explorer tiles.
* Prevents the content from appearing in featured or related content sections.

#### Hidden from Search

* Excludes the item only from **Curator search results**.
* The content continues to appear in other locations, such as tiles, related content, and Explorer tiles.
* This setting is **not available for Menus**.

***

### Where to Find the Hidden Settings

| Content Type              | Navigation Path                     |
| ------------------------- | ----------------------------------- |
| **File**                  | Content → File → General            |
| **Page**                  | Content → Page → Page Details       |
| **Menu**                  | Content → Navigation → Menu         |
| **Power BI Dashboard**    | Power BI → Dashboards → Discovery   |
| **Power BI Report**       | Power BI → Reports → Discovery      |
| **Tableau Dashboard**     | Tableau → Dashboards → Discovery    |
| **Tableau Metrics**       | Tableau → Metrics → Discovery       |
| **Sigma Workbooks**       | Sigma → Workbooks → Discovery       |
| **ThoughtSpot Liveboard** | ThoughtSpot → Liveboard → Discovery |
| **ThoughtSpot Search**    | ThoughtSpot → Search → Discovery    |

***

### How to Update Visibility Settings

1. Edit the desired content item (for example, a Dashboard, Report, Page, or File).
2. Navigate to the section shown in the table above.
3. Locate the **Hidden** and **Hidden from Search** toggles.
4. Use the toggles:
   * **Hidden** — hides the item from content listings such as tiles, Explorer tiles, and search results. Navigation menu items linking to the item remain accessible.
   * **Hidden from Search** — hides the item only from search results.
5. Click **Save** to apply your changes.

***

### Bulk Visibility Changes

For every content type except Pages, **Hidden** and **Hidden from Search** are set **per item** on that item's
own edit form. The Discovery lists do offer bulk actions on checked items — for example **Replace Dashboard
URLs** and **Create Menu Items** on Tableau → Dashboards → Discovery — but none of them change visibility.
To hide or unhide several dashboards, reports, files, menus, metrics, workbooks, or liveboards, open and save
each item individually.

#### Pages are the exception

Pages support a bulk visibility change through the **Edit Pages** action:

1. Go to **Content → Pages**.
2. Select the pages you want to change using the checkboxes in the list.
3. Click **Edit Pages** to open the bulk edit window.
4. Set the **Hidden** toggle to the value you want applied to every selected page.
5. Click **Apply Changes**.

<Warning>
  The **Edit Pages** window applies **all** of its toggles — **Hidden**, **Favoritable**, **Blog**,
  **User Commenting**, and **Featured** — to every selected page, using whatever position each switch is in
  when you click **Apply Changes**. Toggles you did not intend to change are still written to the selected
  pages and will overwrite their existing values. Review every switch in the window before applying.
</Warning>

**Hidden from Search** is not included in the **Edit Pages** window. To change it, edit each page individually.

***

### Notes

* Hidden items are still accessible through direct URLs for users with the correct permissions.


# Keywords 
Source: https://docs.curator.interworks.com/site_content_design/content_discovery/keywords

Assign and manage keywords for content organization and improved search and filtering capabilities.

Keywords can be associated with dashboards, pages, individual files, and menu items. These keywords can be utilized in
the Search and Explorer feature when pulling in results, as well as when determining which content to display on a page.
A keyword page can be set up that will pull in all content tagged with the keyword.

***To create a new keyword***

1. Navigate to the **Content** section in the backend of your Curator instance.
2. Select **Keywords** from the Content dropdown.
3. Click the **New Keyword** button.
4. Assign a title to the new keyword (this will be the keyword that is created)
5. From here you can check the box next to an existing piece of content to associate it with that keyword. This new
   keyword will now be available in the keywords list when creating new pieces of content as well.

***To link a keyword to a Dashboard:***

1. While editing a Dashboard, click on the **Misc** tab.
2. Scroll to the **Discovery** section.
3. Select the **Search Keywords** field.
4. Type in the text for the first keyword.
5. Check the box next to the desired keyword.
6. Click the **Save** button at the top-right corner of the page.

The above process is used for linking keywords to pages and files as well. To link a keyword to a menu item, first
create the menu item, then link it to the desired keyword in the **Keywords** section.


# Search
Source: https://docs.curator.interworks.com/site_content_design/content_discovery/search

Enable and configure search functionality to help users discover and locate content across the Curator portal.

The frontend search functionality helps explore your Curator content or access specific content directly without
navigating through the menus.

## Enabling Search

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`) and log in if prompted.
2. Navigate to *Settings > Curator > Portal Settings > Features > Usability*
3. Switch the toggle *Search* on to enable search

*Note:* The search toggle enables the search prompt shown in the menu. You can also
[add a search element directly to a page](#adding-a-search-element-to-a-page) using Page Builder.

### Adding a Search Element to a Page

In addition to the menu search prompt, you can add a dedicated search bar to any page using Page Builder.

1. Navigate to **Content** > **Pages** in the backend of your Curator instance.
2. Click **New Page** or edit an existing page.
3. Add a new row element and/or click the **Edit Content** button (pencil icon) on a row element.
4. In the element popup, select **Search** under the Web Elements tab.
5. Optionally, set the **Element Title** field in the Element Styles section to display a heading above the search bar.
6. Optionally, set the **Search Placeholder Text** field in the Search Settings section to customize the placeholder
   text shown inside the search input.

<Note>
  The search element on a page only works when the global Search toggle is enabled under
  *Settings > Curator > Portal Settings > Features > Usability*. If the toggle is off, the search element will not
  function.
</Note>

### Beta Search

An optional **Beta Search** mode is now available for portals that need faster or more reliable search. To enable it,
follow the steps above to turn on Search, then switch on the *Enable Beta Search* toggle directly beneath it.

Beta Search uses a more powerful search system behind the scenes to deliver quicker and more consistent results than
the default experience. You may want to try it if:

* Your portal has many dashboards, pages, or files and search feels slow
* You need search to scale reliably as your content library grows
* You prefer more precise results that exactly match what you type

<Note>
  Beta Search is less forgiving of typos or vague terms, so queries should closely match titles, descriptions or
  keywords. As this feature is still experimental, behavior may change in future updates.
</Note>

### Content that is searched

The search considers the following components to generate the search results:

1. Titles
2. Descriptions
3. Keywords
4. From version 2023.02.15 onwards: Text content on pages
5. Extracted text content from directly-browsable Files (e.g. uploaded HTML files)
6. Text content of HTML files embedded on a page via the **Upload HTML** page source type

*Note:* For pages with unrestricted HTML content blocks, only static text present directly in HTML elements is
used for search. Content inside `<style>` and `<script>` tags is excluded. If you want text to be searchable, it must
exist in the HTML markup itself.

*Note:* Extracted HTML file text is sanitized before indexing -- scripts, styles, and other executable markup are
stripped, and the text is capped at 10,000 characters. Exactly one item owns that text in search: an HTML file
created through the **Upload HTML** page flow is a hidden backing file, so its text belongs to the page and
surfaces under the page's own permissions; a directly-browsable (non-hidden) file is its own search result and
follows its own [Restrict Access](/site_content_design/menus/restrict_access) instead -- its text is never
surfaced through pages embedding it. A hidden backing file with Restrict Access enabled is excluded from search
entirely. Portals using an external search engine keep these results current automatically -- including after
upgrading, and whenever an embedded file's content, Restrict Access, or visibility changes -- so a manual search
reindex is only needed if the search engine was unreachable while such a change was made.

*Note:* Search results reflect all permissions set on the BI Platforms or by using [Restrict Access](/site_content_design/menus/restrict_access).
In case you have added dashboards or built content that should not be visible in search results, enable the *Hidden*
toggle. To hide dashboards navigate to the *Misc* tab and then in the *Discovery* section you find the toggle.
To hide other types of content, the toggle is in the details pane.

## Changing Search Result Display

Search results show the following components:

* Thumbnail (default if none was created/ set)
* Title
* Description (if existing)
* Keywords (if existing and matching the search term; max. 2 - more are indicated by an ellipsis)
* If the result content is favorited or not

**From release 2023.02.15 onwards**: The description is only shown for Pages if there is a match in it. Otherwise, Pages
will always show a preview of their content (with or without a match).

Files uploaded as HTML behave the same way: where a file's text has been made searchable, its result shows a preview
of that text instead of the file's description. Files without searchable text, and every other type of file, continue
to show their description.

All occurrences of your search term within the title, description, and keywords are highlighted in bold using the portal's highlight color.

## Styling Search

Brand your search with the following settings

* Add a custom search icon (Available since 2022.11.30)
* Navigate to *Settings > Curator > Themes > Styles > Logo and Icons* to add your own search icon
* Style the colors of your search results
* Navigate to *Settings > Curator > Themes > Search Options* (in versions until 2022.09.28: *Settings > Curator > Portal
  Settings > Styles > Search Options*) to set the background and text color
* Navigate to *Settings > Curator > Themes > Styles > Miscellaneous > Navigation Highlight Color* (in versions until
  2022.09.28: *Settings > Curator > Portal Settings > Styles > Miscellaneous > Navigation Highlight Color*) to set the
  text color on hover

## Algorithm Details

Our search applies a fuzzy search algorithm, so search results are intentionally loose so as to help users find the
content regardless of minor typos or alternate spellings.

<img alt="search result example!" />


# Thumbnail Preview Images
Source: https://docs.curator.interworks.com/site_content_design/content_discovery/thumbnail_preview_images

Set up thumbnail and preview images for content to enhance visual discovery and user engagement.

When viewing a list of dashboards, Curator has the ability to display a custom preview of the Tableau Server view as a
thumbnail image.

These thumbnails can either be set manually while creating or
[editing a Dashboard](/site_content_design/pages/pages_overview) or the system will attempt to automatically grab the
thumbnail from the Tableau Server if the Dashboard is created without one.

Automatic thumbnail generation does not apply to Tableau Public dashboards. Tableau Public retired the `.png`
download endpoint that Curator relied on, so Tableau Public dashboards can no longer have their thumbnails generated
automatically and will always display a generic placeholder instead. To show a real image for a Tableau Public
Dashboard, upload a custom thumbnail manually using the steps below.

Views with very large fixed layouts (such as long scrolling dashboards) are automatically scaled down to thumbnail
size. In rare cases an extremely large view may still fall back to the generic placeholder — set an Alternate
Thumbnail URL pointing to a smaller view, or upload a custom thumbnail manually using the steps below.

Once the Dashboard is created you can manually refresh the thumbnail by pressing the Refresh Thumbnail button.

***To refresh the dashboards thumbnail:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Tableau** > **Dashboards** section from the left-hand menu.
3. Click on the "New Dashboard" button or select an existing Dashboard.
4. In the Misc tab, expand the Look/Feel section and click the "Refresh Thumbnail" button.

You can manually upload a thumbnail on the Dashboard edit page.

***To manually upload a thumbnail:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Tableau** > **Dashboards** section from the left-hand menu.
3. Click on the "New Dashboard" button or select an existing Dashboard.
4. In the **Misc** tab, expand the Look/Feel section and use the Thumbnail Image form to upload your custom image.
   *Note: You will need to click the "X" in the bottom-right corner to remove an existing image.*

***To set a global default thumbnail:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the **Home** tab and expand the Tile Type section.
4. Use the "Custom Default Thumbnail" form to upload your custom image.
   *Note: You will need to click the "X" in the bottom-right corner to remove an existing image.*
5. If you wish to use this image for *all* dashboards, disable *Refresh Dashboard Thumbnails* under **Settings** >
   **Curator** > **Portal Settings** > **Features** tab.

Curator also has a feature to enable nightly refreshes of the site's Dashboard thumbnails. This helps to keep the thumbnail
up to date with any changes while also saving time from manually updating every Dashboard thumbnail.

***Enabling or Disabling Refresh Dashboard Thumbnails:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the **Features** tab at the top of the main page content.
4. Toggle the switch to enable/disable *Refresh Dashboard Thumbnails* setting under the Functionality section and click
   the "Save" button.


# Files
Source: https://docs.curator.interworks.com/site_content_design/files/files

Manage file uploads and downloads with group-based access controls and search functionality for document management.

The system supports adding downloadable files and linking to them using the regular navigation menu process. File access
can be restricted based on Groups from the Tableau Server. Search keywords are also provided to help narrow down your
options when searching.

<Note>
  The Files section is designed for **downloadable documents** such as PDFs, spreadsheets, and images. When a File-type
  menu item is clicked, Curator serves the file directly to the browser using the file's own content type — it does not
  render the file inside Curator's page layout or navigation. For an HTML file this means the browser opens it as a
  standalone page (or downloads it), rather than displaying it as a page within Curator.

  If you need to display **custom HTML content** (for example, an HTML page built with an external tool) inside a
  Curator page, use the [Manual Embed (iFrame)](/site_content_design/pages/manual_embed_iframes) feature instead:

  1. Navigate to **Content** > **Pages** and open or create a page.
  2. On the page builder, open the **Add Element** popup, click the **Additional Elements** tab, and select the **Embed**
     content type.
  3. Choose **iFrame** (to point at a URL) or **Embed Code (HTML)** (to paste raw HTML / embed code).
  4. Link that page from navigation using the **Page** link type.
</Note>

***To manage files:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`) and log in if prompted.
2. Navigate to **Content** > **Files** section from the left-hand menu.
3. Add, modify, or delete files as desired.

## Hidden Settings

In Curator, there are two general use-cases for uploading files: **Images** and **Documents**.  By default, the
file-features are configured for Images since this is a much more common scenario.  See configuration items below that
describe treating files as images or documents:

**Hidden**: For images, for example a logo, it may cause confusion to surface the logo in search or inside of a
["recently viewed" Tiles](/site_content_design/pages/tiles) page-element.
In this scenario, hiding the file ensures the logo only shows up on the page you explicitly added it to.
However, you may want to show a PDF inside of the search results, or add it as a link to a tile selection.
*In this case, make sure to un-check the Hidden toggle on the edit-file page*.

## File Size Limits

> This section applies to **Curator On-Prem** only. File size limits for Curator SaaS are managed by Curator support.

The maximum file upload size in Curator is controlled by your server's PHP configuration. Two PHP settings govern upload
limits:

* **`upload_max_filesize`** — The maximum size of a single uploaded file (e.g., `64M` for 64 megabytes).
* **`post_max_size`** — The maximum size of the entire POST request body, which includes the file and any other form
  data. This value should be equal to or greater than `upload_max_filesize`.

To increase the upload limit, update both values in your server's `php.ini` file:

```ini theme={null}
upload_max_filesize = 64M
post_max_size = 64M
```

After changing these values, restart Curator for the changes to take effect. If you are unsure which `php.ini` file is
active, check the output of the `portal/info` API endpoint.

For information on uploading and embedding video files, see [Video Uploads](/site_content_design/pages/video_uploads).


# Loading Screens
Source: https://docs.curator.interworks.com/site_content_design/loading_screens/loading_screens

Configure custom loading screens and progress indicators to improve user experience during content loading.

Loading screens can be used to show text or animations while a Dashboard is loading.

## Understanding Loading Indicators

Curator has several loading mechanisms that may display during content loading:

1. **Custom Loading Screens** - User-created loading screens with custom content (text, images, animations) shown
   while a dashboard loads. Configured per-dashboard or as a site-wide default.
2. **Post-Authentication Loading Screen** - A loading screen shown after login while Curator warms the navigation
   and search caches. Can be enabled or disabled under **Settings** > **Curator** > **Themes** > **Loading
   Screens** tab.
3. **Default Loading Indicator** - A progress bar or spinner shown during page transitions. The color can be
   customized under **Settings** > **Curator** > **Themes** > **General** > **Loading Bar Options**.

***To create a loading screen:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Content** > **Loading Screens** in the dropdown.
4. Click the "New Loading Screen" button.
5. Enter the title of the loading screen in the title field.
6. Enter the content of the loading screen in the content field. This field allows for fully formatted content,
   including images, links, etc.
7. Click the "Create" button.

***To select a default loading screen for all dashboards:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Navigate to the **Settings** > **Curator** > **Themes** section from the left-hand menu.
4. Click on the "Loading Screens" tab at the top right.
5. Select the desired loading screen in the "Default Loading Screen" field.
6. Click the "Save" button.

***To display the Dashboard thumbnail while loading for all dashboards:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on "Settings" link in the left-hand menu.
4. Navigate to the **Settings** > **Curator** > **Themes** section from the left-hand menu.
5. Click on the "Loading Screens" tab at the top right.
6. Toggle on "Show Dashboard Thumbnail During Load". Note the "Custom Loading Screen" option and this option
   can not both be enabled at the same time.
7. Click the "Save" button.

***To set a loading screen for a specific Dashboard:***

1. While editing the Dashboard, click on the "Misc" tab.
2. Scroll to the Look/Feel section.
3. Select the desired loading screen.
4. Click the "Save" button.

***To view the loading screen:***

1. Navigate to the frontend of the system (e.g. `http://curatorexample.com`).
2. Log in if prompted.
3. Navigate to the desired Dashboard by using the navigation menu.
4. The configured loading screen will be shown while the Dashboard is loading.


# Managing Menus
Source: https://docs.curator.interworks.com/site_content_design/menus/managing_menus

Create, edit, and organize menu structures to provide intuitive navigation throughout your Curator portal.

You can only display *one* top-level menu item at a time. It is recommended that you nest your entire navigation under the
default 'Main Menu' parent-item or create a new "Dropdown Placeholder" if you wish to manage multiple menus - often this
approach is used to organize unreleased content via menus. Group Overrides allow you to select one different 'Main Menu'
parent item per group.\*

***To Select the Global Navigation:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the *Curator* > *Settings* > *Portal Settings* section from the left-hand menu and click the "Styles" tab.
3. Expand the "Menu Options" section and select your menu using the *Main Menu* dropdown.

***To Select a Group Override  Navigation:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the *Curator* > *Settings* > *Users* > *Frontend Group Overrides* section from the left-hand menu.
3. Click on the Group Override you would like to modify or click the "New Group Override" button at the top to create a
   new override.
4. Click the "Styles" tab,
5. Choose your overridden Main Menu *Main Menu* dropdown.

## Understanding "Orphaned Items" Placeholder Menus

Curator stores your navigation as a tree, and every menu item records which menu it sits beneath. If that parent
record goes missing — for example it was removed by a database restore, a partial import, or a deletion that left its
children behind — the items underneath it would have nothing to attach to and would drop out of the navigation tree.

To prevent that, Curator looks for menu items whose parent no longer exists and recreates the missing parent as a
placeholder titled **Orphaned Items, Menu #: `<id>`**, where `<id>` is the ID of the menu that went missing. The
affected items stay nested underneath it, so they remain visible and editable in the backend.

This check is queued each time you open a page under *Content* > *Navigation* and then runs as a background job, so
the placeholder generally appears within a minute rather than instantly. An "Orphaned Items" menu appearing is
expected behavior rather than an error: it means the parent record was already gone, and Curator recovered the items
instead of losing them.

The placeholder is recreated using the missing menu's original ID, and that matters for what your end users see.
Curator resolves your Main Menu by looking for a menu with the configured ID, and only checks that such a menu exists
— not whether it is top-level or attached to anything else. So if the missing ID is still the one selected as your
site's Main Menu (*Portal Settings* > *Styles*), or as a Frontend Group Override's Main Menu, the placeholder
immediately takes that role and its contents appear in the navigation on the frontend. If that ID is not selected as
a Main Menu anywhere, the placeholder sits at the top level of the tree and stays out of the frontend navigation
until you move it — or its items — beneath the menu you have selected as your Main Menu.

Deleting the placeholder on its own does not resolve the situation. While its items still point at the missing parent
ID, Curator recreates the placeholder the next time the check runs, which is why the same "Orphaned Items" entry can
reappear after you remove it.

***To Resolve an "Orphaned Items" Menu:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the *Content* > *Navigation* section from the left-hand menu and expand the "Orphaned Items" entry to
   review which menu items are nested beneath it.
3. Navigate to the *Content* > *Reorder Navigation* section and drag each of those items to the location you want them
   in, beneath a menu that still exists.
4. Return to *Content* > *Navigation* and delete the now-empty "Orphaned Items" placeholder. With nothing referencing
   the missing menu ID any more, it will not be recreated.

Alternatively, the placeholder is an ordinary menu record, so if its contents are already in the right place you can
simply keep it and rename it to something meaningful instead of moving the items elsewhere.


# Menu Items
Source: https://docs.curator.interworks.com/site_content_design/menus/menu_items

Configure individual menu items including links, labels, icons, and access permissions for effective site navigation.

***To Create a Navigation menu item:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the *Content* > *Navigation* section from the left-hand menu.
3. Expand/collapse the navigation using the carets to find the menu you would like to edit - or click "New Menu Link" to
   create a new item.
4. From the Create New / Update Link page, you can create/modify your new menu item as you'd like.
5. Once your menu items have been created, visit the Reorder page by navigating to the *Content* > *Reorder Navigation*
   section from the left-hand menu.
6. Click and hold the dots ⠀ to drag/drop your menu items and reorder them as you'd like

***To Bulk Create Tableau Dashboards as Menu Items:***

1. Navigate to *Tableau > Dashboards* on the backend
2. Select the Dashboards you would like to create as menu items
3. Click Create Menu Items button

***To Bulk Create Power BI Dashboards as Menu Items:***

1. Navigate to *Power BI > Dashboards* on the backend
2. Select the Dashboards you would like to create as menu items
3. Click Create Menu Items button

***To Bulk Create Power BI Reports as Menu Items:***

1. Navigate to *Power BI > Reports* on the backend
2. Select the Reports you would like to create as menu items
3. Click Create Menu Items button

***Link Types:***

**Dashboard**
The Dashboard type is used to link to existing dashboards.  See the [Embedded Tableau Server Views](/embedding_using_analytics/tableau_dashboards/adding_a_dashboard)
section for more information.

**Data Manager**
The data manager type is used to link to a front-end enabled data manager page. See the [Data Manager](/embedding_using_analytics/data_manager/data_manager_basics)
section for more information.

**Dropdown Placeholder**
The dropdown placeholder type is used to create a grouping or level in the multilevel navigation. Doesn't contain a link
and only displays text.

**File**
The file type links to a file that has been uploaded to the site. The file is served directly to the browser for
download or direct viewing — it is not rendered inside Curator's page layout. To display custom HTML content within a
Curator page, use a Page with a [Manual Embed (iFrame)](/site_content_design/pages/manual_embed_iframes) element instead.
See the [File](/site_content_design/files/files) section for more information.

**Keyword**
The keyword type is used to create a link to a listing of content tagged with a specified keyword.

**Menu Page**
The menu page type allows you to enter the name of a menu item. The menu link will then take you to a page that displays
all of the dashboards directly under (one menu level) the specified menu item. Similar to a keyword page.

**Project**
The project type syncs in every Dashboard from the chosen Project. These Dashboards will be created and configurable in
the Dashboards area of the Backend. By default the project link acts as a dropdown placeholder and the synced Dashboards
are nested beneath it as its children, so you can give the dropdown its own title and icon. Switch on **Create synced
Dashboards as siblings** if you would rather the Dashboards were created alongside the project link instead of beneath
it; the project link itself is then hidden from the navigation. Existing project links created before this option was
added keep the sibling behavior, so nothing moves when you upgrade.

After you save the menu item, the Dashboards are populated by a background job rather than immediately, so they appear in
the navigation shortly after saving rather than instantly. Curator confirms this with the message "Tableau Project
dashboards are syncing in the background and will appear shortly."; this is expected behavior, not an error.

Changing that option re-arranges the Dashboards that have already been synced. That happens in the background and can
take several minutes on a Project with a lot of Dashboards. Only Dashboards created by the automatic sync are moved:
links you placed by hand are left where they are. A Dashboard synced moments before you changed the option may sit out
that first re-arrange, because Curator is still collecting its details from Tableau; the next sync of that Project moves
it into place. A project link must sit inside another menu item -- it cannot be a top-level item. More info on this can
be found [here](https://interworks.com/blog/morr/2017/11/22/automatically-sync-your-dashboards-portals-tableau/).

**Projects**
The projects type syncs in every Dashboard from every Project on the specified Site -- it is the project type applied to
the whole Site. Each Project gets its own dropdown placeholder beneath this link, with that Project's Dashboards as
direct children. There is no Workbook level, unlike the workbooks type. Because the placeholders are real menu items you
can reorder, rename, and restrict access to them, and they appear in the backend menu tree.

Be aware that this creates a Dashboard record in the Curator backend for every Dashboard on the Site, which can be a
very large number, and each of those Dashboards has metadata and a thumbnail to fetch and keep refreshed. The
placeholders and links are shared rather than generated per user, so what each person sees is decided by permission
checks against Tableau. Workbooks without an accessible Project (for example, Workbooks in a user's Personal Space, or
Workbooks whose Project has been deleted) are omitted rather than listed, and a Project whose Workbooks have all been
removed has its placeholder pruned on the next sync.

**Page**
The page type is used to link to a static page.  See the [Pages](/site_content_design/pages/pages_overview)
section for more information.

**Tag**
The tag type is used to automatically create links to any Tableau Server workbooks which have been tagged with a specific
name. See the [Tagged Workbooks](/site_content_design/menus/tagged_workbooks)
section for more information.

**Web Edit**
The web edit type is used to create a link to the Tableau Server web editor for a specified Dashboard.

**Workbook**
The workbook link type imports in all of the dashboards from a workbook as menu items. It will also automatically pull in
future dashboards added to the workbook. The parent nav item itself is non-clickable and acts as a dropdown placeholder;
only the child dashboard items are clickable links.

**Workbooks**
The workbooks link type imports in all of the dashboards from all workbooks in a project as menu items. It will also automatically
pull in future dashboards added to the project. The parent nav item itself is non-clickable and acts as a dropdown placeholder;
only the child dashboard items are clickable links.

**Custom URL**
This link type is used to create a link to a custom URL. Extra options are provided to customize this like opening the link
in a new tab or the same tab.

**External URL**
This link type is used to create a link to an external URL. This is a slimmed-down version of the Custom URL.

*NOTE: If you are adding a link that is external to your Curator instance, ensure that you prepend the proper protocol to
your URL. For example, to add InterWorks.com use `http://www.interworks.com`, or `https://www.interworks.com`.*


# Restrict Access
Source: https://docs.curator.interworks.com/site_content_design/menus/restrict_access

Control menu visibility and access permissions based on user groups and roles to secure content appropriately.

When you add a Dashboard or other content brought in from connected integrations like Tableau, Curator will inherit the
security settings from those integrations. However, you may want to override those source-systems or you may want to prevent
users from seeing content that exists solely within Curator - for example, restricting access to a specific
[page](/site_content_design/pages/pages_overview).  With **Restrict Access**
you can override inherited security settings when necessary, offering you maximum flexibility over the visibility of content.

## Enabling Restrict Access

1. On the backend of Curator, navigate to the **Content** > **Reorder Navigation** section from the left-hand menu.
2. Find the menu link you'd like to restrict access to and click the pencil/edit icon - or click the "New Menu Link"
   button to create a new menu item.
3. Toggle the Restrict Access to ON to display a list of [groups](/users_groups/user_management/users_and_groups_overview)
4. Select the groups you'd like to grant access to
5. Save the menu item

You can then confirm the restrict access is enabled on the Reorder Navigation page by hovering over the lock icon and
seeing the phrase "Restricted Access based on Group Membership"

**Tableau admins** automatically have access to all Tableau-connected content in Curator.  Restrict access overrides
these permissions, so admins will need to be in one of the selected groups to see the content within the menu.

## Restricting Pages and Files Directly

Pages and Files can also restrict access in their own settings, which secures the content itself rather than a single
menu link to it.  This is the better choice when the content is reachable in more than one way (several menu links,
search, tiles, or a shared URL), or when you do not want to create a menu link at all.  See
[Restricting a Page to Groups](/site_content_design/pages/pages_overview#restricting-a-page-to-groups) and the
[Files](/site_content_design/files/files) documentation.  Content-level and menu-level restrictions stack: a user must
satisfy both to see the content.

## Restrict Access and Direct Links

Restrict Access is enforced on every page load, not just when rendering navigation menus. This means that if a user
shares a Curator URL with someone who is not in an authorized group, that person will still be blocked from viewing the
content. There is no additional configuration required to protect against unauthorized access via shared or bookmarked
URLs — the same group-membership check applies regardless of how the page is reached.

## Restrict Access and Tableau Connection Issues

Inherited Tableau permissions can only be checked while Curator is able to reach Tableau Server. If the connection is
down, disabled, or misconfigured when a user requests a dashboard, Curator cannot verify that user's Tableau
permissions and **grants access instead of blocking it**, so that a temporary outage does not lock out users who are
otherwise entitled to the content. This result can be cached for up to 24 hours, which means access may stay open for
a while even after the connection to Tableau Server is restored.

**Restrict Access is a separate check that reads only from Curator's own database, so it is unaffected by Tableau
connectivity.** Because of this, Restrict Access is not redundant with inherited Tableau permissions — it is the only
access control on a menu item that keeps working while the Tableau connection is unavailable. Enable Restrict Access
directly on any menu item whose content must stay protected even during a Tableau outage.

To apply this protection everywhere at once, enable **Settings** > **Security** > **Authentication Settings** >
**Customization** > **Restrict Access is Always Enabled**, which treats every menu item as restricted and requires
each one to list the groups allowed to see it. See
[Frontend User Permissions](/users_groups/user_security/frontend_user_permissions) for details on that setting.

<Warning>
  The global **Restrict Access is Always Enabled** setting only evaluates content that is linked from at least one
  menu item. A dashboard with no menu link has nothing to restrict, so it skips this check and its access still
  depends solely on the Tableau connection. Add a menu link for any content that must remain protected during an
  outage.
</Warning>


# Site Switcher
Source: https://docs.curator.interworks.com/site_content_design/menus/site_switcher

Enable users to easily navigate between multiple Curator sites or environments through integrated site switching functionality.

Some Tableau Servers have different sites with different dashboards associated with those sites. The site switcher allows
a frontend user to filter the dashboards in the navigation by Tableau Site from a dropdown.

***To enable:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left-hand menu.
4. Click on the "Features" tab at the top of the main page content.
5. Scroll to and expand the "Usability" section and then toggle on "Site Switcher".
6. Click "Save".


# Tagged Workbooks
Source: https://docs.curator.interworks.com/site_content_design/menus/tagged_workbooks

Organize and display workbooks in menus using tags to create dynamic, categorized content navigation.

The system can automatically create dashboards for any workbooks that have a matching tag on the associated Tableau Server.
It will poll the Tableau Server every 10 minutes to check for any newly tagged workbooks which match a tag navigational
item (see the [Navigation](/site_content_design/menus/managing_menus) section
for more information). A new Dashboard and corresponding navigation link will be created for each view in any workbooks
it finds.

Links to any new dashboards created through this process will be placed in the same location as the tag navigational item.
However, these links can be safely moved or deleted if desired.

This functionality requires that the REST API is enabled
(see the [Enabling the REST API](/creating_integrations/tableau_connection/creating_a_connection)
section for more information).


# Org Chart
Source: https://docs.curator.interworks.com/site_content_design/org_chart/org_chart

Create and display organizational charts with hierarchical employee structure and reporting relationships visualization.

The Org Chart provides a visual representation of the organizational structure within a company or organization. It
outlines the hierarchy of positions, roles, and reporting relationships.

## Creating an Org Chart

### Preparing the data

The Curator Org Chart is built using the
[Data Manager](/embedding_using_analytics/data_manager/data_manager_basics)
for its underlying data. You'll need to create an Attribute for each column in the employee data you'll be adding or
importing. It's important the names of the Attributes match the names of the columns from your data if you'll be
importing from another system. Once you have created the Attributes, you'll need to create a Data Manager Group and
select the Attributes you've just created. Finally, you can use the "Batch Import" button on the Data Manager > Manage
Data page in your Curator backend. There, you can upload a CSV with all of your employee data.

### Creating the Org Chart

Navigate to the Data Manager > Org Chart area of your Curator backend. There, you can click "New Org Chart" and fill
out the form. Below are descriptions of each field:

* **Title**: This is the title for your Org Chart. The primary place this will be displayed is in the browser tab
  displaying the Org Chart on the frontend.
* **Data Manager Group**: This is the Data Manager Group we created and imported the data to.
* **Employee Name Attribute**: This is the Attribute name that corresponds to the column in the data for the employee’s
  name. This will be displayed on the employee’s node in the chart.
* **Employee ID Attribute**: This is the Attribute name that corresponds to the column in the data for the employee’s
  ID. This column and the Supervisor ID column will be how the chart knows where to put each employee in the tree.
* **Supervisor Name Attribute**: This is the Attribute name that corresponds to the column in the data for the
  employee’s supervisor’s name.
* **Supervisor ID Attribute**: This is the Attribute name that corresponds to the column in the data for the
  supervisor’s ID. This column and the Employee ID column will be how the chart knows where to put each employee in the
  tree.
* **Role Name Attribute**: This is the Attribute name that corresponds to the column in the data for the employee’s
  role at the company.
* **Who is the top node for the Org Chart?**: Enter the name here for who is at the top of the Org Chart (typically a
  CEO). This needs to match the Employee Name Attribute value of your highest ranking employee.
* **Slug**: This is the bit at the end of the URL for the page where the Org Chart will be displayed. This will be
  automatically generated based on the Title field, but you can change it if you’d like.

### Customize the Org Chart Design

Below the primary configuration for the Org Chart are many fields that can be used to customize the look of the Org
Chart. Here are descriptions of each option in the Design tab:

* **What shape should the nodes be?**: You can choose a circle or a rectangle. The rectangle allows you to show more
  information in each node.
* **How should nodes be named?**: You can choose to show the employee’s name or, if you’d like to be a bit more
  confidential, the employee’s role at the company on the node in the chart.
* **Specify any additional attributes to show in each node**: This is where we can add more information to the
  rectangular nodes. *(This only appears if the node shape is set to rectangle.)*
* **Show employee headshot?**: This will tell the Org Chart you have URLs in your data and would like to show those
  images.
* **Employee Headshot Attribute**: This is the Attribute name that corresponds to the column in the data for the
  employee’s headshot URL. Users will be able to flip the switch in the top right of the chart to toggle headshots and
  the employee info. *(This only shows if the “Show employee headshot?” switch is on.)*
* **Show tooltip on hover with additional employee details?**: This will tell the Org Chart you’d like to show a
  tooltip when hovering over a node. It’s very useful if you’re wanting to display employee details without making the
  chart look too busy.
* **Attributes to show in tooltip**: Add any Attributes here you’d like to appear in the tooltip. *(This only appears*
  *if the tooltip option is flipped on.)*
* **Color employee nodes by attribute?**: This allows adding a visual way to differentiate each employee. The most
  common use cases are coloring by employee department and full-time vs. part-time. A legend will be shown in the
  top-left corner of the chart designating what each color means.
* **Specify any additional attributes for the search bar to parse (default is only employee name)**: This adds
  Attributes/columns that the search will parse. Sometimes you don’t know the employee’s name but know their department,
  so this improves parsing a large org chart.

### Frontend Org Chart Editing

While the Org Chart is more for reporting pre-determined organization data, we do have some light editing tools. Here
are descriptions of each option in the Editing tab:

* **Which Frontend Groups can edit?**: You don’t want just anyone to be able to edit or delete employees from your Org
  Chart, so you can choose specific Frontend Groups to give these privileges to. There will be an Edit button and a
  Delete button that become visible on each node. The Edit button will show a pop-up window with the employee’s relevant
  details, which can be changed and saved. The Delete button will give a confirmation message before sending the node
  into oblivion. *Note: The Edit and Delete buttons are omitted from the top node because changing those details could*
  *easily break the underlying data and leave the Org Chart blank.*
* **Fields to show in edit Form**: By default, only the name, role and supervisor Attributes are shown in the edit
  form. You can use this field to add additional Attributes to the form.
* **PDF Download**: Sometimes the browser’s print functionality doesn’t quite hit the mark with visualizations like
  this, so we’ve added a PDF download option for a much more visually appealing download of the chart.
* **PDF Download Watermark**: The data being revealed on the Org Chart could be sensitive, so it’s important to make it
  known this shouldn’t be shared. Whatever text is added to this field will be slapped over the chart in the PDF.
* **CSV Download**: This will generate a CSV containing data for the visible nodes, as opposed to the full data the Org
  Chart is running on. The button for this, as well as the PDF download, will be in the top-right corner of the Org Chart
  page.


# Blogs
Source: https://docs.curator.interworks.com/site_content_design/pages/blogs

Create and manage blog-style pages for news updates and educational content with feed-based display options.

When using Curator, you may need to notify your audience about updates related to news in your business or may need to
help break down important concepts, and allow those updates to be highlighted in a specific area of your site.  If you
find yourself needing to really this type of information on your Curator pages, then the Blog flag is extremely useful.

All Curator pages can be marked as a "blog" allowing you to filter a subset of pages in a feed-type of display in the
various elements available on the page builder, whether you want to display blog pages in a list, a feed, tiles or any
other format.  While the page is not flagged as a blog, it will only be accessible via the menu or directly from the URL,
allowing you to have pages that are in a draft state priori to a go-live date.

**To mark a page as a blog:**

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Content** > **Pages** section from the left-hand menu.
3. Find the page in the list view or click "New Page" to create a new page.
4. At the bottom of the page, enable the "Blog" toggle, and save the page


# Box Embedding 
Source: https://docs.curator.interworks.com/site_content_design/pages/box_embedding

Embed Box file sharing and collaboration content directly into Curator pages using embed widgets.

## Getting the Embed Widget

1. In your web browser, navigate to your box environment from which you wish to embed a folder within Curator.
2. In the row of your folder, hover over the right-hand-site, click on the ***More options*** ellipsis (**...**).
3. Hover over ***More actions***.
4. Click on ***Embed Widget***.
5. Click on ***Copy*** and all necessary code will be copied

## Adding Box to a Curator Page

Start by either creating a new page or editing an existing Curator page from Curator's backend.  Click on the plus (+)
icon in the Page Builder preview pane to add a new blank element to the page.  This blank element is a placeholder that
you'll use to embed the desired Box folder by following these steps:

1. Hover your mouse over the blank element and click on the pencil icon.
2. Click on the **Additional Elements** tab at the top of the pop-up.
3. Select the **BOX Cloud** option.
4. The pop-up will close and the Box settings will appear on the left.  Paste the widget you copied above into the
   **Box Embed Code** field.  You should see the Page Builder preview update to show the Box folder or login screen.
5. Adjust the height as you need it by using the ***Height*** field in the Box Settings.
6. Once you're happy with the layout, click on the **Save** button.


# Controlling Page Width
Source: https://docs.curator.interworks.com/site_content_design/pages/controlling_page_width

How to control how wide page content appears in Curator using the global Page Margin theme setting and per-row width overrides.

Curator gives you two ways to control how wide your page content appears: a global side-margin that applies to every
page on the site, and a per-row override that lets individual rows break out to the full width of the browser window.

## Global Page Margin

The **Page Margin** setting controls the amount of empty space on the left and right of every page, expressed as a
percentage of the browser window width.  A larger percentage produces narrower content with more breathing room on the
sides; a smaller percentage lets content extend closer to the edges of the screen.

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Click on **Settings** > **Curator** > **Themes** in the left-hand menu.
3. Open the theme you would like to edit and select the **Pages** tab.
4. Adjust the **Page Margin** value (entered as a percentage) and click the "Save" button.

This setting applies to all pages that use the selected theme.

## Per-Row Width

Individual rows in the page builder can override the global page margin and stretch to the full width of the browser
window.  This is useful for hero images, full-bleed banners, or background-colored sections that should reach the edges
of the screen.

1. In the page builder, click on the row you would like to adjust on the page-preview on the right-hand side.
2. In the styling side-panel that opens on the left, locate the **Row Width** option.
3. Choose **Standard** to respect the global Page Margin, or **Full Width** to stretch the row edge-to-edge.
4. Click the "Save" button on the page.

Content *inside* a Full Width row still respects its own column layout, so you can combine a full-width background with
standard-width inner content by nesting elements appropriately.


# Deleting a Page
Source: https://docs.curator.interworks.com/site_content_design/pages/deleting_a_page

Step-by-step instructions for deleting a Curator page, including how to resolve the homepage-block error and what to expect on sites with many user groups.

## To delete a page in Curator

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Content** > **Pages** section from the left-hand menu.
3. Click the page you want to delete to open it.
4. Click the **Delete** button.
5. Confirm the deletion when prompted.

## Troubleshooting: "Cannot delete page set as the homepage"

If the page you are trying to delete is currently configured as the homepage, Curator will block the deletion and
display an error explaining that the page is set as the homepage.  To resolve this:

1. Navigate to **Settings** > **Curator** > **Theme Settings** in the left-hand menu.
2. Change the **Homepage** setting to a different page and save.
3. Return to **Content** > **Pages**, open the page you wanted to delete, and click **Delete** again.

## Slow Deletion on Sites With Many Groups

On sites that have a large number of user groups, deleting a page may take longer than expected.  This is because
Curator automatically resets any per-group homepage overrides that point at the page being deleted before completing
the deletion, which can add measurable time on installations with many groups.  This is expected behavior — let the
request finish rather than retrying.


# Explorer 
Source: https://docs.curator.interworks.com/site_content_design/pages/explorer

Interactive tile layout element with search and filtering capabilities for dynamic content discovery and navigation.

Explorer is an interactive and dynamic tile layout element that can be added in the Page Builder. It provides users the
ability to search and filter displayed content. Filters utilize keywords to get the desired results. This layout is best
used when you have a lot of content on your site as the tiles are small.

## To add a Explorer page element

1. Navigate to the **Content** section in the backend of your Curator instance.
2. Select **Pages** from the Content dropdown.
3. Click the **New Page** button or edit an existing one.
4. Add a new row element and/or click the **Edit Content** button (pencil) icon of a row element.
5. In the element popup select Explorer under the Web Elements tab.

After this your Page will display the Explorer element. Since this uses the Keywords functionality please review the
subject [here](/site_content_design/content_discovery/keywords).

## Keyword Filter Behavior

The keyword and category filters in the Explorer element always describe the content that is currently visible. Each
filter list is built from the tiles remaining after the active filters and search term are applied, so selecting a
keyword narrows the lists to only the keywords that still appear on at least one of the remaining tiles. Keywords that
no longer match any visible tile are hidden until the selection is cleared.

This affects every filter list in the element:

* Selecting a keyword narrows the other keyword list, when both the top and bottom keyword sections are configured,
  along with the list of categories.
* Selecting a category clears any selected keywords and rebuilds the keyword lists for that category.
* Typing in the search box narrows the keyword and category lists in the same way.

The selected keyword itself stays visible and highlighted, so you can click it again to deselect it. Deselecting
restores the options that are still valid under any filters that remain active, such as a selected category, a search
term, or another selected keyword, rather than removing all filtering. This narrowing is the intended behavior and
cannot currently be turned off. The only related element
settings are **Hide Navigation Categories** and **Hide Keyword Filters Categories**, which hide the filter lists
entirely rather than changing how they narrow.

## New and Updated Flags

The Explorer element displays **New** and **Updated** flags on tiles when content has been manually flagged in the
backend (**Tableau > Dashboards > Manually Flag as New / Manually Flag as Updated**), consistent with the behavior of
the Tiles element.


# Forms
Source: https://docs.curator.interworks.com/site_content_design/pages/forms

Build custom web forms for data collection, feedback, and user requests using Curator Data Manager capabilities.

Whether it's storing small data-sets from around your business, getting valuable feedback from your users, or creating a
simple contact-us / request access form Curator's data manager has the web form building capabilities you need.

## Creating a Form

You can create a form on the backend using Curator's Data Manager feature.  See here for more information on how to
create forms and fields in our [Data Manager Basics](/embedding_using_analytics/data_manager/data_manager_basics)
section.

## Adding a Form to a Page

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Content** > **Pages** section from the left-hand menu.
3. Find the page you want to add your form to from the Pages list or click "New Page" to create a new page.
4. Add a new element to your page, and when the modal pops-up, click the "Analytic Element" tab and select the "Curator
   Data Group" option.
   <img alt="Curator Data Group element" />
5. In the Page Styles section on the left-hand side, you can choose to either embed the Form Only for receiving inputs,
   or you can add the Table view to allow your end-users to see the data that has already been added.

## Forms and Tableau Dashboards on Pages

Some Tableau Dashboards can pull their results from Form submissions. In cases like this it can be useful to have the
Tableau Dashboard refresh it's data after a Form submission. Curator will automatically refresh all Tableau Dashboards
that are on a page with a Form if a Form submission occurs.


# Looker Embedding
Source: https://docs.curator.interworks.com/site_content_design/pages/looker_embedding

Embed Looker reports and dashboards directly into Curator pages for integrated analytics viewing.

## Getting the Report URL

In your web browser, navigate to the Looker report you wish to embed within Curator.  Once the report has loaded, copy
the link in the URL bar of your browser.

### Adding Looker to a Curator Page

Start by either creating a new page or editing an existing Curator page from Curator's backend.  Click on the plus (+)
icon in the Page Builder preview pane to add a new blank element to the page.  This blank element is a placeholder that
you'll use to embed the desired Looker report by following these steps:

1. Hover your mouse over the blank element and click on the pencil icon.
2. Click on the **Analytic Elements** tab at the top of the pop-up.
3. Select the **Looker** option.
4. The pop-up will close and the Looker settings will appear on the left.  Paste the link you copied above into the
   **Report URL** field.  You should see the Page Builder preview update to show the Looker report.
5. Once you're happy with the layout, click on the **Save** button.

<img alt="GIF illustrating the steps written above" />


# Manual Embed - (iFrames) 
Source: https://docs.curator.interworks.com/site_content_design/pages/manual_embed_iframes

Embed content from external websites and legacy systems using iFrames and custom embed code.

Sometimes you need to go beyond Curator's standard embedding capabilities and embed content from your unique or legacy
systems into Curator. That's where Curator's **Manual Embeds** feature comes to the rescue! We'll walk you through the
steps to seamlessly embed any other website, using iFrames, into your Curator pages!

**Important Considerations:**

* While you're adding Manual Embeds, keep in mind that the embed code should come from trusted sources. This will help
  you avoid any security risks or funky user experiences.
* Some systems might require some extra configuration or customization to display perfectly within an iFrame. Check out
  the documentation or support resources for the specific system you're embedding to ensure compatibility and the best
  possible display.
* Don't forget to pay attention to the dimensions and aspect ratio of the iFrame content. We want it to fit smoothly
  within your Curator page. Adjust those dimensions if needed, so you avoid any cropping or weird distortions.

## Adding a Manual Embed to a Page

1. Login to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend` ).
2. Navigate to the **Content** > **Pages** section from the left-hand menu.
3. Find the page you'd like to add your Manual Embed to, or click the "+ New Page" button.
4. On the page builder editor, click the section you'd like to add your embed to, or click the "+" icon on the page
   builder page to add a new section.
5. Click the "Additional Elements" tab from the "Add Element" popup and select the **Embed** content type.
6. Choose the dropdown option that best fits your need from the options below
   * iFrame: For use when pasting in a simple URL (e.g. `https://mycuratorexample.com/embed`)
   * Embed Code (HTML): For use when copying embed code from another website - this will be in HTML and can be
     identified by searching the copied code for `</iframe>` - if this string is found in your code it means you are using
     an iFrame to embed.
7. Once you've pasted the correct information in, click "Add"

## URL Parameter Substitution

When you use the **iFrame** option (a plain URL), Curator can substitute the following placeholders in the URL
with the signed-in user's details. Substitution happens server-side, only when a user is logged in, and only for
the iFrame option — placeholders are **not** processed in the Embed Code (HTML) option.

| Placeholder      | Replaced with                                                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[USERNAME]`     | The logged-in user's Curator username (often their email address)                                                                                                                     |
| `[DISPLAY_NAME]` | The logged-in user's display name                                                                                                                                                     |
| `[IW_TOKEN]`     | A short-lived, cryptographically signed identity token for the logged-in user (see [Passing a verified identity with `[IW_TOKEN]`](#passing-a-verified-identity-with-iw_token) below) |

Placeholder matching is case-insensitive. For example, `https://myapp.example.com/report?user=[USERNAME]` renders
as `https://myapp.example.com/report?user=jane.smith@company.com` for the signed-in user. This lets the embedded
application receive the current user's identity in the URL without Curator forwarding any session tokens.

`[USERNAME]` and `[DISPLAY_NAME]` are plain strings, so an embedded application cannot tell whether they were
genuinely set by Curator or forged by whoever crafted the URL. When the embedded application needs to *trust* the
identity — not just display it — use `[IW_TOKEN]` instead.

## Passing a verified identity with `[IW_TOKEN]`

`[IW_TOKEN]` substitutes a short-lived JSON Web Token (JWT) that the embedded application can cryptographically
verify, so it can trust *which Curator user* is viewing the embed without any login flow inside the iframe and
without Curator forwarding session cookies. Append it to the iFrame URL as a query parameter, for example:

```text theme={null}
https://myapp.example.com/form?iw_token=[IW_TOKEN]
```

At render, for a logged-in user, Curator replaces `[IW_TOKEN]` with a freshly signed token. The token:

* is signed with RS256 and lasts about **60 seconds**, so it must be verified as soon as the embed loads;
* carries **identity only** — the user's id (`sub`), username (`preferred_username`), display name (`name`), and
  email (`email`, when the user has one). It carries **no groups or roles**, so the embedded application remains
  responsible for its own authorization;
* is **scoped to the embed's host** (the `aud` claim is the iFrame URL's host), so a token minted for one embed
  cannot be replayed against a different application;
* includes a unique token id (`jti`) the embedded application should record to enforce single use;
* names Curator's JWKS URL in the `jku` claim, so the application does not have to hard-code or reconstruct it.

The embedded application verifies the token against Curator's public keys, published as a JWKS (JSON Web Key Set).
Read the JWKS URL from the token's `jku` claim rather than assuming a fixed location — it is the endpoint below,
and it already accounts for portals hosted under a base path (e.g. `https://<host>/<basepath>/user/embedauth/jwks.json`):

```text theme={null}
https://<your-curator-host>/user/embedauth/jwks.json
```

The token's header names the key (`kid`) used to sign it; the application matches that against the JWKS, checks
the signature, and confirms the `iss` (your Curator URL), `aud` (its own host), and expiry before trusting the
identity. The JWKS endpoint is public and unauthenticated — it exposes only public keys — so the embedded
application can fetch it without a Curator session. No Curator-side configuration is required — signing keys are
created automatically the first time a token is minted.

`[IW_TOKEN]` is only substituted for the **iFrame** option and only when a user is logged in; for an anonymous
visitor it resolves to an empty value. As with the other placeholders, it is not processed in the Embed Code
(HTML) option.

## Authentication Limitations

Curator's iFrame embed renders the target URL inside a browser frame — it does not broker authentication between
Curator and the embedded application. Specifically, Curator does **not**:

* Forward Curator session cookies or authentication tokens to the embedded application.
* Intercept HTTP 3xx authentication redirects that happen inside the iframe.
* Detect when an iframe is displaying a login page instead of the intended content.

If the embedded application has its own authentication requirement (for example, an OIDC/OAuth login flow), users
who are not already authenticated to that application will see the application's own login UI inside the iframe.
Whether the iframe renders at all depends on the target application's own framing policy:

* `X-Frame-Options: DENY` — The application refuses all iframe embedding; the frame appears blank.
* `X-Frame-Options: SAMEORIGIN` — The application only allows framing from its own origin, so it will not load
  inside Curator (a different origin). The frame appears blank.
* A `Content-Security-Policy` header on the target — The browser may block the frame depending on the policy.

When you add or edit an iFrame URL in the **page builder**, Curator checks the target URL's response headers and
warns you in the editor if the target appears to block framing (an `X-Frame-Options` of `DENY`, a `SAMEORIGIN`
value that doesn't match your Curator host, or the presence of a `Content-Security-Policy` header). This check is
a build-time convenience in the editor; it does not run when visitors view the published page, so always confirm
the embed renders correctly on the live page.

**Recommended approach for applications with their own authentication:**

1. Work with the target application's team to explicitly allow framing from your Curator domain — for example, by
   setting `Content-Security-Policy: frame-ancestors 'self' https://analytics.yourcompany.com` on the target
   application.
2. Ensure the target application's session cookies use `SameSite=None; Secure` so browsers transmit them in
   cross-site iframe requests.
3. If you control the target application, use the [`[IW_TOKEN]` placeholder](#passing-a-verified-identity-with-iw_token)
   to pass a signed, verifiable identity into the embed — the application verifies it against Curator's JWKS and
   establishes its own session for that user, with no inline login form and no redirect. This is the preferred
   option when the embed needs to *trust* the Curator user's identity (for example, an authenticated Streamlit form).
4. If the target application only supports a plain-string deep link, use the `[USERNAME]` placeholder to pass the
   user's identity to a token-exchange endpoint on the target side instead. Note that, unlike `[IW_TOKEN]`, a plain
   username is not verifiable, so only use it where the target endpoint applies its own trust checks.

There is no Curator-side configuration to open an authentication flow in a new tab and return to the embed once
authentication is complete.

## Content Security Policy and Framing Headers

Curator sets the following security-related response headers on **its own pages**. These govern how Curator pages
behave — they do not restrict which origins Curator's iframes may load from:

* **`X-Frame-Options: sameorigin`** — Controls whether Curator itself can be framed by another site. On rendered
  pages this header is omitted when the portal **Allow iframe embedding** setting is enabled, so that Curator can be
  embedded elsewhere.
* **`Content-Security-Policy: upgrade-insecure-requests`** — Applied when the portal **Force SSL** setting is
  enabled. It upgrades mixed HTTP/HTTPS sub-resource requests; it does not restrict iframe sources.
* **`X-Content-Type-Options: nosniff`** — Prevents MIME-type sniffing; it does not affect iframe loading.

Cross-origin embedding restrictions are enforced by the **target application's** headers, not by Curator's.


# Pages Overview 
Source: https://docs.curator.interworks.com/site_content_design/pages/pages_overview

Introduction to creating and managing custom pages within Curator using the page builder for flexible content organization and presentation.

When adding content from your analytics environments, Curator will automatically create default template pages for you.
These can be accessed via the edit page of those individual pieces of content.

However, you may want to create something more tailored for your users to showcase certain content.  In this case, using
Curator's page builder allows a huge amount of flexibility for creating and styling your pages, while still allowing you
to link to content that is both secured to the user viewing the page as well as relevant based on their recent browsing activity.

## Building Pages in Curator

### To create a page in Curator

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Content** > **Pages** section from the left-hand menu.
3. Click "New Page" to create a new page.

### To add content to your page

1. Hover over the element on the page-preview on the right-hand side of the page builder and click the "edit" icon
2. Choose the content you'd like to add to your page

## To style content to your page

1. Click on an item on the page-preview on the right-hand side of the page builder.
2. This will expand a side-panel over the menu on the left-hand side of the page that will give you styling controls
   related to the active content.

## Creating a Page from an HTML File, URL, or Embed Code

When all a page needs to show is a single piece of embedded content -- for example a standalone HTML page
generated by an AI tool -- Curator can build the page for you:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Content** > **Pages** section from the left-hand menu.
3. Click the **Upload HTML** button in the toolbar.
4. Enter a title for the new page, then choose a source: upload an `.html` file, link to a URL, or paste
   embed code.
5. Optionally enable **Add new Page to Navigation** to add the new page to the main navigation, and
   **Hide new Page from Search** to keep the page out of search results while it stays visible in tiles
   and the explorer. Both are off by default.
6. Click **Create Page**.

The new page contains a single full-width element holding your content, and its title display is turned off
so the content takes up the whole page area. Both can be changed later in the page builder, just like any
other page. For security, uploaded HTML files are displayed inside a sandboxed frame isolated from the
viewer's Curator session, so scripts inside the file cannot interact with Curator itself.

Pages can also be created this way programmatically via the
[`/content/createPage`](/curator_api/api_docs/content#contentcreatepage) API endpoint.

## Controlling Page Width

Curator gives you two ways to control how wide your page content appears: a global side-margin that applies to every
page on the site, and a per-row override that lets individual rows break out to the full width of the browser window.
See [Controlling Page Width](/site_content_design/pages/controlling_page_width) for the full guide.

## Page Security

Pages will first inherit any [Restrict Access](/site_content_design/menus/restrict_access)
permission that have been set on the individual menu item.  Continuing from there, the permissions will apply according
to the sections below.

### Restricting a Page to Groups

A page can restrict access directly in its own settings, without creating a menu link just to hold the restriction:

1. Navigate to **Content** > **Pages** and open the page.
2. Expand the **Page Details** section and toggle **Restrict Access** to ON.
3. In the **User Group Access** list that appears, check the
   [groups](/users_groups/user_management/users_and_groups_overview) that should be able to see the page.
4. Save the page.

Page-level Restrict Access is enforced everywhere the page can be reached: menu links, direct or shared URLs, search
results, tiles, keyword pages, and when the page is embedded inside another page.  It stacks with any Restrict Access
set on the page's menu links, so a user must satisfy both to see the page.  If Restrict Access is on but no groups are
selected, nobody can see the page.

When **Restrict Access is Always Enabled** is turned on in **Settings** > **Security** > **Authentication Settings**,
every page is treated as restricted and must have at least one group selected before users can see it, the same way
menu links behave under that setting.

In the backend, menu links pointing at a restricted page show a lock icon on the **Reorder Navigation** page, and the
menu link's edit form notes that the page restricts access in its own settings with a link back to the page.

Page security for embedded-content was added in the 2024.03-02 release, all prior releases have no security applied
when loading embedded content for pages.  The following section only applies to 2024.03-02 and later.  Proceed to the
**Security for Pages Without Embedded Content** section if you are on an earlier version.

### Security for Pages With Embedded Content

When embedding analytic-content into pages, for example a Dashboard, Curator will check permissions on that embedded
piece of content.  If the user does not have access to the embedded content it will deny them access, routing them to
the
[Access Denied page](/site_content_design/user_notifications_and_email/error_pages).

This applies to both menu items as well as loading the page directly.

#### Disabling Embedded Content Security

To disable the security check in versions released after 2024.03-02:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Click on **Settings** > **Curator** > **Portal Settings** in the left-hand menu.
3. On the **General** tab, scroll down to the **Security** section and expand it.
4. Toggle the switch **Disable Page Element Security Checks** to ON and click the "Save" button.

### Security for Pages Without Embedded Content

Content that is *linked* on a page, for example Tiles, will run through permissions checks while loading the page.
check when rendering the tiles.  So if a page contains a *Tile* that links to a Dashboard that a user does not have
access to the user will simply not see the tile.  However, for pages that have content *embedded* in them, see the
**Security for Pages With Embedded Content** section above.

## Deleting a Page

To delete a page, including troubleshooting the homepage-block error, see
[Deleting a Page](/site_content_design/pages/deleting_a_page).


# SSRS Embedding
Source: https://docs.curator.interworks.com/site_content_design/pages/ssrs_embedding

Embed SQL Server Reporting Services (SSRS) reports directly into Curator pages for integrated reporting.

## Getting the Report URL

In your web browser, navigate to the SSRS report you wish to embed within Curator.  Once the report has loaded, copy the
link in the URL bar of your browser.

### Adding SSRS to a Curator Page

Start by either creating a new page or editing an existing Curator page from Curator's backend.  Click on the plus (+)
icon in the Page Builder preview pane to add a new blank element to the page.  This blank element is a placeholder that
you'll use to embed the desired SSRS report by following these steps:

1. Hover your mouse over the blank element and click on the pencil icon.
2. Click on the **Analytic Elements** tab at the top of the pop-up.
3. Select the **SQL Server Reporting Services (SSRS)** option.
4. The pop-up will close and the SSRS settings will appear on the left.  Paste the link you copied above into the
   **Report URL** field. You should see the Page Builder preview update to show the SSRS report.
5. Once you're happy with the layout, click on the **Save** button.


# Text Element
Source: https://docs.curator.interworks.com/site_content_design/pages/text_element

WYSIWYG text elements for adding formatted text, links, and images to your Curator pages.

## Adding a Text Element

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Content** > **Pages** section from the left-hand menu.
3. Find the page you want to add your form to from the Pages list or click "New Page" to create a new page.
4. Add a new element to your page, and when the modal pops-up select the "Text" option.
   <img alt="Curator Text element" />
5. You will then be prompted with the WYSIWYG editor, where you can add and format your text, add links, and images.
   <img alt="Curator Text element" />

## Page Variables

Page variables can be used to display important user or session based information on pages.

* `{{ full_name }}` : Displays the full name for the logged in user
* `{{ first_name }}` : Displays the first name for the logged in user
* `{{ last_name }}` : Displays the last name for the logged in user
* `{{ username }}` : Displays the Curator username for the logged in user
* `{{ original_username }}` : Displays the original username for the logged in user


# Tiles
Source: https://docs.curator.interworks.com/site_content_design/pages/tiles

Create visual tile layouts to organize and link content from multiple source systems with automatic permission handling.

Creating a central location to link all of the content users have access to is a breeze with Curator's tiles feature.
You can bring in content that pulls across different source-systems, from Curator's page system, as well as adding in
your own custom links to send users to other useful websites.

NOTE: All tiles, unless specifically overridden, will respect the permissions of what the user has access to.
If there are any group restrictions on menu items, those will be taken into account.
Second, it will check the source-system permission (e.g. Tableau, Power BI, etc.).
Then finally will look at the individual item's permission (e.g.
[Restrict Access](/site_content_design/menus/restrict_access) on a file).

## Tile Types

You can quickly add tiles into your page in a few clicks.  To give you more insight into what each of these tiles allow
you to display for your users, we've provided a brief description of each section below:

**Dashboards**
Dashboard Tiles allow you to link to analytic content that you have brought into Curator.  This links from any source-system,
be it Tableau, Power BI, or ThoughtSpot - anything that Curator supports natively!  This runs through a permissions check
to make sure the user has access, and can be sorted to your preference.  The default sorting after your preference will
be to place user-favorited dashboards first, then order them by visit, and finally by alphabetical order.

**Pages**
Page Tiles allow you to link to other pages you have created on Curator.  You may want to embed a "contact us" page,
create a feedback form, link to other detail pages, or maybe even use our explorer feature to allow users to browse
through all the content they can see.  Whatever you want to create within Curator, Page Tiles can specifically link to
that content.

**Menus**
Menu Tiles repeat the same-level menu items as the menu you've linked to.  So if you want to display all the top-level
menu items someone has access to, you can add in a link to your highest menu item, and it will display all the links
one level below the link you've selected.  It's an easy way to allow people a more visual exploration while still
maintaining the guardrails of your neatly maintained menu system.

**Keyword Pages**
Keyword Page Tiles pull in content of any sort so long as it has been associated with a specific keyword on Curator.
Linking this content together allows you to logically group things at a topic level that may not make sense to be grouped
in other ways.  It unifies areas that cut across your site in a categorically succinct manner.

**External URL**
External URLs can be created in the Navigation section, and allow you to link to other websites.

**Media**
Media brings in any content that has been uploaded to Curator's Files system.  This allows you to link to specific files
(e.g. PDFs) that are hosted on Curator. Files can have security applied directly to them without needing to be added to
the menu.

**External (RSS) Feeds**
Allows you to bring in external and RSS feeds as tiles, that serve as links to the host page.

**Custom Mix**
For when you want bring in anything and everything someone has access to.  This combines all the tile types listed here
and displays content based on the criteria you've chosen.

**Managed Instances (Enterprise Only)**
If your users have access to multiple Curator sites that you've deployed through Central Dispatch, this tile-type will
allow them to view all the different Curator sites they have access to.

## Tile Style

**Tile Style** can be selected on the Page Styles menu when tiles are selected in the Page Builder. The tile style
selection includes shapes in Square, Small Horizontal, Boxy, Circle, and Hex.

Tile styles in Page Builder is independent of the Global tile styles in Portal Settings. You are able to have different
tile styles for different Pages, but the same Dashboards have to have the same tile style.

## Open in New Tab

The **Open in new tab** toggle in the Content Selection panel controls whether tiles open their linked content in a new
browser tab. When it is on, every tile in that element opens in a new tab; when it is off, tiles open in the same tab.

This toggle applies to dynamically filtered content - that is, any selection that pulls content automatically, such as a
Content Type of "All" combined with a Content Filter (e.g. "User Favorites"), as well as keyword, menu, and feed
selections. It sets the behavior for the whole group of tiles at once.

Manually selected content does not use this toggle. Instead, each manually added item has its own **Open in new tab**
switch in the Manually Selected Content list, so you can set the behavior per tile.

## Tile Thumbnails

**Tableau Dashboards** can generate thumbnails automatically and they will be updated regularly if you want them to.
Yet, this might display data that you do not want to show on a thumbnail. To show a generic thumbnail for this Dashboard:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the Tableau > Dashboards section from the left-hand menu.
3. Click on the Dashboard you want to change the thumbnail for.
4. Open the Misc tab and expand the Look/ Feel section.
5. Delete the auto-generated thumbnail.
6. Use the Upload button to upload your custom thumbnail.
7. Click Save.

**Pages**' thumbnails default to the global default thumbnail unless you set one on the Page itself:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the Content > Pages section from the left-hand menu.
3. Click on the page you want to change the thumbnail for.
4. Scroll down, under the Preview window.
5. Use the Upload button for the Thumbnail Image to upload your custom thumbnail.
6. Click Save.

**Files & Keywords**' thumbnails default to the global default thumbnail unless you set one on the Page itself:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the Content > Files or Keywords section from the left-hand menu.
3. Click on the file or keyword you want to change the thumbnail for.
4. Use the Upload button for the Thumbnail Image to upload your custom thumbnail.
5. Click Save.

Most of the **Navigation** items can have an icon associated with them. If there is no additional explicit option to
upload a thumbnail for it, the default thumbnail will be the icon. To set the icon or thumbnail for a navigation item:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the Content > Reorder Navigation section from the left-hand menu.
3. Click on the pen icon (edit button) of the navigation item you want to change the icon or thumbnail for.
4. Use the Upload button for the Icon or if existent the Thumbnail Image to upload your custom icon/ thumbnail.
5. Click Save.

If you want to customize the **default thumbnail** to show for any content type that does not have a thumbnail set:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to the Settings > Curator > Themes section from the left-hand menu.
3. Click on the Pages tab in the middle of the screen.
4. In the new left-hand-side menu, Pages Options, expand the Tile Styles section.
5. Use the Upload button for the Custom Default Thumbnail to upload your default thumbnail.
6. Click Save.

   ***2024.02-02 Default Thumbnail update***

   The default tile was updated in the 2024.02-03 release to a more modern design.  If you wish to re-upload the old file,
   you can right click the file link to save this image: [Old Default Thumbnail](/assets/images/site_content_design/pages/old_default_thumbnail_file.png).


# User Customized Metrics 
Source: https://docs.curator.interworks.com/site_content_design/pages/user_customized_metrics

Enable users to personalize their landing pages with custom dashboard selections displayed in a grid layout.

User Customized Metrics gives your users the ability to customize their landing page with their desired dashboards that
will be displayed in a grid layout. For the best experience it’s recommended to create smaller dashboards or Dashboard
cards, for example this could be Dashboard with your KPIs.

**To enable User Customized Metrics:**

1. Navigate to the **Content** section in the backend of your Curator instance.
2. Select **Pages** from the Content dropdown.
3. Click the **New Page** button or edit an existing one.
4. Add a new row element and/or click the **Edit Content** button (pencil) icon of a row element.
5. Select **User Customized Metrics** under the Web Elements tab.
6. You may wish to tweak some settings by expanding **Custom Metrics Settings** on the left:

* **Use Keywords** allows you to pre-filter the list of dashboards displayed by a specific keyword. This ensures
  your users can only pick from dashboards tagged with that keyword. To find out more about keywords [click here](/site_content_design/content_discovery/keywords).
* **Default Dashboards** allows you to pre-select the Dashboard which are displayed to your user by default.

**To select your Customized Metrics on the frontend:**

1. Navigate to the page which has the User Customized Metrics Element.
2. Login if prompted (you must be logged in).
3. Click on the **Edit button** on the top right.
4. Drag your desired Dashboard(s) from **Available Dashboards** to **Selected Tiles**.
5. Click on **Save**.


# Video Uploads
Source: https://docs.curator.interworks.com/site_content_design/pages/video_uploads

Learn how to upload, embed, and host video content in Curator using Page Builder elements and external hosting options.

Curator supports uploading a variety of file types including images, documents, and video files such as **MP4** and
**MOV**.

## Embedding Videos with Page Builder

Curator's Page Builder provides dedicated elements for embedding videos on pages:

* **YouTube** — Use the
  [YouTube embed element](/site_content_design/pages/youtube_embedding) to embed YouTube videos directly on a page.
* **Vimeo and other platforms** — Use the
  [custom/manual embed element](/site_content_design/pages/manual_embed_iframes) to embed Vimeo videos or content
  from other video platforms.

## Hosting Large Videos Externally

For large video files, hosting externally is recommended rather than uploading directly to Curator. Large
videos can slow down page load times and consume significant server storage. Consider using one of the following
external hosting options:

* **YouTube** or **Vimeo** — Upload the video to the platform and embed it on your page using the appropriate
  Page Builder element as described above.


# YouTube Embedding
Source: https://docs.curator.interworks.com/site_content_design/pages/youtube_embedding

Embed YouTube videos directly into Curator pages for educational content and multimedia presentations.

## Getting the Video URL

In your web browser, navigate to the YouTube video you wish to embed within Curator.  Once the video has loaded, copy
the link in the URL bar of your browser.

### Adding a YouTube video to a Curator Page

Start by either creating a new page or editing an existing Curator page from Curator's backend.  Click on the plus (+)
icon in the Page Builder preview pane to add a new blank element to the page.  This blank element is a placeholder that
you'll use to embed the desired YouTube video by following these steps:

1. Hover your mouse over the blank element and click on the pencil icon.
2. Click on the **Additional Elements** tab at the top of the pop-up.
3. Select the **YouTube** option.
4. The pop-up will close and the YouTube settings will appear on the left.  Paste the link you copied above into the
   **Video URL** field.  You should see the Page Builder preview update to show the YouTube video.
5. Once you're happy with the layout, click on the **Save** button.

<img alt="GIF illustrating the steps written above" />

For information on uploading video files directly to Curator, see
[Video Uploads](/site_content_design/pages/video_uploads).


# Curator Styles
Source: https://docs.curator.interworks.com/site_content_design/theme/curator_styles

Customize the visual appearance of your Curator portal with built-in styling options and theme configurations.

Curator allows controls related to your site design across all content types, however having a central place to modify
styles that will impact every page your user visits allows you to create a standard and consistent brand.  The live
preview makes this even easier, allowing you to change the configuration of options in the Curator Styles section while
previewing those changes (across device sizes too).  It's best to look through all of the options, and toggle each
selection on or off.  Deleting any content that is input into a text box will revert it back to the default setting.
Feel free to play around and revisit your design as much as you'd like!

## Creating a new Theme

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to:
   * **Settings** > **Curator** > **Theme** section from the left-hand menu. Select the Theme you'd like to update.
   * *Pre 2022-11-30:* **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click through each tab, expand the sections on the left-hand navigation to see more advanced styling options.
   Changing the the selections will update the live preview on the screen and will show the pending changes.
4. Once you have configured your theme the way you would like, click "Save" to apply your changes to this Theme.

## Applying a Theme to your Site

This feature is only available for Curator instances running 2022-11-30 and above.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. On the "General" tab, use the "Global Theme" dropdown to change the theme applied to your Curator site.  If you would
   like to apply your Theme to a specific group of users, see the
   [Group Override instructions](/site_content_design/theme/group_overrides).
4. Click "Save" to apply your changes.

## Defaults when Using Multiple Themes

When you create a new theme, its fields start **blank** rather than pre-filled with Curator's out-of-the-box values, and
**Use Global Theme for Defaults** is enabled automatically. This means a brand-new theme inherits the look of your
Global Theme from the start — you only need to fill in the specific fields you want to change, instead of clearing every
field first.

Any field you leave blank (an empty text input, no color selected, or the "Default" dropdown option) is resolved when
the page is rendered — the inherited value is not copied into the form controls, so blank fields stay blank in the
backend. A blank field resolves in one of two ways:

* If **Use Global Theme for Defaults** is enabled (the default for new themes) and the theme is not itself the Global
  Theme, the blank field inherits the matching value from your Global Theme (chosen in **Settings** > **Curator** >
  **Portal Settings**).
* Otherwise, the blank field falls back to Curator's built-in out-of-the-box default.

This is particularly useful if you have [Group Overrides](/site_content_design/theme/group_overrides) that need to use
themes that look exactly like the Global Theme with just a few minor changes. You can switch **Use Global Theme for
Defaults** on or off in any theme that isn't the Global Theme.

The Global Theme itself cannot inherit from another theme, so its own blank fields always use Curator's built-in
defaults.

## Custom Styles (CSS / HTML Inserts)

Curator supports injecting custom CSS and HTML into your site through the theme settings. For step-by-step
instructions on enabling and using custom styles, see the [Custom Styles](/site_content_design/theme/custom_styles)
page.


# Custom Styles
Source: https://docs.curator.interworks.com/site_content_design/theme/custom_styles

Add custom CSS and HTML head inserts to your Curator theme for advanced styling and third-party integrations.

Curator supports injecting custom CSS and HTML into your site through the theme settings. This is useful for adding
custom fonts, third-party scripts, or styling overrides that go beyond the built-in theme options.

<Note>The code in this section is not supported by the Curator team and will need to be self-managed.</Note>

## Enabling Custom Styles

1. <BackendNavPath />
2. Toggle on **Enable Custom Styles (CSS / HTML inserts)**.
3. Click "Save" to apply your changes. A new **Custom Styles** tab will appear in the theme editor.

## Using the Custom Styles Tab

Once the toggle is enabled, the **Custom Styles** tab provides two code editors:

* **Head Insert** — A code editor for custom HTML that is inserted into the `<head>` section of every page. Use this
  for JavaScript, external libraries, fonts, or any other tags that belong in the document head.
* **Custom Stylesheet** — A code editor for custom CSS that is appended to the end of your compiled theme stylesheet.
  Use this for all custom page styles. Because it is appended last, these styles will override any default theme styles.

## Fallback Behavior for Secondary Themes

If a secondary theme (one that is not the Global Theme) does not have **Enable Custom Styles** toggled on but does
have **Use Global Theme for Defaults** enabled, Curator will check the Global Theme. If the Global Theme has custom
styles enabled, the secondary theme will inherit the Global Theme's custom CSS. The same fallback does not apply to
the Head Insert, which is resolved through group overrides independently.


# Group Overrides
Source: https://docs.curator.interworks.com/site_content_design/theme/group_overrides

Apply group-specific theme customizations and styling overrides to provide tailored experiences for different user groups.

When using Curator, you may want to surface different content to different users.  You can achieve this using Curator's
Group Overrides.  Whether you want to show a homepage to a certain subset of users or you want to change the colors and
logos for a specific client, you can use groups (synced from Tableau or your SAML provider) to modify the look and feel
of your Curator site. For additional info, view our
[Group Overrides blog post](https://interworks.com/blog/morr/2018/04/09/portals-tableau-new-feature-spotlight-overriding-settings-tableau-group/).

## To Create a new Group Override

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Users** > **Frontend Group Overrides** section from the left-hand menu.
3. Click the 'New Group Override' button at the top.
4. From the Frontend Group list, select the group you would like these settings to apply to.
5. Give the group override a title, if a user has access to multiple groups, this will be the title that is displayed
   that allows them to switch between group overrides\*.
6. Modify the settings you wish to override for this group using the tabbed form fields at the bottom of the page, and
   once you're done, click Save.

## Using the Theme-switcher

If you are logged in to the front-end of Curator and your user is a member of multiple groups, by default you will see
a dropdown in your menu that allows you to view either the "Default" setting\*, or individual Themes.  The experience
when selecting these themes will depend on whether or not "Use Global Theme for Defaults" has been enabled for the theme.

\***Group Override Inheritance - Use Global Theme for Defaults Enabled**
When "Use Global Theme for Defaults" is enabled, and your use is a member of multiple groups, they will see all settings
that have been saved inside of Themes across those groups.

For example, if there are two groups:

* Group 1 - Green menu, default/no bg color
* Group 2 - Default/no bg menu color, black background

"Default" would show you a Green menu and black background, whereas selecting Group 1, you will see a Green menu and the
remainder of settings will show the default settings, and the same goes for Group 2 where you will see a default menu
color but the background of the site will be black.

\***Group Override Inheritance - Use Global Theme for Defaults Disabled**
If you create a  group override with the Global Theme Default disabled, this group override will remain distinct and
separate from the inheritance flow, only allowing you to see this if:

1. You are a member of that group and *only* that group.
2. You are a member of multiple groups, and have chosen that group from the Theme-switcher dropdown on the front-end of Curator.

## Disabling Group Switching

By default, users who have access to multiple group overrides will be allowed to cycle through the group overrides they
belong to.  Group Overrides are inherited by creation-date, with the oldest group-override taking the highest priority.
If you do not want to give users access to changing this to view distinct Themes on a per-group basis you can disable
that dropdown using the steps below:

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the 'Features' tab and expand the 'Usability' section at the bottom of the page.
4. Toggle **Group Override Selector** to the off position.
5. Save your settings.


# Homepage
Source: https://docs.curator.interworks.com/site_content_design/theme/homepage

Configure and customize the homepage layout, content, and design elements to create an engaging user landing experience.

Curator allows you to create unique web pages using
[Curator's page builder](/site_content_design/pages/pages_overview) to customize
the layout and content of any page on your site.  This is particularly useful when creating your homepage to ensure
users start off with all the information they need.  By default, Curator comes installed with some sample pages, but if
you no longer have that page or want to start by creating a new page, follow the
[steps to create a page](/site_content_design/pages/pages_overview) first.  Once
your page has been created use the steps below to set that page as your homepage.

## Setting the Homepage

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings** > **Curator** > **Theme** section from the left-hand menu. Select the Theme to apply the
   new homepage to.
3. Click on the 'Home' tab at the top of the page.
4. Change the Homepage Type dropdown to **Page**.
5. Change the Homepage Page dropdown to the page you'd like to set as your homepage.
6. Optional - the homepage hides page titles by default. To show your page's title at the top of the homepage, change
   the **Show Page Title on Homepage** dropdown to **On**.
7. Click "Save" to apply your changes.


# Mobile Styles
Source: https://docs.curator.interworks.com/site_content_design/theme/mobile_overrides

Fine-tune the mobile and responsive behavior of your Curator portal with these settings.

Curator pages automatically adapt to screen sizes based on the default settings and industry standard design practices.
For example, when viewing Curator from a mobile device:

* The desktop navigation is replaced by a hamburger menu (☰).
* Page layout stacks vertically.
* The toolbar repositions to suit the narrower layout.

The default threshold is **1025 pixels**. That means any device whose content area is narrower than
1025px will display the mobile layout (hamburger menu, etc.), while
devices at 1025px or wider display the full desktop layout. Note that the majority of the design of Curator is responsive (i.e. does *not*
require a page re-load) but that some of the vendors we rely on like Tableau do require a page re-load to determine the
correct layout. Therefore, resizing the browser window may not always trigger the correct layout for all content.

If you would like to fine-tune the existing mobile behavior, you can do so by adjusting the following settings in your
theme.

## Configuring the Mobile Breakpoint

To change the width at which the portal switches to mobile view:

1. <BackendNavPath />
2. Change the **Mobile Width** value (default: 1025 pixels) to your preferred breakpoint.
3. Click **Save** to apply your changes.

## Device Layout Override

The **Device Layout Override** setting controls breakpoints specifically for Dashboard rendering, independent of
the navigation breakpoint described above. When enabled, two additional fields appear:

* **Tablet Layout Size** — the width threshold below which Dashboards render at tablet dimensions (default: 992px).
* **Mobile Layout Size** — the width threshold below which Dashboards render at mobile dimensions (default: 768px).

If your Tableau Workbook was designed for a bigger tablet or your users view Dashboards in landscape orientation on devices like an iPad Pro, consider increasing *Tablet Layout Size* to around 1380px.

As with the Mobile Width setting, these breakpoints are evaluated at page load and are not re-evaluated when the
browser window is resized after the page has loaded.

To enable and configure Device Layout Override:

1. <BackendNavPath />
2. Toggle **Device Layout Override** on.
3. Set your preferred **Tablet Layout Size** and **Mobile Layout Size** pixel values.
4. Click **Save** to apply your changes.

## Override Tableau Container Size on Mobile/Tablet

The **Override Tableau Container Size on Mobile/Tablet** setting resizes the Tableau embed container to fit the
viewable screen area on mobile and tablet devices. This does not change the Tableau Dashboard itself — only the
container Curator renders around it. Enable this setting when filters, toolbars, or other UI elements overflow
off-screen on smaller devices.

<Note>
  This setting only appears when at least one Tableau connection is configured in your portal.
</Note>

To enable the override:

1. <BackendNavPath />
2. Set **Override Tableau Container Size on Mobile/Tablet** to **On**.
3. Click **Save** to apply your changes.

## Mobile Menu Styling

The colors used in the mobile navigation menu are configured separately from the desktop menu.

1. <BackendNavPath />

2. Update any of the following color settings as needed:

   * **Side/Mobile Navigation Trigger Color** — sets the color of the hamburger (☰) icon and the close (✕) button
     that appear when the portal is in mobile view. Default: `#999999`.
   * **Mobile Navigation Background Color** — sets the background color of the expanded mobile menu panel.
     Default: `#000000`.
   * **Mobile Navigation Text Color** — sets the color of the menu item text inside the mobile menu.
     Default: `#ffffff`.
   * **Mobile Navigation Underline Color** — sets the color of the divider lines between menu items in the mobile
     menu. Default: `#ffffff`.
   * **Mobile Navigation Active Item Color** — sets the background highlight color for the currently active menu
     item. Default: `#000000`.
   * **Mobile Navigation Active Item Text Color** — sets the text color of the currently active menu item.
     Default: `#ffffff`.

3. Click **Save** to apply your changes.

## Toolbar Mobile Settings

When the portal is in mobile view, the toolbar appears as a slide-out panel.

1. <BackendNavPath />
2. Update the **Toolbar Mobile Background Color** — sets the background color of the slide-out toolbar in mobile
   view. Default: `#ffffff`.
3. Click **Save** to apply your changes.

***

For a full list of all mobile-related theme fields and their descriptions, refer to the
[Themes controls reference](/site_content_design/theme/reference).


# Page Meta Titles (SEO)
Source: https://docs.curator.interworks.com/site_content_design/theme/page_meta_titles_seo

Configure page meta titles and SEO metadata to improve search engine visibility and social media sharing.

Meta titles play a crucial role in the realm of Search Engine Optimization (SEO) and website usability. When displayed
in search engine results or shared links via internal communication tools (e.g. Slack) meta titles serve as the first
impression of your content.

You can take advantage of Curator's meta title controls impacting the the meta titles for your entire site by creating
a site name, specifying a title on the home page.
*All other meta titles will be auto-generated based on the title of the content (e.g. Page Title, Dashboard Title).*

All Meta titles for individual pages will have this structure:

`Page Meta Title | Site Meta Title`

So for example, if we were to call our site "My Website", and create a page with a title of "My Page" that would result
in

`My Page | My Website`

## Changing the Site Meta Title

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings** > **Curator** > **Themes** section from the left-hand menu.
3. Click on the Theme you'd like to modify.
4. Click on the **Brand** tab and change the *Curator Site Name* field to show the Site Name you'd like to appear on
   every page.
5. Be sure to save your Theme settings.

## Changing the Homepage Page Meta Title

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to **Settings** > **Curator** > **Themes** section from the left-hand menu.
3. Click on the Theme you'd like to modify.
4. Click on the **Home** tab and change the *Curator Home Title (Meta tag)* field to show the Homepage Name you'd like
   to appear on the home page.  If you would like to have no homepage title, simply delete any text in this field.
5. Be sure to save your Theme settings.

## Changing the Page Meta Title for an individual Page

When creating a page, or analytic element (e.g. Tableau Dashboard), the Page Meta title will draw from the name of the
content given on the edit page.  The only exception to this is the homepage Meta Title which will override the page
being displayed on the homepage.  If you wish to change a Page's Meta title you must change teh Page's title itself.

## SEO Considerations

Remember that meta titles play a crucial role in SEO and determining how your website appears in search engine results.
Make sure to use relevant keywords, keep the titles concise (usually between 50-60 characters), and create compelling
titles that entice users to click through to your site. Also, check your website regularly to ensure the meta titles
are accurately representing the content and objectives of your pages.


# Themes Controls Reference
Source: https://docs.curator.interworks.com/site_content_design/theme/reference

Setting up a New Theme or revamping an existing one? There are dozens of customizations you can make to your Curator Portal's theme, and the controls can be a bit overwhelming. This page will help you find just the controls you're looking for. When utilizing these controls, the control area will populate on the left side of your page an a preview pane will take up the majority of the main space. For most changes, you should be able to see the live update to the preview. 

<Note>
  **Default Themes**: When editing the Main Theme Default will follow the notes below. If
  you are editing a secondary theme (not set in Portal Settings as your Global Theme),
  the "Default" option will follow the notes below unless you have the **Use Global Theme for Defaults** toggle enabled
  at the top of your theme. If that toggle is switched to ON, Default options in your Theme will follow the settings
  chosen for your **Main Theme**.
</Note>

<img alt="image.png" title="image.png" />

More information can be found in the [Themes](https://docs.curator.interworks.com/site_content_design/theme/curator_styles) section.

## Brand

This section allows you to customize the branding, logos and search result descriptions for your portal.

**Logo** - upload a logo image (.jpg, .gif, .svg, or .png format) for your homepage and menu bar

**Logo Padding** - adds padding to your logo image. By default, adding padding to one side adds an equal padding to all sides, but this can be unlocked for independent padding on all sides as well.

**Favicon** - upload an icon to be used in browser tabs and location bar (.jpg or .png format)

**Portal Description** - Adds a \<meta> tag or description for search results if your portal will be searchable via search engine.

**Default Preview Image** - upload and add a default preview image to search results and copied/embedded links.

**App Icon** - Upload an icon that will be used on the home screen when someone bookmarks your portal on a mobile device

## Home

You can add and control the behavior of your Portal's homepage from this section

**Homepage** - This controls the content displayed on your portal's homepage. You can choose a created home/landing , show a specific or random dashboard, or employ a redirect. By Default, Curator's default homepage is chosen.

**Homepage Page** - When the Homepage Type is set to "Page" or "Default," use this option to choose the [page ](https://docs.curator.interworks.com/site_content_design/pages/pages_overview)you display as your portal's Homepage.

**Show Page Title on Homepage** - When the Homepage Type is set to "Page," use this option to display the selected
page's title at the top of the homepage. Options are Off and On. Default is Off, as the homepage hides page titles.
The title only appears when all three of the following allow it:

1. Hide All Titles and Hide Page Titles in the Title Display section. If either is set to "Hide," no title appears,
   whatever this option is set to.
2. This option. If it is Off, no title appears on the homepage, even when the page shows its title everywhere else.
3. The page's own Show Title toggle in the page editor, which applies when the two settings above are set to "Show."

**Redirect Location** - When the Homepage Type is set to "Redirect," use this option to set the URL for your homepage to redirect to.

**Curator Home Title \[Meta Tag]** - add a meta tag here to be appended to the homepage for SEO and link previews in search engine results.

## Global

**Main Body Background Color** - Sets the background color for the main body of the site. This control impacts pages, dashboards, and forms throughout the site.

**Background Image** - Ad an image instead of a solid background color to your portal. This will also impact pages, dashboards, an forms throughout the site.

### Search Options

**\*Note: (Search must be enabled in Portal Settings to utilize these options)**

**Search Icon** - Upload a custom icon for search on your portal. This icon will appear in the menu/navigation bar of your portal when search is enabled. The default icon is a magnifying glass.

**Search Result Background Color** - Sets the color for the background of search results from the menu/navigation search bar.

**Search Result Text Color** - Sets the color for the text of search results from the menu/navigation search bar

### Alerts Options

* **Flash Error Text Color** - Sets text color for flash error messages
* \*\*Flash Error Background Color \*\*-Sets background color for clash error messages (default is red)
* **Flash Info Text Color** - Sets text color for flash information messages (informational notices, etc.)
* **Flash Info Background Color** - Sets background color for flash information messages (default blue)
* **Flash Success Text Color** - Sets text color for flash success messages (slide capture, form submission success)
* \*\*Flash Success Background Color \*\*- Sets background color for flash success messages (default is green)
* **Flash Warning Text Color** - Sets text color for flash warning messages
* **Flash Warning Background Color** - sets background color for flash warning messages (default is yellow)

### Loading Bar Options

* \*\*Loading Indicator Color \*\*- Sets color for loading bar across the top of a page when it is loading inside the portal

### Mobile Settings

* **Mobile Width** - Sets the screen width (in pixels) that triggers the portal to change from desktop to mobile view
* **Device Layout Override** - When enabled, allows you to manually input screen size trigger for both tablet and mobile layouts for dashboard rendering.
* **Override Tableau Container Size on Mobile/Tablet** - When enabled, resizes the Tableau embed container to fit the viewable screen area on mobile and tablet devices. This affects only the Curator container, not the Tableau Dashboard itself. Only visible when a Tableau connection is configured.

## Fonts

This section allows you to control the font family(ies), weight, size, and color throughout your portal. The top section controls the default, and each sub-section allows you to further customize the fonts for different areas and uses inside the portal.

## Menu

This section allows you to control the navigation section of your portal, including the menu your portal will use. Menu items can be added and edited in the Navigation section of the portal.

**Menu Dropdown** - Allows you to choose the Menu to use in your portal. The option you choose here will be the highest level of the menu and all navigation items nested underneath will show in your portal's navigation bar.

**Navigation Type** - Controls the location and format of the menu bar in your portal. You can choose between Top Navigation, Side Navigation, and Mega Menu. The Default option is Top Navigation.  Examples of these options are located in the [Titles & Toolbar section](https://docs.curator.interworks.com/site_content_design/theme/titles_and_toolbars).

**Hide Menu on Scroll** - When enabled, the navigation bar automatically hides when the user scrolls down and reappears when they scroll back up. Options are Off and On. Default is Off. This option is available when Navigation Type is set to Top Navigation or Mega Menu.

**Navigation Background Color** - Controls the background color of your menu bar/navigation

**Navigation Text Color** - Controls the color of the Text in your menu bar/navigation

**Navigation Highlight Color** - Controls the color of the of a highlighted menu item. This option also controls the color for the text on Menu Breadcrumbs for side navigation that can be enabled under **Theme > Titles & Toolbar > Enable Menu Breadcrumbs**.

### Menu Styles

* **Navigation Alignment** - Sets whether navigation items align to the right or left. Default is Right-aligned.
* **Menu Height** - Allows you to set the height of your menu/navigation bar in pixels
* **Drop Shadow** - Allows you to turn on or off the shadow for your menu/navigation bar.
* **Navigation Border Width (px)** - Allows you to set the width of the border on your navigation menu/bar
* **Menu icon size** - when you elect to add a menu icon, this control allows you to choose the size of the icons next to your menu/navigation items. Options are small, medium, and large.
* **Menu icon spacing** - Sets the distance between a menu icon and its label in pixels. The default distance is 2 pixels.

### Menu Text Options

* **Top Level Menu Font Transform** - Allows you to transform the top level menu font. Options are Default, None, Capitalize, Uppercase, Lowercase. Default is no transformation.
* **Top Level Menu Font Style** - Sets font style for top level menu items. Options are Default, Normal, Italic, Oblique. Default is Normal style.
* **Top Level Menu Font On Hover** - Allows for Top Level Menu Items to be Underlined on hover. Options are Default, Normal, and Underline. Default is Normal/Not Underlined
* **Drop Down Font Transform** - allows you to transform the dropdown/sub items menu font. Options are Default, None, Capitalize, Uppercase, Lowercase. Default is no transformation.
* **Drop Down Font Style** - Sets font style for dropdown menu items. Options are Default, Normal, Italic, Oblique. Default is Normal style.
* **Drop Down Font on Hover** - Allows for Dropdown Menu Items to be Underlined on hover. Options are Default, Normal, and Underline. Default is Normal/Not Underlined

### Menu Color Options

* **Top Level Active Item Color** - Sets the background color for the active top-level menu item. Default is Black
* **Top Level Active Item Text Color** - Sets the text color for the active top-level menu item. Default is white.
* **Dropdown Background Color** - Sets the background color for the dropdown menu items. Default is Black.
* **Dropdown Text Color** - Sets the text color for the dropdown menu items. Default is white.
* **Dropdown Hover Background Color** - Sets the background color for dropdown menu items on hover. Default is black.
* **Dropdown Hover Text Color** - Sets the text color for dropdown menu items on hover. Default is white.

### Side Navigation

These options appear on the **Menu** tab when **Navigation Type** is set to Side Navigation.

* **Collapse Side Nav By Default** - When enabled, the side navigation loads collapsed to a narrow icon-only rail (with the logo still visible) on desktop, leaving more room for content. This option appears only when **Collapsable Side Nav** is enabled. On mobile the full-size menu is always used, so this setting has no effect there. Options are Off and On. Default is Off.
* **Expand Collapsed Nav By** - Controls how users expand the collapsed side navigation. **Button** (the default) shows a control users click to expand and collapse the rail. **Hover** expands the rail while the pointer or keyboard focus is over it and collapses it again when they move away, with no button shown. This option appears only when **Collapse Side Nav By Default** is enabled.

### Mobile Menu

The mobile menu is triggered under the default settings when the browser window reaches 1025 pixels wide. You can adjust the window width for triggering the mobile menu in the Themes editor under **Menu > Mobile Settings > Mobile Width**.

* **Side/Mobile Navigation Trigger Color** - Sets the color for the mobile menu trigger (hamburger menu and 'X'). Default is white.
* \*\*Mobile Navigation Background Color \*\*- Sets the background color for menu items in the mobile menu. Default is black.
* **Mobile Navigation Text Color** - Sets the text color for menu items in the mobile menu. Default is white.
* **Mobile Navigation Active Item Color** - Sets the background color for the active menu item in the mobile menu. Default is black.
* **Mobile Navigation Active Item Text Color** - Sets the text color for the active menu item in the mobile menu. Default is white.
* **Mobile Navigation Underline Color** - Sets the color for the dividing line between mobile menu items. Default is white (set to blue in example below).
*

<img alt="image.png" />

## Titles and Toolbar

**Title and Toolbar Location** - Defines where content titles and toolbars should be located within your portal. Options are Default, Top of Page, Inside Top Nav, Beneath Top Nav, and Side Toolbar & Title Top of Page. Default is Top of Page. Examples of these options are located in the [Titles & Toolbar section](https://docs.curator.interworks.com/site_content_design/theme/titles_and_toolbars).

### Title Display

* **Hide All Titles** - Allows you to hide titles across every page type. Options are Default, Show, and Hide. Default is Show.
* **Hide Dashboard Titles** - Allows you to hide or show titles across Tableau and Sigma Dashboard Pages and Power BI Report Pages. These are dashboards and reports brought in directly from your analytics platform. Options are Default, Show, and Hide. Default is Show. Note - Sigma workbooks also have their own Show Title toggle in the workbook editor, which defaults to on. This theme setting takes precedence. If titles are hidden here, they stay hidden for every workbook and the toggle has no effect. If titles are shown here, each workbook can use its toggle to hide just its own title.
* **Hide Page Titles** - Allows you to hide or show titles across all Page content. Options are Default, Show, and Hide. Default is Show. Note - this option can be overridden on a page-by-page basis using the Show Title toggle in the page editor, or by placing a Page Title element in the page builder, which acts as a page-level override and always displays its title.

### Toolbar Styles

* **Hide Action Titles** - Allows you to show or hide the text/title under Action buttons on the Dashboard toolbar (Tableau Dashboards only). Options are Default, Show, and Hide. Default is Show.
* **Action Button Size** - Sets the size of Toolbar action buttons. Options are Small, Medium, and Large. Default is Large.
* **Enable Menu Breadcrumbs** - When enabled, shows breadcrumbs in sub-navigation that reflect menu item hierarchy (Side Navigation only). Options are Default, Off, and On. Default is Off.

### Toolbar Colors

* **Subnav Background Color** - Sets the background color for toolbar sub-navigation items. Default is white. Color is set to green in example image below.

  <img alt="image.png" />
* \*\*Subnav Text Color \*\*- Sets the text color for toolbar sub-navigation items. Default is Black. Color is set to default in example image above.
* \*\*Action Button Color \*\*- Controls the color of Action Buttons and text/titles on the toolbar. Default is black. Color is set to black in the example image above.
* **Accent Color** - The accent color applies to elements in Custom Views, Dashboard Export, Report Builder, Tutorials, Org Charts, Explorer Elements, Favorites, Dashboard commenting, Scorecard, and New and Updated flags. It is recommended to use a distinct color (not white or black) to indicate users are able to click on these elements to perform an action. The accent color also applies to buttons within the toolbar for Dashboards. The default color is white.
* **Accent Text Color** - Sets the text color for accent-button elements. The background color of these elements is generally controlled by **Accent Color**. Ensure that the Accent Color and Accent Text Color have sufficient contrast to make the text visible. The accent text color also applies to buttons within the toolbar for Dashboards. The default color is black.

### Toolbar Mobile Settings

* **Toolbar Mobile Background Color** - Sets the background color for the slide-out toolbar when in mobile view. Default is White.

## Dashboards

**Dashboard Full-Screen Margin** - Sets the left and right margins (in pixels) for fullscreen-width dashboards. This setting will apply only to dashboards that take up the full width of the screen and are set to 'range' or 'automatic' sizing.

### Dashboard Tabs Styles

* **Tab Shape** - Sets the corner shape for dashboard tabs. Options are Default, Square, Rounded, and Pill. Default rounds the top two corners and leaves the bottom two squared, so the active tab blends into the line beneath the tab strip. Square makes all four corners sharp. Rounded and Pill round all four corners and remove the line beneath the tab strip.
* **Default** - These controls set the background, text, and border color for dashboard tabs when enabled. Default for tab color is white. Default for text color is black. Default for tabs border color is black.
* **Active** - These controls set the background, text, and border color for the active dashboard tab when enabled. Default for tab color is black. Default for text color is white. Default for tabs border color is black.
* **Hover** - These controls set the background, text, and border color for the dashboard tabs on hover when enabled. Default for tab color is white. Default for text color is black. Default for tabs border color is black.

## Metrics

This section controls metrics chart and background colors for Tableau Metrics when in use within the portal.

## Pages

This section allows you to set default colors, styles, and options for tiles, tutorials, buttons, margins, and form styles across your portal.

**Thumbnail Tile Style** - Sets the default shape of tile elements across the Curator portal. Options are Default, Square, Landscape, Boxy, and Hex. Default is Square. Note - The default tile style can be overridden on an element-by-element basis in the Edit Page section of the backend. more information. More information can be found in the [Tiles](https://docs.curator.interworks.com/site_content_design/pages/tiles) section.

**Tile Text Color** - Controls the color of Text below tiles across Curator. The default is black.

**Button Shape** - Sets the default shape for buttons in your portal. Options are default, square, rounded, pill, and oval. Default is Square.

\*\*Hyperlink Color \*\*- Controls the hyperlink text color inside buttons. The default is black.

### Tile Styles

* **Tile Background Color** - Controls the background color for tiles. Default is white.
* **Tile Overlay** - Gives the ability to add a description or action buttons on hover for tiles. If the "Show Tile Description" control is set to 'On Hover,' the Action button option will not be shown. The default setting is None.
* **Show Tile Description** - Shows Description for tiles - description will only show for content that has a description added. Options are Default, Do Not Show, On Hover, and Below Tile. Default is to show the description on Hover.
* **Show Tile Title** - Controls the default setting for showing Tile titles across Curator. Options are Default, Show, and Hide. Default setting is to show titles.
* **Show Tile Dates** - Shows a Tableau Dashboard's created and/or last updated dates in the tile hover overlay, above the description. The dates are the ones reported by Tableau, so they match the dates shown on the Dashboard itself, and only appear for Tableau Dashboard tiles. Options are Off, Created Date, Updated Date, and Created and Updated Dates. Default is Off.
* \*\*Custom Default Thumbnail \*\*- Enables you to add a custom 'default' thumbnail for tiles where a thumbnail is not set within the content itself. If a file is not uploaded here, Curator will use its own default thumbnail for content where there is not a custom thumbnail, or when dashboard thumbnails cannot be retrieved.

### Tutorial Styles

* **Tutorial Title Text Color** - Controls the Color of the Title Text for Tutorials

* **Tutorial Header Font Size** - Sets the tutorial title font size (in pixels), independent of the theme's Header Font Size. Default is 18. Located on the **Fonts** tab.

  <img alt="image.png" />

### Button Options

* **Primary Buttons** - Submit buttons on forms, Close/Close and Do Not Show Again Buttons on Tutorials, Button elements on pages set to "Primary" under the Button Settings section will use these color settings.
  * **Primary Button Color** - Sets background color for primary buttons across the Curator portal. The Default setting is White.
  * **Primary Button Text Color** - Sets the text color for primary buttons across the Curator portal. The Default setting is Black.
  * **Primary Button Border Color** - Sets border color for primary buttons across the Curator portal. The Default setting is Black.
* **Secondary Buttons** - Button Elements on Pages set to "Secondary" under the Button Settings section will use these settings
  * **Secondary Button Color** - Sets background color for secondary buttons across the Curator portal. The Default setting is Black.
  * **Secondary Button Text Color** - Sets the text color for secondary buttons across the Curator portal. The Default setting is White.
  * **Secondary Button Border Color** - Sets border color for secondary buttons across the Curator portal. The Default setting is Black.
* **Cancel Buttons** - Clear and Cancel buttons on forms
  * **Cancel Button Color** - Sets background color for Cancel buttons across the Curator portal. The Default setting is White.
  * **Cancel Button Text Color** - Sets the text color for cancel buttons across the Curator portal. The Default setting is Black.
  * **Cancel Button Border Color** - Sets border color for cancel buttons across the Curator portal. The Default setting is Black.

### Page Margin

**Page Margin** - Sets the margins for pages in percentage. Default is 0%

### Form Styles

**Form Font Color** - Controls the font color for form elements on pages, including the text shown in a
dropdown both when it is closed and in the open list of options. Default settings is black.

\*\*Form Background Color \*\*- Controls the background color for dropdowns in form element dropdowns. Default setting is white.

\*\*Form Highlight Color \*\*- Controls the highlight color for dropdowns in form elements. Default setting is blue.

\<Note> Form Font, Background and Highlight color controls also affect dropdowns (Custom views, download options, etc.) inside the toolbar for dashboards\</Note>

### Accordion Collapse Styles

\<Note>These controls apply to Accordion elements on pages\</Note>

**Accordion Header Font Color** - Controls the font color for the section headers for accordion elements. The default color is white

\*\*Accordion Header Background Color \*\*- Controls the background color for the section headers for accordion elements. The default color is blue.

\*\*Accordion Header Border Color \*\*- Controls the border color for the section headers for accordion elements. The default color is white.

\*\*Accordion Body Background Color \*\*- Controls the background color for the body section for accordion elements. The default color is white. Text color for the body section is controlled within the element's text editor itself.

## Loading Screens

Curator Loading Screen - This control allows for loading screens while users are waiting for content to load in the portal. Options are Default, Off, and On. Default option is On. In order to enable the additional controls in this section, the Loading Screen must be set to Default or On.

**Default Loading Screen** - This controls the loading screen that shows by default for elements in Curator. Some elements in Curator, such as Tableau Dashboards, can have individually set loading screens.

**Show Dashboard Thumbnail During Load** - This option must be de-selected if Curator Loading Screen is set to On or Default. When loading screens are not enabled, this control allows for dashboard thumbnails to display while dashboards load.

**Display Loading Screen During Login** - This control allows the default loading screen to show after a user logs into Curator while homepage content loads.

## Footer

**Footer Menu** - This control allows you to select a menu to be displayed in the footer throughout the Curator portal. More information on creating and managing menus can be found in the [Menu section](https://docs.curator.interworks.com/site_content_design/menus/managing_menus). You can choose a footer menu or footer page for your portal. By default, no footer is shown.

**Footer Insert Page** - This control allows for a page to be inserted as a footer throughout the portal. More information on creating pages can be found in the [Pages section](https://docs.curator.interworks.com/site_content_design/pages/pages_overview).

### Footer Colors

\*\*Footer Background Color \*\*- controls the background color for footer pages and menu bars. The default is blue.

**Footer Text Color** - controls the text/font color for footer menu items. The default option is white.


# Titles and Toolbars
Source: https://docs.curator.interworks.com/site_content_design/theme/titles_and_toolbars

Customize page titles, toolbar elements, and navigation components to match your brand and improve user experience.

The title and toolbar location, for most options, are dependent upon one another for the styling of your site.  While
titles help your users understand where they are and what they are looking at,  Toolbars contain the action buttons that
allow your users to interact with, filter, export and even send scheduled emails of your embedded visualization.

**NOTE**: As of now, all actions are available for Tableau Dashboards. There is no feature parity for Power BI or ThoughtSpot.

## Title & Toolbar Location (examples below)

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`) and log in if prompted.
2. Navigate to **Settings** > **Curator** > **Themes** from the left-hand menu and select the Theme you'd like to update\*.
3. Chang the "Title and Toolbar Location" dropdown to modify the layout, using the live-preview to view your pending
   changes.
4. Click "Save" to apply your changes.

## Title Settings

Titles can be controlled globally, or by content type.  Follow the steps below to show or hide titles:

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`) and log in if prompted.

2. Navigate to **Settings** > **Curator** > **Themes** from the left-hand menu and select the Theme you'd like to update\*.

3. Click on the \**Titles & Toolbar* tab and expand the "Title Display" section.

4. Choose from one of the options below

   * Hide All Titles: Hides all titles - this will ensure that no titles display across your entire site, regardless of
     the page-type.
   * Hide Dashboard Titles: This allows control for titles on the page level, and automatically displays them (except for
     the homepage).  This setting is typically most useful if your dashboards already contain titles.
   * Hide Page Titles: This ensures all titles are displayed on Dashboard pages, but will not show up on Pages created with
     the page-builder. The exception is a page that contains an explicit Page Title element in the page-builder, which
     will still display that title.

5. Click "Save" to apply your changes.

Prior to the 2022-11-30, these setting can be found under:
**Settings** > **Curator** > **Portal Settings** > **Styles tab**.  Title and Toolbar location are found in the
"Menu options" section, global title settings are found in the the "Global Settings" section, Dashboard title settings
are under the "Dashboard Styles" section, and Page title settings are under the "Page Styles" section.

## Title & Toolbar location examples

### Top Navigation and Mega Menu

#### Top of page: Top Navigation and Mega Menu

Have your title at the top of a page and the toolbar situated right beneath it. With this option, you can further adjust
your toolbar in the *Toolbar Styles* and *Toolbar Colors* sections.

<img alt="Top Navigation and Top of page Title/Toolbar Location" />

* *Hide Action Titles* - If enabled the toolbar buttons will not show any titles on a desktop screen. Hovering over a
  button will show the title to clarify functionalities.

* *Action Button Size* - Choose between large, medium, and small-sized buttons to save space or prevent wrapping. The
  default size is large.

#### Inside of top nav: Top Navigation and Mega Menu

The title and toolbar move inside the navigation bar along the top of the screen. They are placed between the menu items
and the user menu. Make sure you have enough space to have everything readable.

<img alt="Top Navigation and Inside of top nav Title/Toolbar Location" />

#### Beneath top nav: Top Navigation and Mega Menu

Create a second navigation-like bar right beneath your actual navigation. The title and toolbar move next to each other
inside one row. You can set the background, *Subnav Background Color*, and text color, *Subnav Text Color*, in the
*Toolbar Colors* section.

<img alt="Top Navigation and Beneath top nav Title/Toolbar Location" />

#### Side toolbar & title top of page: Top Navigation and Mega Menu

The title and toolbar get separated using this configuration.  The title moves inside a second navigation-like bar right
beneath your actual navigation. The toolbar moves to the right side of the screen, next to your Dashboard. Clicking a
button triggers a slide-out to view further actions. You can set the background, *Subnav Background Color*, and text
color, *Subnav Text Color*, in the *Toolbar Colors* section.

<img alt="Top Navigation and Side Slide-out Title/Toolbar Location" />

### Side Navigation

#### Top of page: Side Navigation

Have your title at the top of a page and the toolbar situated right beneath it. With this option, you can further adjust
your toolbar in the *Toolbar Styles* and *Toolbar Colors* sections.

<img alt="Side Navigation and Top of page Title/Toolbar Location" />

* *Hide Action Titles* - If enabled the toolbar buttons will not show any titles on a desktop screen. Hovering over a
  button will show the title to clarify functionalities.

* *Action Button Size* - Choose between large, medium, and small-sized buttons to save space or prevent wrapping. The
  default size is large.

#### Top nav bar: Side Navigation

Create a second navigation-like bar right beneath your actual navigation. The title and toolbar move next to each other
inside one row. You can set the background, *Subnav Background Color*, and text color, *Subnav Text Color*, in the
*Toolbar Colors* section.

<img alt="Side Navigation and Beneath top nav Title/Toolbar Location" />

The color of the toolbar buttons can be set under in the *Toolbar Colors* section.


# Email Formatting
Source: https://docs.curator.interworks.com/site_content_design/user_notifications_and_email/email_formatting

Customize email templates and formatting for automated notifications, reports, and user communications.

## Requirements

Before moving on, it's important that you follow the [steps to configure email](/setup/email/email_configuration)
on Curator.

## Email Template Formatting

When users from both the front-end and back-end are notified via Curator, they will be notified via e-mail.  This will
include all notifications such as password reset, welcome-messages on first log in, backend administrators gaining
access, and scheduled report emails.

In order to modify the background, body-color, as well as adding a header image to your emails, you can find all the
available controls for email formatting on the left-hand menu under **Settings** > **Mail** > **Mail branding**.

## Email Content

If you would like to change the messages inside of your emails, you *can* modify the templates on the backend via
the left-hand menu under **Settings** > **Mail** > **Mail templates**.  **Proceed with caution if you are modifying
these templates - they require very exact specifications**.  If you need to reset your templates and are unable to do so
please reach out to Curator support.


# Error Pages 
Source: https://docs.curator.interworks.com/site_content_design/user_notifications_and_email/error_pages

Configure custom error pages to provide helpful messaging when users encounter access issues or broken links.

When things go wrong, you want to be sure to send the right messages to your audience.  By default, Curator has error
pages that will let users know when they don't have access, they visit a broken link, or a system is down.
Communicating exactly what you'd like in these situations can be made even easier by sending your users to a custom-made
error page.

**NOTE**: You must [create a page](/site_content_design/pages/pages_overview)
first before setting it to your error page

## Setting up "Not Found" or "Access Denied" Pages

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).

2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.

3. Click on the "General" tab and expand the "Error Pages" section.

4. Using the dropdown, select a page from the list of pages you have created on Curator. You can set two pages here:

   * Access Denied (403) - Displays when a user does not have access to a specific link on Curator.
   * Not Found (404) - Displays when a user visits a link that does not exist on Curator, or visits an old deleted/moved link.

5. After making your selection from these dropdowns, save the Settings page.

**NOTE**: The Access Denied page is a portal-wide setting. Curator does not support per-Dashboard or per-group overrides
for this page, so the same Access Denied page displays for every restricted link regardless of which Dashboard or user
group triggered it. As a best practice, create a single custom page with general access-request guidance (for example,
instructions for contacting an administrator to request access) rather than Dashboard-specific messaging. For more
context, see the [Pages Overview](/site_content_design/pages/pages_overview) and
[Frontend User Permissions](/users_groups/user_security/frontend_user_permissions) documentation.

## Setting up "Tableau Server Down" (503 error) Page

Occasionally your Tableau Server may go down for maintenance reasons, or even unplanned issues.  In this case it's
helpful to tell your users that things will be back shortly, and redirect them to useful resources.
Follow the steps below to ensure your custom page displays when your Tableau Server is unavailable.

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Tableau** > **Tableau Server Settings** section from the left-hand menu.
3. From the "General" tab expand the "Errors" section.
4. Using the "Tableau 503 Error Page" dropdown, select a page from the list of pages you have created on Curator.
5. After making your selection from this dropdown, save the Settings page.

## Troubleshooting

If you have configured a custom Access Denied (403) or Not Found (404) page but users are still seeing the default
Curator error page instead of being redirected to your custom page, work through the steps below.

### Verify Your Curator Version

A bug in earlier Curator releases could prevent custom error pages from being saved or applied correctly. Confirm that
your instance is running Curator version `2026.04-05` or later, where this issue was fixed. The version is shown in the
backend under **Settings** > **Curator** > **System Upgrade**, or to the right on the backend home page.

### Confirm the Page Is Still Selected

1. Navigate to **Settings** > **Curator** > **Portal Settings** and expand the "Error Pages" section under the "General"
   tab.
2. Verify that your custom page is still selected in the Access Denied (403) or Not Found (404) dropdown. If the
   dropdown is empty, the page may have been deleted or renamed -- re-select it and save.
3. Open the page itself under **Content** > **Pages** and confirm it still exists and is published.

### Rule Out Browser Caching

Browsers can cache error responses, which may make it appear that the custom page is not being served even after the
configuration is correct. Open a private/incognito browser window and revisit the URL that triggers the error to
confirm the custom page is displayed for a fresh session.


# Notices 
Source: https://docs.curator.interworks.com/site_content_design/user_notifications_and_email/notices

Create and manage site-wide or page-specific notice banners to communicate important information to users.

Curator supports adding a text banner across the top of individual pages. These can either be created on a per-menu-item
basis, or set globally to appear across every page on your site.

***To create a notice:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Content** > **Notices** section from the left-hand menu.
3. Create the notice by filling out the title and body of the notice.
4. Click the checkboxes at the bottom of the page next to the menu links you would like the notice to be associated with.
5. Save the notice to create it.
6. (optional) After the notice has been saved/created, you can now check the "Set this as the Global Notice"checkbox and
   save again to set the global notice.


# Tutorials 
Source: https://docs.curator.interworks.com/site_content_design/user_notifications_and_email/tutorials

Create interactive tutorials and help documentation to guide users through dashboard features and site functionality.

Tutorials can be used to explain how to use a page, embedded visualization, or for any other supporting documentation
related to content on your Curator site.

They can be shown every time a Dashboard is viewed, a fixed number of times the Dashboard is viewed, or only when clicked
on by a user.

***To create a tutorial:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Content** > **Tutorials** in the left-hand menu. (or in earlier versions **Tableau** > **Tutorials**).
4. Click the "New Tutorial" button.
5. Enter the title, description and content of the tutorial in the appropriate fields. The content field allows for
   fully formatted content, including images, links, etc.
6. Enter the number of times the tutorial should be shown in the "Maximum Views" field.
   * Entering zero in this field means the tutorial will only be shown if the user clicks to see it.
   * Entering -1 in the field means the tutorial will be shown each time the user views the Dashboard until they click
     to not show it again.
7. You can control the size and location of the tutorial on the page by adjusting the pixel value for width, height,
   top position and left position. Leave blank to use the system default.
   * Top position is the number of pixels below the top of the page (0px is at the very top)
   * Left position is the number of pixels from the left of the page (0px is at the very left)
8. A highlighted image can be added by selecting an image from "Highlight Image". Once selected you can control the
   highlighted section by adjusting the pixel value for top position, left position, right position and bottom position.
   * Pixel value determines the size of highlighted area, starting from the top left. For example, if top position is
     10px and bottom position is 100px, the highlighted area will start 10px below the top of the image and end 100px
     below the top.
9. Multiple slides can be created by clicking "Add New Item"
10. Click the "Create" button.

## Styling the Tutorial Header

The tutorial title font size is controlled independently of the rest of your portal's typography. Set it under
**Theme > Fonts > Tutorial Header Font Size (px)**. Adjusting this value affects only the tutorial modal title and
leaves the theme's **Header Font Size** (and the page titles and sub-headings it drives) unchanged. The default is
18px.

## Setting Tutorials on Individual Content Pages

**Dashboards:**

1. While editing the Dashboard, click on the "Misc" tab.
2. Expand the "Education" section.
3. Select the desired tutorial.
4. Click the "Save" button.

**Pages:**

1. While editing a page, click on the "Misc" tab.
2. Scroll to the "Page Details" section at the bottom of the page.
3. Select the desired tutorial for the **Tutorial** field.
4. Click the "Save" button.

On a page that has an assigned tutorial but no embedded Dashboards, a tutorial button (a graduation-cap
icon) appears in the page title bar so users can re-open the tutorial at any time. This button is only
shown while the page title is visible — it is hidden if **Show title** is disabled for the page, or if no
tutorial is assigned. On pages with embedded Dashboards, each Dashboard's tutorial button continues to
appear in that Dashboard's toolbar.

## Setting Tutorials Across Multiple Pages

**Global Tutorials\***(applied across every page of your Curator portal):

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Curator** > **Portal Settings** in the left-hand menu.
4. In the Portal Settings page, click on the "General" tab at the top.
5. Select the desired tutorial in the "Global Tutorial" field under the "Global Settings" section.
6. Click the "Save" button.

\*NOTE: \*\*For versions prior to the **2023.05.31-10** release, "Global tutorials" were not truly global.
To enable a tutorial across all pages for these versions, you will also need to explicitly select a
homepage tutorial (instructions below).

\*NOTE: \*\*For versions prior to the **2023.05.31-10** release to set tutorials across *every single page*
on your Curator site, you will also need to explicitly select a homepage tutorial

**Homepage Tutorials:**

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Curator** > **Portal Settings** in the left-hand menu.
4. In the Portal Settings page, click on the "General" tab at the top.
5. Select the desired tutorial in the "Homepage Tutorial" field under the "Global Settings" section.
6. Click the "Save" button.


# Backend Administration Tutorial: Adding Content
Source: https://docs.curator.interworks.com/tutorials/backend_administration/quick_start_adding_content

Step-by-step tutorial for adding content to Curator backend including dashboards and data sources.

<iframe title="YouTube video player" />


# Backend Administration Tutorial: Filters, Parameters, Tutorials & Loading Screens
Source: https://docs.curator.interworks.com/tutorials/backend_administration/quick_start_adding_content_filters_parameters_tutorials_loading_screens

Advanced tutorial covering filters, parameters, tutorials, and loading screens configuration in Curator backend.

<iframe title="YouTube video player" />


# Backend Administration Tutorial: Menu and Navigation
Source: https://docs.curator.interworks.com/tutorials/backend_administration/quick_start_adding_content_menu_and_navigation

Tutorial for creating menus and navigation structures in Curator backend for organized content access.

<iframe title="YouTube video player" />


# Backend Administration Tutorial: Styling
Source: https://docs.curator.interworks.com/tutorials/backend_administration/quick_start_styling

Backend tutorial for customizing visual styling, themes, and design elements in Curator.

<iframe title="YouTube video player" />


# Frontend Experience Tutorial: Dashboard
Source: https://docs.curator.interworks.com/tutorials/frontend_experience/quick_start_dashboard

Frontend tutorial for embedding and customizing dashboard presentations and user interactions.

<iframe title="YouTube video player" />


# Frontend Experience Tutorial: Homepage
Source: https://docs.curator.interworks.com/tutorials/frontend_experience/quick_start_homepage

Frontend tutorial focused on customizing and configuring the homepage layout and user experience.

<iframe title="YouTube video player" />


# Get Started with Curator in 5 Minutes
Source: https://docs.curator.interworks.com/tutorials/get_started_with_curator_in_5_minutes

Quick start guide to get up and running with Curator in just 5 minutes including essential setup steps.

<iframe title="Get Started with Curator in 5 Minutes" />


# Curator Backup
Source: https://docs.curator.interworks.com/upgrading_migration/backups/curator_backup

Learn about Curators comprehensive backup options beyond basic Import/Export functionality.

The Import / Export is a great way to backup your Curator data but sometimes a more complete backup is
needed. The Full Backup will export an entire snapshot of all your Curator data (it's a full database and
filesystem backup of the Curator webroot directory). Curator will even show you up-to-date stats on how much
free space you have available on your server to ensure you have room.

<Note>
  Moving Curator onto new server hardware is built on top of a full backup. See
  [Moving Curator to a New Server](/upgrading_migration/migration/moving_to_a_new_server) for the end-to-end
  process.
</Note>

***Modifying the Full Backup Settings***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Backups** in the left -hand menu.
3. Click on the gear icon to display a popup.  From here you can modify the location/frequency and retention options.

***Backup Retention and Disk Space***

This section applies to Curator On-Prem. For Curator SaaS, see the
**Curator SaaS (InterWorks-Hosted) Notes** at the end of this page.

Curator defaults to a **weekly** backup schedule that keeps **2** backups. Both values live in the gear icon
popup. **Backup Schedule** offers Manual, Daily, Weekly and Monthly. **Backup Retention** ranges from
**Keep 1** to **Keep 10**.

Curator purges old backups only while a full backup runs, and only when **Backup Schedule** is set to
something other than **Manual**. A purge deletes the oldest completed backups until the retained number
remains, and it always leaves at least one in place. On the **Manual** schedule, Curator never deletes a
completed backup, so backups build up until you remove them.

Curator purges at the start of a backup, before the new file exists, and again once the new backup is
packaged. Lowering **Backup Retention** and then taking a backup removes the extra copies straight away,
even if that backup later fails.

To reclaim space:

* Delete backups one at a time from the Backups list view using the trash icon in the **Actions** column.
* Delete the `full_backup_*.zip` files from the directory shown in **Backup Location**. That path is
  `<web root>/storage/temp` by default. Each filename
  includes the date and time of the backup. Deleting one gives up that restore point, but it does not touch
  the live Curator database or files.

To make Curator clean up on its own, set **Backup Schedule** to Daily, Weekly or Monthly and pick a
retention count that fits the free space you have. Cleanup only happens when Curator's scheduled tasks run.
If scheduled backups never appear, see the cron troubleshooting guide for
[Linux](/server_management/system_administration/linux_cron_troubleshooting) or
[Windows](/server_management/system_administration/windows_cron_troubleshooting).

***Troubleshooting Failed or Stuck Backups***

The cron guides above cover the case where the schedule never fires at all. A backup that does start but never
finishes is a different problem, and the place to look first is
**Settings** > **Curator** > **Queued Processes**.

Every full backup, scheduled or manual, runs as a "Curator Backup" job in that queue. While it runs, the job's
status moves through "Step 1 of 3: Backing up the Curator filesystem.", "Step 2 of 3: Backing up the Curator
database." and "Step 3 of 3: Packaging the full backup file." Step 1 can take a long time on a large webroot,
so a job sitting on that step is not necessarily stuck. A job that stays on **Pending** instead usually means
the queue itself is not being processed rather than that the backup failed. Two backups queued back to back
run one after the other, never at the same time. See
[Queued Processes](/site_administration/performance/queued_processes) for how to read, unblock and clear that
list.

When a backup fails part way through, Curator normally removes the job from the queue just as it does for a
successful one, so a failed backup usually leaves nothing behind in **Queued Processes**. The signal to watch
for is the job disappearing from the list without a new archive appearing under **Settings** > **Curator** >
**Backups**. Some failures do leave a job in the list with a status beginning with "Error:", which you can
remove with **Clear Errors** once you have read the log.

Either way, the reason is written to the log. Search `storage/logs/system-*.log` for the date the backup ran
(the same entries appear in the Event Log). The backup job records one of these:

* `ERROR: Unable to dump Curator database during backup` — the database dump step failed, or produced a file
  smaller than 100 KB. Confirm that `mysqldump` is on the PATH of the account that runs Curator's scheduled
  tasks, that the database credentials in Curator's configuration work from the Curator server, and that the
  installed `mysqldump` matches the database server version.
* `ERROR: Not enough space for full backup.` — free disk space on the server is smaller than the size of the
  last backup. Free up space or lower **Backup Retention**, then take a new backup. This check does not apply to
  Curator SaaS, where InterWorks manages the server and its storage.
* `ERROR: Unable to backup Curator files` — the **Backup Location** is not writable by the user Curator runs
  as, or the webroot zip step failed. The log entry names the path. See
  [Filesystem Permissions](/server_management/system_administration/filesystem_permissions) to correct the
  permissions on that folder.

A failed database dump does not stop the rest of the backup. Curator finishes packaging the files and appends
`_NO_DATABASE` to the archive name, and the Backups list shows "Does not include a database export!" against
it. A backup with that suffix cannot restore your database, so treat it as incomplete: fix the cause and take
a new backup.

***To Manually Create a new Curator Backup:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Backups** in the left-hand menu.
3. Click the "Take New Backup" button to start a backup.  If you would like to check the status of the backup
   while it is running, you can view the active status under the
   **Settings** > **Curator** > **Queued Processes** in the left navigation.

***To Queue a Backup From a Script:***

Automation (for example a scheduled job that refreshes a test environment) can queue a backup and check on
it through the Curator API instead of the backend. Call `/api/v1/portal/queueBackup` with an API key to
queue one, then poll `/api/v1/portal/listBackups` until the new archive shows a `Ready` status. If the queued
row disappears from that list and no new archive appears, the backup failed; check the system log under
`storage/logs/` for the error. Both endpoints are described under
[Curator API](/curator_api/api_docs/curator_api#portalqueuebackup).

***To Restore From a Full Backup:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Backups** in the left navigation.
3. Find the backup from the list view (NOTE: They are all appended with a timestamp from when they were
   taken), and click the "Restore Backup" icon (counter clockwise arrow) to restore Curator to exactly mirror
   the time the backup was taken.

***Curator SaaS (InterWorks-Hosted) Notes***

On Curator SaaS instances, InterWorks hosts your instance and manages its storage. The behavior described
above differs in two important ways:

* **The Backups list view shows only the 10 most recent `.iwe` backups**, even when more exist. Older
  backups are retained by InterWorks and are still recoverable, but they will not appear in the backend list
  view. If you need to restore from a backup older than the 10 most recent, contact InterWorks support.
* **The configured retention schedule does not purge `.iwe` or `.iwgz` backup files on SaaS.** These backup
  files accumulate indefinitely, and they are held under a compliance lock that prevents deletion or
  modification for the duration of the lock period. Retention settings in the backend gear icon popup have no
  effect on `.iwe` / `.iwgz` retention for SaaS deployments. To manage these files on SaaS, contact InterWorks
  support.


# Manual Restoration of Curator Backup
Source: https://docs.curator.interworks.com/upgrading_migration/backups/manual_restoration_of_curator_backup

Step-by-step guide for manually restoring Curator from a full backup when automated restoration fails.

If you haven't attempted to use the Curator interface to restore from a full backup, go do that now
(Backend> Settings > Curator > Import/Export > Full Backup tab).
This guide is only needed if that fails for some hard-to-fix reason and it's an emergency to restore from a full backup.

It's also worth noting that, by default, Curator's full backups are stored on the same server as Curator.  If
something were to happen to the server, these could potentially disappear at the same time that Curator
does.  Please take steps to set up a server-level backup and/or store Curator's full backups in a safe, external location.

<Note>
  If you are restoring this backup onto new server hardware, see
  [Moving Curator to a New Server](/upgrading_migration/migration/moving_to_a_new_server) for the full sequence
  this step belongs to.
</Note>

## Preface

Curator's full backups are a zip archive containing the following files:

* MySQL/MariaDB database dump (as a SQL script)
* The contents of Curator's web root directory, which contains all of the code, configuration, and uploads (as a zip archive)

The restoration process essentially overwrites all of the files on the server with the contents of the web
root directory and runs the SQL script to overwrite the database.  These are the steps you'll need to perform
when manually restoring from a full backup.

## Handling Different Database Connections

Curator stores the database connection details in `<web root>/config/database.php`.  The zip archive of the
web root within a full backup also contains these connection details.  If the database connection differs
from the system the backup originated from to the system being restored over, you'll need to perform these
steps prior to restoring:

1. Unzip the full backup zip archive to a temporary location (i.e. not inside either Curator portal’s actual web root).
2. Unzip the web root zip archive.
3. Modify the `config/database.php` file as needed in the extracted web root folder to match the connection
   details of the database you'll be restoring over.
4. Re-zip the extracted web root folder (use the same file name for the resulting zip archive).  DO NOT zip
   up the folder itself, just the contents (you should have a list of folders including plugins, storage, and vendor).
5. If the MySQL/MariaDB database name (not to be confused with host or username) differs, rename that part
   of the database dump SQL script.  Be sure to retain the date-stamp and file extension portions of the file
   name.  Also, open the file and update any references to the database name in the first \~30 lines.
6. Re-zip the web root zip archive (not to be confused with the extracted web root directory) and the
   database dump SQL script as the full backup (use the same file name for the resulting zip archive).
7. Transfer the updated full backup zip archive to the system you wish to restore over and place it in the
   directory where full backups are stored (default is `<web root>/storage/temp/`).

## Manually Restoring the Database

If you haven't already, unzip the full backup zip archive to extract the database dump and transfer that SQL
script to the system you'll be restoring over.

Make the following replacements in the commands below.  If you don't know the values, look at the
`<web root>/config/database.php` file on the system you'll be restoring over.

* `$host`: The database host.  This is normally localhost unless you have an external database.
* `$user`: The database username.
* `$port`: This is almost always 3306, unless you've customized your database configuration to run on a different port.
* `$name`: This is the database name.  Each MySQL/MariaDB host can store many different databases, usually
  this is Curator, but it could be different.
* `$dbDumpFilename`: This is the file name to the database dump file.  Include the full file path if running
  the command from a different directory that where the SQL script lives.

*NOTE: You will be prompted for the database password while the command runs.*

```MySQL theme={null}
mysql -h $host -u $user -p --port=$port --database $name < $dbDumpFilename
```

## Manually Restoring the File System

### Step 0 for Linux Systems

Before beginning on Linux systems, run the following commands to determine which system user and group owns
Curator's web root.  It will be needed during the process.

```Linux theme={null}
cd /var/www/html
ls -l
```

The user and group should either be `apache` or `www-data` and should be listed next to all of the files.
The commands below will assume apache, but replace it with www-data if your system lists it here instead.

### Restoration Process

1. If you haven't already, unzip the full backup zip archive to extract the web root directory backup and
   transfer that zip archive to the system you'll be restoring over.
2. In a temporary location on the Curator server outside of Curator's web root directory (make note of the
   location), unzip the web root directory backup (i.e. the file that matches the pattern: `webroot_YYYYMMDD_HHMMSS.zip`).
   * Linux Command:
     `sudo -u apache unzip webroot_YYYYMMDD_HHMM.zip`
   * On Windows systems, you should be able to utilize the built-in zip extract function, though
     alternatives like 7-zip may be faster.
3. In the web root directory, delete directories as follows:
   * Linux Command:
     `sudo rm -Rf /var/www/html/modules /var/www/html/plugins /var/www/html/themes /var/www/html/vendor`
   * On Windows systems, delete these folders using Windows Explorer:
     * modules
     * plugins
     * themes
     * vendor
4. Copy the contents of the extracted web root backup to the actual web root directory.
   * Linux Command:
     `sudo -u apache cp -a /path/to/extracted/webroot/backup/* /var/www/html/`
   * On Windows systems, use a copy/paste or select/drag operation within Windows Explorer.
5. Fix file permissions as needed.  See this document for details:
   [Filesystem Permissions](/server_management/system_administration/filesystem_permissions)


# Taking a Manual Full Backup
Source: https://docs.curator.interworks.com/upgrading_migration/backups/taking_a_manual_full_backup

Instructions for manually creating comprehensive Curator backups when built-in backup functionality is insufficient.

While we highly recommend using the built-in Full Backup functionality within Curator, there are times where
that isn't possible or when implementing your own full backup process.  This guide will cover the steps and
commands that Curator uses to take a full backup.  You may need to customize these steps for your own
purposes.

<Note>
  If you are taking this backup in order to move Curator onto new server hardware, see
  [Moving Curator to a New Server](/upgrading_migration/migration/moving_to_a_new_server) for the full sequence
  this step belongs to.
</Note>

There are 2 sets of data that will need to be included in a full backup:

1. Curator's Database
2. Curator's File System

## Database Dump

The way Curator backs up its database is by dumping the structure and data contained in that database to a
SQL file. This SQL file will include the actual SQL code needed to recreate the tables and insert all of the data.

The command Curator runs is:

`mysqldump -h $host -u $user -p --port=$port --databases $databaseName > $backupFilename`

Where:

* `$host` is the host name where the database lives.  This is almost always localhost or 127.0.0.1.
* `$user` is the database user.  Get this from your *\<web root>*/config/database.php configuration file.
* `$port` is the port the database runs on.  This is almost always 3306.  Get this from your *\<web root>*
  config/database.php configuration file if it's something other than 3306.
* `$databaseName` is the name of the database inside of MariaDB/MySQL that houses Curator's data.  Get this
  from your *\<web root>*/config/database.php configuration file.
* `$backupFilename` is the file to save the SQL dump into.  Curator names this file `$databaseName`\_`$currentTimestamp`.sql

You will be prompted for the password when running this command.  Get the password from your *\<web root>*
config/database.php configuration file.

## Filesystem Backup

To back up Curator's files, Curator just zips the entire web root directory (i.e. /var/www/html or
C:\InterWorks\Curator), excluding any other full backup files.  Curator stores its full backup files in the
*\<web root>*/storage/temp directory as `full_backup_$currentTimestamp.zip` by default, but this backup
location may be configured to be a different directory.

## Curator Compatible Backups

If you are trying to create a backup that's compatible with Curator's Full Backup functionality so that it
can be restored with the click of a button, here are the details that will be important:

1. The full backup zip archive must follow this naming convention, where the the middle part is replaced by
   an appropriate timestamp: `full_backup_YYYYMMDD_HHMMSS.zip`.
2. The full backup zip archive must consist of 2 files:
   1. The database dump with the name of the database as the prefix (e.g. `curator_`), a timestamp that
      matches the full backup timestamp, and a `.sql` file extension.
      The name should look something like: `curator_YYYYMMDD_HHMMSS.sql`.
   2. The backup of the file system as a zip archive that must follow this naming convention, where the
      middle part is replaced by the same timestamp as the full backup: `webroot_YYYYMMDD_HHMMSS.zip`.
3. In order to be restored by Curator, this file must be placed in *\<web root>*/storage/temp/.


# Importing and Exporting
Source: https://docs.curator.interworks.com/upgrading_migration/migration/importing_and_exporting

Manual backup and migration process for transferring Curator content between installations.

We provide a simple manual backup process that can help with migrating your Curator content from one
environment to another, or to the server as a backup so you don't lose all that hard work.

<Note>
  This page moves selected metadata between instances. To move an entire Curator installation onto new server
  hardware, use a full backup and restore instead — see
  [Moving Curator to a New Server](/upgrading_migration/migration/moving_to_a_new_server).
</Note>

## Migration Via File

This method to migrate data involves downloading a file from the source Curator and uploading it to the destination
Curator. These files can be used as backups or a simple way to pass data to the Curator support team for debugging
your specific content. The maximum file size for imports is 1.5GB. If your export file exceeds this limit, consider
breaking it into smaller pieces by exporting fewer items at a time.

***To export your Curator metadata:***

1. Login to the backend of your source Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to **Settings** > **Curator** > **Import/Export** section using the left-hand menu.
3. Check the necessary items you need to backup. Items are grouped into category cards (such as Settings,
   Users & Access, and Content & Theme). Each card has its own "Select all" link, and the "Select All" link at
   the top selects everything. The bar at the bottom of the page shows how many items are selected.
4. Click "Export" in the bar at the bottom. This will download a file you can keep as a backup or use to
   import your settings to another Curator instance.

***To import your Curator metadata:***

1. Login to the backend of your destination Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to **Settings** > **Curator** > **Import/Export** section using the left-hand menu.
3. Click on the "Import" tab at the top.
4. Click the "Upload" icon (upwards arrow) to locate the `.iwe` or `.iwgz` file you exported using the steps
   above, then click "Preview Import".
5. Curator analyzes the import in the background and shows a progress screen with the current phase and a
   progress bar. Large imports can take several minutes. Keep the page open; the review screen appears
   automatically when the analysis finishes. *Note: The Curator scheduler (cron), which is part of every standard
   installation, normally performs this processing. If the scheduler has not picked the job up (for example, on a
   development instance where it is not running), the page takes over and processes the import itself after about
   a minute, and a note appears asking you to keep the tab open until the import finishes. This fallback applies
   to both file-based and API-based imports.*
6. Review the import summary. Each content type shows how many items were found and how many conflict with
   existing content. Choose "Include" or "Skip" per type (or use the "Skip All" / "Include All" links), and
   resolve any conflicting items listed below the summary.
7. Click the "Import" button. Another progress screen tracks the import itself, and a results table showing
   succeeded, skipped, and failed items appears when it completes. If any links between items could not be
   restored, a yellow notice appears above the results listing them -- see
   [Links Between Items Missing After an Import](#links-between-items-missing-after-an-import) below.

## Migration Via API

This method to migrate data involves using Curator's REST API from the destination Curator to request data from the
source Curator. This option can be convenient because it requires fewer steps after the initial setup.

***Retrieve an API key:***

1. Login to the backend of your source Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to **Settings** > **Curator** > **API Keys** section using the left-hand menu.
3. Copy an API Key using the icon in the "ACTIONS" column. *Note: If the API Key has "Restrict Access" enabled, ensure
   the "export" endpoint in the "Portal Permissions" section is allowed.*

***To import your Curator metadata:***

1. Login to the backend of your destination Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to **Settings** > **Curator** > **Import/Export** section using the left-hand menu.
3. Click on the "Import" tab at the top.
4. Click the "Use API" radio button.
5. Enter the source Curator's URL and API Key. *Note: After completing one import from the source Curator this info
   will be stored. The next time you need to migrate data you can simply select that stored data instead of re-entering
   it.*
6. Check the data types you'd like migrated. Every item of the selected types will be retrieved, but you can select
   specific items in the next page.
7. Click "Preview Import" at the bottom of the screen.
8. Curator analyzes the import in the background and shows a progress screen. Keep the page open; the review
   screen appears automatically when the analysis finishes. The same scheduler note from the file-based import
   steps above applies here: if the scheduler has not picked the job up, the page processes the import itself
   while it stays open.
9. Review the import summary, choose "Include" or "Skip" per type, and resolve any conflicting items listed
   below the summary.
10. Click the "Import" button. A results table showing succeeded, skipped, and failed items appears when the
    import completes, along with a yellow notice if any links between items could not be restored -- see
    [Links Between Items Missing After an Import](#links-between-items-missing-after-an-import) below.

## Automatic Exports

Alongside the manual export above, Curator keeps a rolling set of automatic exports: scheduled `.iwe` snapshots
of your metadata that you can restore or download at any time. These are listed on the **Automatic Exports** tab
of the Import/Export page.

***To view, restore, or download an automatic export:***

1. Login to the backend of your Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to **Settings** > **Curator** > **Import/Export** using the left-hand menu, then open the
   **Automatic Exports** tab.
3. Each export is listed with the date it was taken and its file size. Use the "Restore Export" icon to restore
   Curator to that point in time, click the export name to download the file, or use the "Delete Export" icon to
   remove it.
4. Click "Take New Export" to generate a new automatic export immediately.

***To set the number of exports to retain:***

By default, Curator keeps automatic exports based on the free space available on your server. You can instead cap
retention to a fixed number of exports.

1. On the **Automatic Exports** tab, click the gear icon next to "Take New Export" to open the **Export Settings**
   popup.
2. Set **Number of exports to retain** to how many of the most recent exports you want to keep (1 through 10),
   then click "Save".
3. After each automatic export runs, Curator keeps only that many of the most recent exports and removes the
   older ones. Select **Use default (disk-based)** to return to keeping exports based on available disk space.

<Note>
  On Curator SaaS (InterWorks-hosted) instances, automatic exports are held under a compliance lock, so they are
  retained indefinitely and cannot be deleted through Curator. The **Export Settings** retention option is
  therefore not shown on SaaS deployments. See
  [Curator Backup](/upgrading_migration/backups/curator_backup) for more on SaaS backup retention.
</Note>

## Permissions

Each backend user in Curator can be assigned permissions for handling certain content. If your user doesn't have
permissions to make changes to the content included in an import it will be filtered out of the data. You can
request these permissions be added by your Curator administrator or have them process the import.

## Troubleshooting

If an import returns an error, no data, or unexpectedly missing items, work through the relevant section below.

### API Import Issues

If an API import returns an error or no data, work through the following checks in order:

1. **Verify the API key is still valid.** Login to the source Curator backend, navigate to
   **Settings** > **Curator** > **API Keys**, and confirm the key you're using is listed and has not been rotated or
   deleted.
2. **Check restricted-key export permissions.** If the API key has "Restrict Access" enabled, open it and confirm
   the "export" endpoint in the "Portal Permissions" section is allowed. Without this permission the source Curator
   will reject the request even though the key itself is valid.
3. **Confirm the source URL is reachable from the destination.** From the destination server (not your local
   machine), verify the source Curator URL resolves and responds. Firewalls, VPN-only networks, and self-signed
   certificates on the source can all block the request.
4. **Check destination backend user permissions.** The backend user running the import must have permission to
   create or update every content type included in the import. See the [Permissions](#permissions) section for details
   on how items without sufficient permissions are handled.

### File Size Limit

The maximum file size for imports is 1.5GB. If your export file exceeds this limit, break it into smaller pieces
by exporting fewer items at a time and importing each piece separately.

### Items Missing After a Successful Import

If the import completes without errors but some expected items are missing on the destination, this is usually
caused by permission filtering. Items the destination backend user does not have permission to create or
update are silently skipped rather than failing the import. Re-run the import as a high level administrator, or have your
Curator administrator grant the necessary permissions to your user. See the [Permissions](#permissions) section
above for more detail.

If the items themselves imported but the *links between them* are missing, see the next section instead.

### Links Between Items Missing After an Import

Items can be linked to one another -- keywords tagged on navigation links, dashboards, pages, and files;
navigation links assigned to user groups; notices attached to navigation links. When an import cannot work out
which destination item a link points at, it skips that link rather than saving a broken reference, and reports
it in a yellow notice above the results table.

The notice lists each skipped link and gives a total. When there are more skipped links than the notice lists,
the remainder are recorded in the log only -- your Curator administrator can find the full list under
**Settings** > **Logs** > **Event log** in the backend.

This normally means the item on the other end of the link was not part of the import and does not already exist
on the destination. Common causes:

* The item was set to "Skip" on the review screen while the item linking to it was included.
* The export did not include the item's content type. For example, exporting Navigation without also exporting
  Keywords leaves the keywords tagged on those navigation links with nothing to point at.
* The item was deleted on the destination after the export was taken.

To resolve it, export both content types together from the source and re-run the import, including both on the
review screen. The links are restored automatically once the items on both ends are present.


# Moving Curator to a New Server
Source: https://docs.curator.interworks.com/upgrading_migration/migration/moving_to_a_new_server

End-to-end process for moving an existing Curator installation to new server hardware.

When the server hosting Curator reaches end of life, or you are moving to newer hardware, you do not migrate Curator
in place. Instead you install Curator fresh on the new server, then restore a full backup taken from the old server
over the top of it. This page sequences that process end to end and links out to the detailed guide for each step.

<Note>
  This page applies to Curator On-Prem, where you host and manage the server yourself. Full backups are not available
  on Curator SaaS, because InterWorks hosts and manages those instances. If you are on Curator SaaS and need to move
  your instance, [contact support](https://interworks.com/help) rather than following this page.
</Note>

## Choosing Between a Full Backup and an Export

There are two ways to move Curator content to another server, and they are not interchangeable.

* **Full backup and restore** moves the entire database and web root, including content, users, settings,
  uploads, theme, and code. Use it when you are replacing a server and want the new instance to match the old one
  exactly.
* **[Import/Export](/upgrading_migration/migration/importing_and_exporting)** moves selected metadata only, such
  as content, navigation, and settings. Use it when you are seeding a separate environment, or moving content
  between two instances that both stay in service.

Moving to new server hardware is the first case, so the rest of this page covers the full backup and restore path.

## Before You Start

Gather the following from the old server. You will need them later in the process, and some become harder to
retrieve once the old server is decommissioned.

* The contents of `<web root>/config/database.php`, specifically the database host, port, database name, username,
  and password. The new server needs its own working values, and you will compare the two sets in Step 4.
* A copy of `<web root>/.env`. This file is not included in a full backup, and it holds the `APP_KEY` value that
  Curator uses to encrypt stored secrets. You will carry that key over to the new server in Step 3.
* Your Curator license key. The key is stored in Curator's database, so a full restore normally carries it across,
  but having it on hand avoids a support round trip if activation fails.
* Any server-level configuration that lives outside Curator's web root and is therefore not in the backup, such as
  SSL certificates, virtual host or site bindings, and firewall rules.

<Warning>
  Keep the old server running and untouched until you have confirmed the new server is working. Curator's full
  backups are stored on the same server as Curator by default, so decommissioning the old server too early can
  destroy the backup you are relying on.
</Warning>

## Step 1: Install Curator on the New Server

Perform a normal fresh install on the new server using the guide for its operating system:

* [Windows Installation](/setup/installation/windows_installation)
* [Linux Installation](/setup/installation/linux_installation)

Confirm you can reach the new instance in a browser and log in to its backend before continuing. Restoring over a
broken install makes it much harder to tell whether a later problem came from the restore or the install.

<Note>
  Curator no longer supports new installations on IIS. If your old server runs IIS, install on Apache on the new
  server using the [Windows Installation](/setup/installation/windows_installation) guide. See
  [IIS Installation](/setup/installation/iis_installation) for details.
</Note>

## Step 2: Take a Full Backup on the Old Server

On the **old** server, take a fresh full backup so the restore captures the most recent state.

<Warning>
  Stop write activity on the old server before taking this backup, and keep it read-only through the cutover in
  Step 6. That means no new content edits, no uploads, and no user or settings changes. Anything written to the old
  server after this backup exists only there, is not carried across by the restore, and is lost when the old server
  is decommissioned.
</Warning>

1. <BackendNavPath />
2. Click **Take New Backup**.
3. Watch the job to completion under **Settings** > **Curator** > **Queued Processes**.
4. Once it finishes, copy the resulting `full_backup_YYYYMMDD_HHMMSS.zip` file off the server. It is written to the
   directory shown in **Backup Location**, which is `<web root>/storage/temp` by default.

See [Curator Backup](/upgrading_migration/backups/curator_backup) for more detail on the backup interface. If the
built-in backup cannot run — for example the server is low on disk space or the job fails — build the archive by
hand using [Taking a Manual Full Backup](/upgrading_migration/backups/taking_a_manual_full_backup).

## Step 3: Carry Over the Encryption Key

Curator encrypts stored secrets, such as Tableau connection passwords, personal access token secrets, and Connected
App secrets, using the `APP_KEY` value in `<web root>/.env`. That file is not part of a full backup, and a fresh
install generates its own key. If you restore the old server's database under the new server's key, Curator cannot
decrypt those secrets, and every affected connection has to be re-entered by hand.

To keep the saved secrets working, put the old key in place before you restore:

1. On the old server, open `<web root>/.env` and copy the full value of the `APP_KEY` line.
2. On the new server, open `<web root>/.env` and replace the value of its `APP_KEY` line with the copied value.
   Change only that line. Leave the rest of the file, including any database connection values, as the new install
   set them.
3. Restart Curator so the new key takes effect. On Windows, run `stop.bat` and then `start.bat` from the Curator
   install directory. On Linux, restart Apache or PHP-FPM.
4. Confirm you can still log in to the new instance's backend.

<Note>
  If the old server's `.env` file is no longer available, you can still complete the move. Restore as normal, then
  re-enter the password or secret on each affected connection, starting with your Tableau, Power BI, or ThoughtSpot
  connection settings.
</Note>

## Step 4: Restore the Backup on the New Server

A full backup contains a database dump and a zip of the old server's web root. Restoring it overwrites the new
server's database and files with the old server's, which is what makes the new instance an exact copy.

### If the Database Connection Details Differ

The web root in the backup includes the old server's `config/database.php`, and the database dump is written for
the old server's database name. If the new server's database host, port, name, username, or password differ from
the old server's, restoring the archive unmodified can leave Curator pointing at the wrong database, or at one it
cannot reach. Curator checks for this before restoring and refuses to continue when the connection details in the
backup do not work, with an error telling you to fix the database connection first.

Curator can rewrite the connection details inside the archive for you:

1. Place the `full_backup_YYYYMMDD_HHMMSS.zip` file in the new server's **Backup Location**, which is
   `<web root>/storage/temp` by default.
2. <BackendNavPath />
3. Find the backup in the list and click the wrench icon in the **Actions** column, labeled **Fix database
   connection in this backup**.
4. Enter the **old** server's database host, database name, database user, and database password. These are the
   values you gathered from the old server's `config/database.php` in Before You Start. Curator already knows the
   new server's values and substitutes them in.
5. Click **Queue Fix** and confirm the prompt, then watch the job to completion under **Settings** > **Curator** >
   **Queued Processes**. The backup's status in the list returns to **Ready** when the fix is done.

The fix unpacks both layers of the archive, replaces the old values in the database dump and in
`config/database.php`, and repacks the backup under its original name, so it takes a while and needs a good deal of
free disk space on the new server.

If the fix job fails, or you prefer to edit the archive by hand, follow the **Handling Different Database
Connections** steps in
[Manual Restoration of Curator Backup](/upgrading_migration/backups/manual_restoration_of_curator_backup) instead.

If the connection details are identical on both servers, no fix is needed and you can restore the archive as it is.

### Running the Restore

1. Place the `full_backup_YYYYMMDD_HHMMSS.zip` file in the new server's **Backup Location**, which is
   `<web root>/storage/temp` by default, if it is not there already. Curator only lists backups it finds in that
   directory.
2. <BackendNavPath />
3. Find the backup in the list, identified by its timestamp, and click the **Restore Backup** icon, which is the
   counter-clockwise arrow in the **Actions** column.

If the restore fails for a reason you cannot resolve, restore the database and file system by hand using
[Manual Restoration of Curator Backup](/upgrading_migration/backups/manual_restoration_of_curator_backup).

### Fix File Permissions

Copying a web root between servers routinely leaves files owned by the wrong user, which shows up afterwards as
cache, upload, or job system errors rather than as an obvious restore failure. Correct ownership on the new server
using [Filesystem Permissions](/server_management/system_administration/filesystem_permissions).

## Step 5: Reactivate the License on the New Server

Curator's license key is stored in its database, so a full restore usually carries it over to the new server. Log in
to the new instance and check **Settings** > **Curator** > **System Upgrade** to confirm the key is present and
active.

If the key did not carry over or fails to activate, re-enter it by following
[Updating License Key](/site_administration/license_key/updating_license_key).

<Warning>
  A standard license key covers up to 3 instances, with only one of them in Production. The old server still counts
  against that limit after you stop using it, so a server move can push you over the cap and cause activation to
  fail on the new server. [Contact support](https://interworks.com/help) to deregister the retired instance once the
  new server is confirmed working.
</Warning>

## Step 6: Verify and Cut Over

Before pointing users at the new server, confirm the following on the new instance:

* The portal loads and your content, navigation, and users all appear as they did on the old server.
* Dashboards embed and render correctly. This confirms both that the restored connections to Tableau, Power BI, or
  ThoughtSpot still work from the new server's network location, and that the encryption key carried over in Step 3
  decrypts their saved credentials.
* Scheduled tasks are running. If backups, exports, or other scheduled jobs never appear, work through the cron
  troubleshooting guide for [Linux](/server_management/system_administration/linux_cron_troubleshooting) or
  [Windows](/server_management/system_administration/windows_cron_troubleshooting).
* A new full backup completes on the new server.

If your portal authenticates through SAML, whether the identity provider needs changing depends on how you cut
over. A DNS-only move, where the same public hostname now points at the new server and the SAML endpoints are
unchanged, needs no identity provider changes. If the hostname or a SAML endpoint changes, the identity provider
still points at the old values and must be updated as part of the cutover — follow
[SAML Cutover Process](/upgrading_migration/migration/saml_cutover) to sequence the DNS and SAML changes with
minimal downtime.

Once the new server is confirmed working and the retired instance has been deregistered, the old server can be
decommissioned.


# SAML Cutover Process
Source: https://docs.curator.interworks.com/upgrading_migration/migration/saml_cutover

A guide to cutting over a production SAML-authenticated portal to a new production portal with minimal downtime.

When migrating from one production Curator portal to another, the cutover involves two main changes: updating DNS to
route your friendly URL from the current production portal to the new one, and migrating the SAML authentication
connection. While DNS changes are straightforward, the SAML migration requires careful planning to minimize downtime and
ensure users can authenticate seamlessly after the switch.

During the preparation phase before cutover, the new portal will be accessible at a temporary direct URL (e.g.,
`https://new-server.example.com`). This temporary direct URL is only needed until cutover is complete. After cutover,
DNS will route your friendly URL (e.g., `https://curator.yourcompany.com`) to the new portal, and the temporary direct
URL will no longer be needed.

<Note>
  During this process it can be difficult to tell which portal you are viewing at a given URL, especially once DNS
  changes are in progress. To make this easier, consider temporarily changing the **Curator Site Name** on one of
  the portals so you can visually distinguish between them. This setting is found in the backend under
  **Settings** > **Curator** > **Themes** > select your theme > **Brand** tab. For example, you could rename the
  new portal to "Curator (New)" during the migration. Remember to revert the name after cutover is complete.
</Note>

This guide presents two options for handling the SAML cutover and provides detailed step-by-step plans for each.

## Preparing for Migration: Authenticating to the New Portal

Before you begin the cutover process, you need a way to authenticate to the new portal so you can import content,
configure settings, and compare the new portal side-by-side with the existing production portal. There are two
approaches for this.

### Approach A: Create a Second SAML Application (Recommended)

Create **two separate SAML applications** in your Identity Provider (IdP) — one for your current production portal
(you should already have this) and one for your new production portal (you will need to create this).

Each SAML application in your IdP will point to a different Curator URL:

* **Current production app**: Configured with your friendly URL (e.g., `https://curator.yourcompany.com`)
* **New production app**: Configured with the new portal's temporary direct URL (e.g., `https://new-server.example.com`)

With both applications in place, your team can authenticate to either portal independently. This allows you to:

* Import and migrate content to the new portal using Curator's
  [import/export functionality](/upgrading_migration/migration/importing_and_exporting)
* Verify that analytics integrations, user permissions, and embedded content work correctly on the new portal
* Compare the new portal's content and configuration against the current production portal before committing to the
  cutover

<Note>
  Depending on which cutover option you choose below, the new production SAML app is temporary. It is only needed
  during the preparation and testing phase. After cutover, the new portal will use the friendly URL and will be served
  by either the original SAML app (Option 2) or the new (but modified) SAML app (Option 1). The temporary app can
  then be removed from your IdP.
</Note>

For instructions on creating a SAML application in your IdP, refer to the provider-specific guides:

* [Okta](/setup/authentication/okta_saml)
* [Microsoft Entra ID / Azure AD](/setup/authentication/azure_ad_saml)
* [OneLogin](/setup/authentication/one_login_saml)

### Approach B: Use Curator Users on the New Portal Temporarily

If creating a second SAML application is not practical, you can temporarily set the new portal's authentication type to
**Curator Users** during the preparation phase. This allows testers to log in with locally-created usernames and
passwords instead of SAML.

To set this up, log in to the backend of the new portal and navigate to the authentication settings.

<BackendNavPath />

Set the **Authentication Type** to **Curator Users**, then create local user accounts for each person who needs to test
the new portal. For details, see the [Curator Users](/setup/authentication/curator_users) guide.

<Warning>
  The local usernames and passwords created during this phase are only for the preparation period. They will be
  abandoned once you switch the authentication type back to SAML — either to stage the changes for Option 2, or
  during the cutover itself for Option 1. Make sure testers are aware that these credentials are temporary.
</Warning>

<Note>
  You can also temporarily use this approach while waiting for the second SAML application to be set up in your IdP
  and then switch to Approach A once it's ready.
</Note>

## Migration Options Overview

### Option 1: Swap SAML IdP Configuration

This approach involves modifying the SAML Identity Provider (IdP) to swap the URLs configured in both your current and
new production SAML applications at the time of cutover.

**Advantages:**

* No changes are usually required in Curator during cutover (this depends on the SAML IdP)
* No changes required on individual user machines
* Works in all networking environments, including those using Curator's force domain setting

**Disadvantages:**

* The IdP configuration changes are specific to your SAML provider (Okta, Microsoft Entra ID / Azure AD, OneLogin, etc.)
  and must be coordinated with your SAML administrators
* More moving parts during the cutover window since both DNS and IdP changes happen simultaneously
* Cannot be fully staged or tested in advance

See the [detailed cutover plan for Option 1](#detailed-cutover-plan-option-1-idp-configuration-swap) below.

### Option 2: Copy SAML Settings with Host File Override (recommended)

This approach involves copying the SAML configuration from your current production portal to your new production portal
before cutover, then using local host file entries to test the new portal in advance.

**Advantages:**

* Fewer moving parts during the actual cutover since SAML is already configured and tested
* Can be staged and validated in advance of the cutover window
* No changes required in your SAML IdP

**Disadvantages:**

* Requires temporary administrative changes on tester machines (editing the hosts file)
* Testers cannot access both portals simultaneously while the host file override is active
* Will not work in environments using Curator's force domain setting or other networking configurations that bypass
  local DNS resolution (e.g., split-horizon DNS, internal DNS overrides, or proxy servers that resolve DNS independently)

See the [detailed cutover plan for Option 2](#detailed-cutover-plan-option-2-saml-settings-copy-with-host-file-override)
below.

## Detailed Cutover Plan: Option 1 (IdP Configuration Swap)

This plan involves coordinating DNS and SAML IdP changes during a single cutover window. Because the IdP changes cannot
be tested in advance against the new portal's URL, plan for a brief period of downtime while changes propagate.

### Prerequisites

* Your new production Curator portal is fully configured and tested (content, integrations, users, etc.) with the
  exception of SAML authentication
* You have access to your DNS provider to update the friendly URL's DNS record
* Your SAML IdP administrators are available and prepared to make changes during the cutover window
* You have identified the SAML IdP application entries for both your current and new production portals

### Pre-Cutover

1. Confirm your new portal is accessible at its temporary direct URL (e.g., `https://new-server.example.com`) and all
   content, integrations, and user configurations are working as expected using a non-SAML authentication method (such as
   pass-through or Curator Users).
2. Document the current SAML settings from your existing production portal. <BackendNavPath /> Record the values for **Entity ID**, **SignOn URL**, **IdP ID**, **SignOut URL**, and the **Certificate**.
3. Coordinate a cutover window with your SAML IdP administrators and any stakeholders who need to be informed of the
   brief downtime.

### During Cutover

<Steps>
  <Step title="Update DNS">
    Update the DNS record for your friendly URL (e.g., `curator.yourcompany.com`) to point to the IP address of
    your new production portal server. Note that DNS propagation may take time depending on TTL settings. Consider
    lowering the TTL value in advance of the cutover to speed up propagation.
  </Step>

  <Step title="Update the SAML IdP application for the new portal">
    Work with your SAML IdP administrators to update the application entry that will be used for the new production
    portal. The URLs in the IdP application (such as the Assertion Consumer Service URL and the Entity ID/Audience
    URI) need to reference your friendly URL. The specific steps depend on your IdP:

    * **Okta**: Update the **Single sign-on URL** and **Audience URI (SP Entity ID)** in the Okta application
      settings.
    * **Microsoft Entra ID (Azure AD)**: Update the **Reply URL** and **Identifier (Entity ID)** in the Enterprise
      Application's SAML configuration.
    * **OneLogin**: Update the **ACS (Consumer) URL** and **Audience** in the OneLogin application configuration.

    <Note>
      The exact steps vary by IdP. Consult your SAML IdP's documentation or work with your SAML administrators
      for provider-specific instructions.
    </Note>
  </Step>

  <Step title="Update the SAML IdP application for the old portal (if keeping it active)">
    If you intend to keep the old portal running (e.g., as a fallback), have your SAML IdP administrators update
    its application entry to reference the old portal's new direct URL instead of the friendly URL. If you are
    decommissioning the old portal, you can skip this step and remove its IdP application entry entirely.
  </Step>

  <Step title="Configure SAML on the new portal">
    If needed, you may be required to perform a fresh export and import of the SAML metadata from your SAML IdP into
    Curator if there were changes to certificates or other crucial details that must be reflected within Curator
    itself.

    <BackendNavPath />

    Set the **Authentication Type** to **SAML** and import or enter the SAML metadata provided by your IdP
    administrators for the updated application. Ensure the **Entity ID** matches your friendly URL.
  </Step>

  <Step title="Verify the cutover">
    Once DNS has propagated, open a new browser session (or use an incognito/private window) and navigate to your
    friendly URL. Confirm that:

    * The page loads and shows the new portal
    * Clicking "Log In" redirects to your SAML IdP
    * After authenticating, you are redirected back to the new portal and logged in successfully
    * Embedded analytics content loads correctly

    <Warning>
      If DNS has not yet propagated to your machine, you may still reach the old portal. Use tools like `nslookup`
      or `dig` to verify that the DNS record has updated before testing.
    </Warning>
  </Step>
</Steps>

### Post-Cutover

* Monitor authentication logs on the new portal for any errors. You can view these in the backend under
  **Settings** > **Event Log** or in the [system log files](/site_administration/logging/file_based_logs).
* Communicate the completion of the cutover to your users and stakeholders.
* Decommission or repurpose the old portal once you are confident the migration is successful.

## Detailed Cutover Plan: Option 2 (SAML Settings Copy with Host File Override)

This plan allows you to configure and test SAML on the new portal before the cutover window by reusing the existing
SAML settings and tricking your local machine into resolving the friendly URL to the new portal's IP address.

### Prerequisites

* Your new production Curator portal is fully configured and tested (content, integrations, users, etc.) with the
  exception of SAML authentication
* You have access to your DNS provider to update the friendly URL's DNS record
* You have administrative access to your local machine to edit the hosts file
* Your environment does not use Curator's force domain setting, split-horizon DNS, or a proxy server that resolves DNS
  independently of the local machine

### Pre-Cutover: Configure SAML on the New Portal

<Steps>
  <Step title="Export SAML settings from the current production portal">
    Log in to the backend of your current production Curator portal.

    <BackendNavPath />

    Record or export all SAML configuration values:

    * **Entity ID**
    * **SignOn URL**
    * **IdP ID**
    * **SignOut URL**
    * **Certificate**

    If your portal uses signed SAML requests, also expand the **SAML Advanced** section and record the **Service
    Provider Certificate** and **Service Provider Private Key** values.
  </Step>

  <Step title="Apply SAML settings to the new portal">
    Log in to the backend of your new production Curator portal using its temporary direct URL (e.g.,
    `https://new-server.example.com/backend`).

    <BackendNavPath />

    Set the **Authentication Type** to **SAML** and enter all of the values recorded from the current portal.
    If you exported a metadata XML file, you can use the **Import SAML Metadata** button instead. Ensure all
    fields match exactly.

    If your portal uses signed SAML requests, expand the **SAML Advanced** section and paste the **Service
    Provider Certificate** and **Service Provider Private Key** values as well.

    Save the settings.
  </Step>

  <Step title="Add a host file override on your testing machine">
    To test SAML authentication against the new portal before updating DNS, add an entry to your local hosts file
    that maps your friendly URL to the new portal's IP address.

    <Warning>
      While the host file override is in place, your machine will route all traffic for the friendly URL to the
      new portal. You will not be able to access the current production portal using the friendly URL from this
      machine.
    </Warning>

    Determine the IP address of your new production portal server.

    <Warning>
      If your new portal is hosted on **Curator SaaS**, the IP address is dynamic and may change at any time
      without notice. This means your host file entry could stop working unexpectedly. If this happens, resolve
      the current IP address again and update the hosts file entry. Because of this limitation, keep the host
      file override in place only for the duration of your testing and remove it promptly afterward.
    </Warning>

    Edit the hosts file on your machine:

    * **Windows**: Open Notepad as Administrator and edit `C:\Windows\System32\drivers\etc\hosts`
    * **macOS / Linux**: Edit `/etc/hosts` with sudo (e.g., `sudo nano /etc/hosts`)

    Add a line at the end of the file:

    ```
    <NEW_PORTAL_IP>    curator.yourcompany.com
    ```

    Replace `<NEW_PORTAL_IP>` with the actual IP address and `curator.yourcompany.com` with your friendly URL.

    Save the file. On macOS, you may need to flush your DNS cache afterward:

    ```bash theme={null}
    sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
    ```
  </Step>

  <Step title="Verify the host file override is working">
    Before testing SAML, confirm that the host file override is routing your friendly URL to the new portal.
    Open a new browser session (or use an incognito/private window) and navigate to the backend of your friendly
    URL (e.g., `https://curator.yourcompany.com/backend`). Log in and check the **Curator Site Name** displayed
    at the top of the page to confirm you are viewing the new portal rather than the current production portal.

    <Note>
      This is why temporarily renaming the new portal's site name (as suggested at the top of this guide) is
      helpful — it makes it immediately obvious which portal you are connected to.
    </Note>
  </Step>

  <Step title="Test SAML authentication against the new portal">
    Open a new browser session (or use an incognito/private window) and navigate to your friendly URL. Because of
    the host file override, your machine will connect to the new portal.

    Confirm that:

    * The page loads and shows the new portal's content
    * Clicking "Log In" redirects to your SAML IdP
    * After authenticating with the IdP, you are redirected back and logged in successfully
    * Embedded analytics content loads correctly

    <Note>
      Since the SAML IdP is configured with your friendly URL, the authentication flow will work normally because
      your browser is sending requests to the friendly URL, which resolves to the new portal via the host file
      override.
    </Note>

    If authentication fails, verify that:

    * The SAML settings on the new portal match the current portal exactly
    * The **Entity ID** on the new portal matches what is configured in your SAML IdP
    * The SSL certificate on the new portal is valid for the friendly URL domain
  </Step>

  <Step title="Remove the host file override">
    After successful testing, remove or comment out the host file entry you added in Step 3. This restores normal
    DNS resolution so your machine can access the current production portal again.
  </Step>
</Steps>

### During Cutover

Once you have validated that SAML works correctly on the new portal, the actual cutover is straightforward since
the only change needed is updating DNS.

<Steps>
  <Step title="Update DNS">
    Update the DNS record for your friendly URL (e.g., `curator.yourcompany.com`) to point to the IP address of
    your new production portal server. As with Option 1, consider lowering the TTL value in advance to speed up
    propagation.
  </Step>

  <Step title="Verify the cutover">
    Once DNS has propagated, open a new browser session and navigate to your friendly URL. Confirm that you reach
    the new portal and that SAML authentication works as expected.

    <Warning>
      Ensure you have removed any host file overrides from your testing machine before verifying, so that you are
      testing actual DNS resolution.
    </Warning>
  </Step>
</Steps>

### Post-Cutover

* Monitor authentication logs on the new portal for any errors. You can view these in the backend under
  **Settings** > **Event Log** or in the [system log files](/site_administration/logging/file_based_logs).
* Communicate the completion of the cutover to your users and stakeholders.
* Decommission or repurpose the old portal once you are confident the migration is successful.


# Dependency Updates
Source: https://docs.curator.interworks.com/upgrading_migration/upgrading/dependency_updates

Instructions for updating PHP, Apache, or MariaDB dependencies on your Curator webserver.

Curator's upstream dependencies (PHP, Apache, and MariaDB) require periodic updates to maintain security, performance,
and compatibility with the latest Curator features.

*Note: Before upgrading any dependencies, it is a good idea to ensure that you have a recent Curator backup available.*

## PHP Dependencies by Curator Version

| Curator Version | Minimum PHP Version | Maximum PHP Version |
| --------------- | ------------------- | ------------------- |
| 2023.03.01      | 8.0                 | 8.0                 |
| 2024.10.04      | 8.0                 | 8.1                 |
| 2025.07-03      | 8.0                 | 8.3                 |
| 2025.09-03      | 8.1                 | 8.3                 |
| 2026.04-01      | 8.3                 | 8.3                 |

### Important Notes

* Always ensure your PHP environment meets or exceeds the minimum version requirement for your Curator installation.
* Installing a PHP version above the listed maximum is unsupported and causes runtime errors. Stay within the
  minimum/maximum range shown for your Curator release.
* Upgrading Curator may require upgrading your PHP version. The System Upgrade page will automatically warn you
  when a release requires a newer PHP version than your server is currently running. See
  [System Upgrade — PHP Version Compatibility](/upgrading_migration/upgrading/system_upgrade#php-version-compatibility)
  for details on how these warnings appear.
* Check your current PHP version with `php --version`.

### Required PHP Extensions

Running a supported PHP version is not enough on its own — Curator also requires the following PHP extensions to be
enabled in that version:

| Extension            | Used for                                                                   |
| -------------------- | -------------------------------------------------------------------------- |
| `zip` (`ZipArchive`) | Backups, content import and export, and upgrade packages                   |
| `gd`                 | Image processing and thumbnail generation                                  |
| `fileinfo`           | Detecting the type of uploaded files                                       |
| `zlib`               | Compression                                                                |
| `curl`               | Outbound requests to analytics platforms, licensing, and upgrade downloads |
| `openssl`            | Encryption and secure connections                                          |

Curator checks for these extensions and, on self-hosted installations, raises a *Curator is missing one or more
dependencies* warning that links back to this page when any of them are unavailable.

Upgrading PHP with the [Curator Dependency Update Utility](#windows) on Windows, or with the
[`php_upgrade_util.sh` script](#linux) on Linux, enables the required extensions for you. Installing or upgrading PHP
manually does **not** — for example, downloading a PHP release yourself and pointing IIS or Apache at it. In that
case you must enable each extension in the new PHP version's `php.ini`.

To list the extensions the PHP command line currently loads:

```bash theme={null}
php -m
```

To check for a single extension, filter that list with `php -m | findstr zip` on Windows, or `php -m | grep zip` on
Linux.

<Note>
  If `php artisan` commands fail immediately after a manual PHP upgrade with an error such as
  `Class "ZipArchive" not found`, the `zip` extension is not enabled in the PHP version now in use. Add
  `extension=zip` to the `php.ini` file that `php --ini` reports as loaded, then restart your web server and any
  PHP FPM processes. Reverting to the previous PHP version also clears the error, because the old installation still
  has the extension enabled.
</Note>

## Database Dependencies by Curator Version

Starting with **2026.06-01**, Curator requires a newer database engine. Older MySQL and MariaDB versions are no
longer compatible with the underlying framework, so the System Upgrade process will refuse to install a release that
requires a database version newer than the one your server is running.

| Curator Version | Minimum MySQL Version | Minimum MariaDB Version |
| --------------- | --------------------- | ----------------------- |
| 2026.06-01      | 8.0                   | 10.5                    |

### Database Notes

* Always ensure your database engine meets or exceeds the minimum version requirement for your Curator installation.
* Upgrading Curator may require upgrading your database. The System Upgrade page will automatically block a release
  when it requires a newer database version than your server is currently running. See
  [System Upgrade — Database Version Compatibility](/upgrading_migration/upgrading/system_upgrade#database-version-compatibility)
  for details on how this appears.
* Check your current database version by running `SELECT VERSION();` against your Curator database, or
  `mysql --version` from the command line.
* See the [Optional MariaDB Upgrade](#optional-mariadb-upgrade) and [Manual MariaDB Updates](#manual-mariadb-updates)
  sections below for instructions on upgrading MariaDB.

## Windows

First and foremost: ensure all relevant Windows Updates have been applied to your server.

Next, update Curator dependencies.

Curator bundles PHP, Apache, and VC Redistributable upgrades (plus an optional MariaDB upgrade) into a simple
utility package to make updating them as easy as possible.

To update Curator's dependencies, simply download our **[Curator Dependency Update Utility](https://portals.interworks.com/Curator_PHP_Upgrade_Util.exe)**.

Once downloaded, simply double-click the utility to run updates.
The Microsoft Visual C++ Redistributables, PHP, and Apache will be upgraded automatically by this utility.
During the upgrade, the utility pauses Curator's scheduled jobs and stops any running PHP processes so files are
not locked mid-upgrade, then resumes everything once the upgrade finishes.

**Note: Internet access is required for this process. Systems without internet access will need to upgrade manually.**

### Optional MariaDB Upgrade

The utility can also upgrade Curator's bundled MariaDB database. Because the database is stateful, this step is
**off by default**: the utility asks whether you want to run it, and the prompt only appears when a Curator MariaDB
installation (`libs\MariaDB`) and the *CuratorDB* service are both present on the server.

If you opt in:

* You will be prompted for your database root password, which is validated against the running server before
  anything is changed. The password is saved in the *info.txt* file in your installation directory
  (typically `C:\InterWorks\Curator\info.txt`) under *Database Root Password*.
* The utility takes a full backup of the `libs\MariaDB` folder as a rollback point. A disk-space check runs first
  to confirm there is enough room for the backup.
* Only the MariaDB program files are replaced. Your databases (the `data` folder) and configuration (`my.ini`)
  are never touched.
* If the upgrade crosses major MariaDB versions, the utility warns you and asks for confirmation before proceeding.
* After the new version starts, the utility runs `mysql_upgrade` and verifies the result.
* If the new version fails to start or verification fails, the previous MariaDB installation is automatically
  restored from the backup.

After a successful upgrade, the backup folder (for example, `libs\MariaDB.old`) is kept on disk. Once you have
confirmed Curator works correctly, you can delete it to reclaim disk space.

*Note:* The database briefly stops during this step, and upgrading MariaDB is not usually required for a Curator
upgrade. Only opt in when a release requires a newer database version (see
[Database Dependencies by Curator Version](#database-dependencies-by-curator-version)) or you have another reason
to upgrade. Always have your own recent backup before upgrading the database.

### Manual Dependency Updates

If your server has restrictions that prevent the utility from downloading files automatically, you can manually download
the required files and run the upgrade utility locally.

To manually upgrade dependencies:

1. Download the **[Curator Dependency Update Utility](https://portals.interworks.com/Curator_PHP_Upgrade_Util.exe)** on
   a system with internet access.

2. Download the following files to the same directory as the utility.
   <Warning>File names must match exactly as shown below for the utility to recognize them.</Warning>
   * **vc\_redist.exe** - VC Redistributables: [https://api.curator.interworks.com/file/vc\_redist](https://api.curator.interworks.com/file/vc_redist)
   * **php.zip** - PHP package: [https://api.curator.interworks.com/file/php\_apache](https://api.curator.interworks.com/file/php_apache)
   * **apache.zip** - Apache updates: [https://api.curator.interworks.com/file/apache](https://api.curator.interworks.com/file/apache)
   * **mariadb.zip** - MariaDB package (only needed if you opt into the
     [Optional MariaDB Upgrade](#optional-mariadb-upgrade)): [https://api.curator.interworks.com/file/mariadb](https://api.curator.interworks.com/file/mariadb)
     <Note>These links are API-served download endpoints. The URLs do not include file extensions — each link
     downloads a file with the name shown in bold above (e.g., `vc_redist.exe`, `php.zip`, `apache.zip`).</Note>

3. Transfer all files (the utility and the downloaded files) to your Curator server.

4. Ensure the utility and all downloaded files are in the same directory, such as having them all on your Desktop,
   then double-click the utility to run the upgrade.

*Note: The utility will detect the locally available files and use them instead of attempting to download them. If the
file names do not match exactly, the utility will not recognize them and will attempt to download them from the internet.*

### Manual MariaDB Updates

The [Optional MariaDB Upgrade](#optional-mariadb-upgrade) step in the Dependency Update Utility is the recommended
way to upgrade MariaDB on Windows, since it backs up the installation and automatically rolls back if the upgrade
fails. Use the manual steps below only if you cannot run the utility.

To manually upgrade MariaDB, download the [MariaDB package](https://api.curator.interworks.com/file/mariadb).

*Note:* To upgrade MariaDB, you will need your database root password.
If you do not know this password, check your installation directory for an *info.txt* file
(typically `C:\InterWorks\Curator\info.txt`) and look for the *Database Root Password* entry.

### MariaDB on Windows

To upgrade MariaDB on Windows, first stop the *CuratorDB* Service, using Window's *Services* app.

You can open Window's *Services* by simply searching for *Services* using the Window's start bar.

To stop the *CuratorDB* process, find it in the *Services* list, then right click on it and click *Stop*.

Next, find Curator's MariaDB installation folder.

*Note:* This can usually be found in C:\InterWorks\Curator\libs\MariaDB.

Rename to MariaDB's *bin* folder to *bin.bkp*.

After a successful upgrade, you can delete this backup directory.

Then, download the latest [MariaDB](https://api.curator.interworks.com/file/mariadb) package.
Unzip this package over top of Curator's MariaDB installation.

Finally, open PowerShell in Administrative mode and run MariaDB's upgrade utility.
To open Powershell in Administrative mode, use the search widget in Window's start bar.
Search for Powershell, then Right-Click on Powershell and click "Run As Administrator".

Navigate to MariaDB's bin directory and run the upgrade utility.

```bash theme={null}
cd C:\InterWorks\Curator\libs\MariaDB\bin
mysql_upgrade_service.exe --service=CuratorDB
```

Note: if you have trouble with the MariaDB's *service* upgrade utility, you can also use the non-service version.
To do this, first restart MariaDB in Window's *Services* app, and then run this command:

```bash theme={null}
mysql_upgrade.exe -u root -p --force
```

## Linux

Linux's upstream repositories handle dependency updates, so first ensure you are running a recent version of your Linux distribution.

If you're not sure, you can take a look at our recommended distributions on the [Linux Installation page](/setup/installation/linux_installation).

To update Curator's Linux dependencies, SSH into your web server and cd into the webroot directory
(typically /var/www/html) and ensure you're using a user that has full sudo access, and run the command below.

This command will upgrade PHP, MariaDB, Apache, and any other operating system dependencies required by Curator:

```bash theme={null}
curl -s -o php_upgrade_util.sh https://api.curator.interworks.com/scripts/php_upgrade_util.sh && chmod +x ./php_upgrade_util.sh && ./php_upgrade_util.sh
```


# Disable Curator Upgrades
Source: https://docs.curator.interworks.com/upgrading_migration/upgrading/disable_curator_upgrades

Learn how to disable the upgrade functionality in Curator for servers without external network access.

Curator can be set up on a server that does not have access to outside networks. When you have this setup it
is advised to Disable Upgrades. This will prevent any issues if someone accidentally clicks the upgrade
button when Curator can't reach an out of network connection.

***To enable Disable Curator Upgrades:***

1. Login to the backend of your Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section using the left-hand menu..
3. Click on the "Features" tab at the top of the main page content.
4. Click to switch on the "Disable Curator Upgrades" setting under the "Functionality" section and click the "Save" button.


# Offline Upgrades (Air Gapped)
Source: https://docs.curator.interworks.com/upgrading_migration/upgrading/offline_upgrades_air_gapped

Guide for updating Curator on servers without internet access using manual update files.

If you've installed Curator on a server that is cut off from internet access, we provide a Manual Update
option. This requires enabling the Disable Curator Upgrades setting to be enabled so you can perform a Manual
Upgrade.

***To enable Allow Manual Curator Upgrades:***

1. Login to the backend of your Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section using the left-hand menu..
3. Click on the "Features" tab at the top of the main page content.
4. If "Disable Curator Upgrades" is set to OFF, click the switch to turn this feature ON
5. Click to switch the "Allow Manual Curator Upgrades" setting ON under the "Functionality" section and click
   the "Save" button.

***Click [Here](/upgrading_migration/upgrading/system_upgrade) for
Documentation on How to Manually Upgrade Curator***


# System Upgrade
Source: https://docs.curator.interworks.com/upgrading_migration/upgrading/system_upgrade

Learn about the various methods to update your Curator installation to the latest version.

There are several easy ways to update Curator.

To see if Curator needs an update, check the status of your Curator instance on the homepage of the backend,
or on the System Upgrade page.

The "Current Version" will show what software version Curator is currently running and the "Latest Version"
will show the latest release available.

**Attention: We recommend taking a Curator Backup before an upgrade. See the [Curator Backup documentation](/upgrading_migration/backups/curator_backup) for details.**

## Testing Upgrades in a Non-Production Environment

Before upgrading a production instance, we strongly recommend validating the upgrade against a separate dev or
staging instance that mirrors production. This catches version-specific issues against your actual data and
configuration before they affect end users. A standard Curator license covers up to three instances, so a
dedicated non-production instance is available at no additional cost in most cases.

The recommended workflow is:

1. **Export production data.** From the production instance, navigate to **Settings** > **Curator** >
   **Import/Export** and run a full export. Download the resulting archive.
2. **Stand up a dev instance at the same version as production.** Install a fresh Curator instance running the
   exact same version as production, then use the **Import/Export** tool on the dev instance to import the
   archive from step 1. The dev instance should now closely match production.
3. **Upgrade and validate the dev instance.** Perform the upgrade on the dev instance using whichever method
   you plan to use in production (One-click, Manual, or API). Once the upgrade completes, exercise the
   integrations and pages most critical to your users — Tableau, Power BI, or ThoughtSpot dashboards, SSO
   sign-in, scheduled syncs, and any custom themes or pages. Confirm everything renders and behaves as
   expected.
4. **Back up and upgrade production.** Only after the dev upgrade is validated, take a full
   [Curator Backup](/upgrading_migration/backups/curator_backup) of production and then run the same upgrade
   against production.

If the dev upgrade surfaces an issue, you can iterate on the dev instance without disrupting end users, and
report findings to InterWorks Support before touching production.

## Upgrading Curator

***One-click Upgrade:***

1. Login to the backend of your Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to the **Settings** > **Curator** > **System Upgrade** section using the left-hand menu.
3. Click the "Start One-click Upgrade" button.

***Manual Upgrade:***

1. Login to the backend of your Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to the **Settings** > **Curator** > **System Upgrade** section using the left-hand menu.
3. Click the "Manual Upgrade" button to display the Manual Upgrade links in the release notes section at the
   bottom of the page.
4. Click the link of the version you wish to upgrade to, this will download a .zip file containing the upgrade contents.
5. Upload the .zip file you just downloaded to the "Upgrade Zip Archive" section and click the "Submit" button.

***Curator API:***

1. Login to the backend of your Curator instance (e.g. `https://curator.example.com/backend`).
2. Navigate to the **Settings** > **Curator** > **API Keys** section using the left-hand menu.
3. Select an existing key or create a new key
4. If creating a new key, save the key.
5. From the REST API dropdowns, select 'Portal' in the left dropdown and 'Upgrade' in the right dropdown.
6. Click the link that was generated below the drop-downs.
7. This will open a new tab, when upgrade is successful a small success text display will populate.

## Troubleshooting

***Having Issues With the Upgrade?*** Try our [Upgrade Troubleshooting Documentation](/upgrading_migration/upgrading/troubleshooting_upgrades).

## PHP Version Compatibility

The System Upgrade page automatically checks your server's PHP version against each release's minimum
PHP requirement. If your server's PHP version is too old for a given release:

* The **Upgrade** button for that release will be disabled and shown in red as **"PHP X.X+ Required"**.
* An exclamation icon will appear next to the version number.
* In the **Manual Upgrade** download column, a warning note will appear: *"Requires PHP X.X+ — upgrade PHP before installing"*.
* If you attempt a one-click upgrade to an incompatible release, the confirmation dialog will block the
  upgrade and direct you to update PHP first.

To resolve this, upgrade your server's PHP version before upgrading Curator. See our
[Dependency Updates](/upgrading_migration/upgrading/dependency_updates) page for platform-specific instructions.

## Database Version Compatibility

Starting with **2026.06-01**, Curator also checks your server's MySQL or MariaDB version against each release's
minimum database requirement. Older database versions are no longer compatible with the underlying framework. If
your server's database version is too old for a given release, the upgrade will be blocked and you will see an error
similar to:

> ERROR: Your Curator server's MariaDB version (10.3.39) is too old. You need MariaDB 10.5 or newer before upgrading
> Curator. Reach out to Curator support if you need help with this.

The minimum supported versions are **MySQL 8.0** and **MariaDB 10.5**. To resolve this, upgrade your database engine
before upgrading Curator. See the
[Database Dependencies by Curator Version](/upgrading_migration/upgrading/dependency_updates#database-dependencies-by-curator-version)
section of our Dependency Updates page for the version table and platform-specific upgrade instructions.

## Known Issues

The System Upgrade page also shows the known issues InterWorks has published for each release, so you can see what
affects a release before you upgrade to it and what affects the release you are running today. When a release has
known issues:

* An **"N known issues"** badge appears next to the version number in that release's row.
* A **"Known issues (N)"** heading appears under the release notes. The list is collapsed by default; click the
  heading to expand it.
* Each entry is a bullet that starts with an impact badge (**Small**, **Medium**, or **Large**), followed by a short
  note describing the behavior. An entry without a note shows the issue title instead.
* A smaller line under the note lists the affected areas of Curator. When known, it also shows **"Since X"** with the
  release where the issue first appeared. When a later release fixes the issue, it shows **"Fixed in X"** with that
  release version.

When the release you are running has known issues, a box near the top of the page also lists them, under the heading
**"Your version X has N known issues"**. Each entry uses the same layout, and **"Upgrade to X to fix"** names the
release that fixes the issue. On a portal hosted by InterWorks, the entry shows **"Fixed in X"** instead, because
InterWorks runs the upgrade. The box does not appear when the running release has no known issues or when the page
cannot load the release list.

This list is curated by InterWorks and only reviewed entries appear. A release with no badge means no known issues
have been recorded for it yet, not that the release is free of bugs. If you run into a problem that is not listed,
reach out to Curator support.

## Multi-version Upgrades (4+ versions)

We recommend upgrading no more than 3 versions at a time.

If you plan to make an upgrade to a Curator instance that is more than 4 versions out-of-date, use the
version-specific upgrades on the upgrade page, instead of the "One-click upgrade".

## Common Upgrade Gotchas

When planning an upgrade — especially when jumping several versions — keep the following in mind. Most of
these are covered in more detail elsewhere in the docs; this list is a quick pre-upgrade checklist so you know
what to watch for.

* **PHP version requirement** — Each release declares a minimum PHP version. The System Upgrade page disables
  the upgrade button (showing **"PHP X.X+ Required"** in red) and blocks one-click upgrades if your server's
  PHP is too old. Upgrade PHP first. See the [PHP Version Compatibility](#php-version-compatibility) section
  above and the [Dependency Updates](/upgrading_migration/upgrading/dependency_updates) page.
* **Database version requirement** — Starting with **2026.06-01**, the upgrade is also blocked if your MySQL
  or MariaDB version is too old (minimums are **MySQL 8.0** and **MariaDB 10.5**). Upgrade your database engine
  first. See the [Database Version Compatibility](#database-version-compatibility) section above.
* **Upgrading too many versions at once** — Skipping more than 3 versions in a single step is not recommended.
  For instances more than 4 versions out-of-date, use the version-specific Manual Upgrade download links and
  step through intermediate versions in batches of three or fewer. See
  [Multi-version Upgrades](#multi-version-upgrades-4-versions) above.
* **Database migrations not applied** — If the upgrade completes but new features appear missing or the system
  behaves unexpectedly, the database migrations may not have finished. You can safely re-run them multiple
  times; follow the steps in
  [Updating the Curator Database (Running Migrations)](/upgrading_migration/upgrading/troubleshooting_upgrades#updating-the-curator-database-running-migrations).
* **Stale cache after upgrade** — Unexpected behavior immediately after an upgrade is often a stale cache. Ask
  end users to hard-refresh their browser (`Ctrl+Shift+R` / `Cmd+Shift+R`). To flush Curator's server-side
  cache, use the **Clear Cache** button in the backend, or append `?cache=clear` to any Curator page URL.
* **Authentication and session changes** — Some releases adjust session handling or SSO sign-in. If users are
  unexpectedly signed out or cannot authenticate after an upgrade, review the release notes for any
  intermediate versions you skipped and consult the
  [Upgrade Troubleshooting](/upgrading_migration/upgrading/troubleshooting_upgrades) guide.
* **Always upgrade non-production first** — Validate the upgrade against a dev or staging instance before
  touching production. See
  [Testing Upgrades in a Non-Production Environment](#testing-upgrades-in-a-non-production-environment) above.


# Troubleshooting Upgrades
Source: https://docs.curator.interworks.com/upgrading_migration/upgrading/troubleshooting_upgrades

Common upgrade issues and solutions to help resolve problems during the Curator update process.

Occasionally, you may run into issues during the upgrade process. We've provided some common scenarios and
how to quickly resolve them below.

**NOTE:** While running updates, it is always a good idea to have someone on standby during your upgrade who
has access to the server that Curator is running on, as most of these debugging solutions require
server-level access.

## Re-run the Upgrade With an Alternate Method

Curator can be upgraded in several different ways, so if you run into an issue upgrading in a specific way,
try using an alternative method to upgrade.

For example, there may be an issue with running the "one click" upgrade on your system.

Try upgrading via the Curator API, or using the Manual Upgrade method.

Both of these upgrade methods are detailed in our [System Upgrade Guide](/upgrading_migration/upgrading/system_upgrade).

## Dependency Upgrades

If Curator requires dependency updates before upgrading, such as PHP, follow the steps provided in our
[dependency upgrades](/upgrading_migration/upgrading/dependency_updates)
documentation.

## License Expiration Blocking Upgrade

When you start a one-click upgrade, Curator runs a set of pre-upgrade checks and shows the results in a
confirmation window. If your license check fails, that window is headed **"Caution! An issue was found"** and
lists:

> License Expiration **You will not be able to upgrade until this is resolved.**

When an issue blocks the upgrade, the **Upgrade** button is not shown in that window — only **Cancel**.

This is a license check, not a PHP or database check, so the fixes described elsewhere on this page do not
apply. Curator stores the expiration date that the InterWorks licensing service reports for the license key
saved on your instance, and blocks the upgrade when that date is in the past or when Curator has no expiration
date on record at all. A missing date is common when the stored key is absent or incorrect — for example after
a migration to a new server — or when a recent renewal has not yet been synced to the instance.

The **License Expiration** tile at the top of **Settings** > **Curator** > **System Upgrade** shows the date
Curator currently has on record, which tells you which of the two cases you are in.

<Note>
  On Curator SaaS, InterWorks manages your license and performs your upgrades, and the **Update Key** link is not
  shown. If you see this error on a SaaS instance, contact [Curator support](https://interworks.com/help).
</Note>

**Step 1 — Reload the System Upgrade page:**

Curator re-syncs the expiration date from the licensing service each time the System Upgrade page loads.
Navigate to **Settings** > **Curator** > **System Upgrade** and let the **License Expiration** tile populate. If
it now shows a future date, retry the upgrade.

**Step 2 — Re-enter your license key:**

If the tile still shows no date, or reports your key as missing, re-enter the key by following the
[Updating License Key](/site_administration/license_key/updating_license_key) guide. Saving the key clears
Curator's cache for you, so no separate cache clear is required. Return to the System Upgrade page afterwards so
the expiration date can sync, then retry the upgrade.

If the tile still shows stale information, clear the cache explicitly using the **Clear Cache** button in the
backend, or by appending `?cache=clear` to any Curator page URL, and reload the System Upgrade page.

**Step 3 — Check whether the license has actually lapsed:**

If the tile shows a real expiration date that has already passed, your subscription has lapsed and re-entering
the same key will not clear the block. Contact your account manager to renew, then repeat Step 1 so the renewed
date syncs to your instance.

If the error persists after the steps above, contact [Curator support](https://interworks.com/help) with the
exact error text, your Curator version, and the URL of the instance. Do not post your license key in a public
channel.

## Curator Upgrade Failing After a PHP Upgrade

If you upgraded PHP on your server independently and the Curator upgrade now fails, a PHP version mismatch is
the most likely cause. Each Curator release supports a specific range of PHP versions, and running outside that
range causes runtime errors.

This scenario is easy to miss because the System Upgrade page only checks whether your PHP version is *too old*
for the release you are installing. It does not warn you when your PHP version is *newer* than the release
supports. If you upgraded PHP past the maximum version supported by your **currently installed** Curator
release, that release starts throwing runtime errors — including while it is running the upgrade — with no
version warning shown.

**Step 1 — Check your current PHP version:**

Run `php --version` on your web server. If you cannot access the server, log in to the backend of Curator and
navigate to **Settings** > **Curator** > **Status**, where the PHP version is listed for self-hosted instances.

**Step 2 — Compare against the supported PHP range:**

Refer to the
[PHP compatibility table](/upgrading_migration/upgrading/dependency_updates#php-dependencies-by-curator-version)
and check your installed PHP version against **both**:

* the release you are currently running, since that code is what performs the upgrade, and
* the release you are upgrading to.

**Step 3 — Resolve the mismatch:**

* If your PHP version is **above the maximum** supported by your currently installed Curator release: downgrade
  PHP to a version within that release's supported range, complete the Curator upgrade, and then re-apply the
  PHP upgrade once you are on a Curator release that supports it. This restores the normal order of operations —
  Curator first, PHP second, or PHP first only when the release you are on already supports it.
* If your PHP version is **below the minimum** supported by the release you are upgrading to: follow the
  [Dependency Updates](/upgrading_migration/upgrading/dependency_updates) guide to upgrade PHP into the
  supported range. In this case the System Upgrade page will also show a **"PHP X.X+ Required"** warning on the
  release.
* If you are unsure which direction the mismatch runs, contact
  [Curator support](https://interworks.com/help) with your PHP version, your current Curator version, and the
  version you are trying to upgrade to, and we can advise on the safest path forward.

Once PHP is inside the supported range, retry the upgrade using any of the methods described in the
[System Upgrade Guide](/upgrading_migration/upgrading/system_upgrade). If errors persist, capture the event log
using the [Event Log Troubleshooting](#event-log-troubleshooting) steps below and send it to Curator support.

## Updating the Curator Database (Running Migrations)

<Note>
  Curator returns **503 Database Error: Check Curator Logs to Resolve** when a database query fails during a web
  request. Unfinished migrations are one cause after an upgrade. The steps in this section re-run them. On
  Curator SaaS, InterWorks hosts your instance. Send the error to
  [Curator support](https://interworks.com/help) instead.
</Note>

Curator's database is often modified during the upgrade process, and if database changes are not completed
successfully database errors can occur.

If you run into any database errors after upgrading, or during the upgrade process, re-running Curator's
database migrations can resolve these errors.
You can safely rerun these migrations multiple times without any adverse effects.

**To Re-run the Curator Database Migrations From Your Browser:**

1. Visit your Curator url in a web browser, but add `/up` to your URL, for example: `https://curator.example.com/up`
2. You should be directed to a page that contains "success" followed by a list of the steps taken to finish
   the migration. If you see errors instead, make note of the errors seen and contact Curator support for
   further assistance.

**To Re-run the Curator Database Migrations From the Web Server:**

1. Open a command prompt/terminal.
2. *Double-check* that you are running the terminal/command prompt as the same user that is running Curator
   (you can find this information on the backend of Curator under **Settings** > **Curator** > **Status**).
3. Use the `cd` command to move the command prompt into your webroot (e.g. `cd /var/www/html` on Linux or
   `cd C:\InterWorks\Curator\htdocs` on Windows).
4. Type `php artisan winter:up` and then press ENTER.
5. Any remaining database migrations will run, and display status messages in green.
6. If there are any errors during this process, please take a screenshot and send it to Curator support.

## File System Permissions Issues

If Curator's logs contain errors relating to filesystem permissions on your Curator site, or the site itself
is rendering an error that says "failed to cache..." or "permission denied...", or "no such file found...",
use the following steps to resolve this issue:

1. Click the "clear cache" button on the backend of Curator
2. Use our [Filesystem Permissions Guide](/server_management/system_administration/filesystem_permissions)
   to fix any errant file permissions settings.

## Fix Corrupted Files

If Curator is displaying an error message stating "vendor files are missing" or some pages may throw a
warning message that some files were not able to be found, you can re-download the Curator system files to
your web server using the steps below:

***Fixing Corrupted File Systems on Linux:***

1. `cd` into your webroot directory (e.g. `/var/www/html`)
2. Run the commands below, replacing the `[curator_key]` in the URL with your Curator license key. If you
   don't know your license key, reach out to your account manager for more information.

   wget -O latest.zip "[https://api.curator.interworks.com/get\_version.php?key=\[curator\_key\]\&kernel=473\&version=latest](https://api.curator.interworks.com/get_version.php?key=\[curator_key]\&kernel=473\&version=latest)";
   unzip latest.zip;
   rm -Rf plugins/interworks;
   rm -Rf vendor;
   cp core/. . -Rf

   NOTE: You may replace `latest` in the URL above with a specific version
3. Manually rerun database migrations using the steps provided in the **Updating Curator Database** section.
4. Visit your Curator site in a web browser to confirm whether your site is back up and running.

***Fixing Corrupted File Systems on Windows:***

1. From a web-browser visit the URL below to download a .zip file with your Curator filesystem, replacing the
   `[curator_key]` in the URL with your Curator license key. If you don't know your license key, reach out to
   your account manager for more information.
   `https://api.curator.interworks.com/get_version.php?key=[curator_key]&kernel=473&version=latest`
2. Make a backup of your webroot in case of any errors that occur in the steps below.
3. Unzip the file that was downloaded from **Step 1** into your webroot (e.g. `C:\InterWorks\Curator\htdocs`)
   and replace all files with the newly extracted files.
4. Manually rerun database migrations using the steps provided in the **Updating Curator Database** section.
5. Visit your Curator site in a web browser to confirm whether your site is back up and running.

## Event Log Troubleshooting

***Event Log Retrieval if You Can Access the Curator Backend in a Web Browser:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Logs** > **Event Log** section using the left-hand menu.
3. Look for any "upgrade" related errors.
4. Reach out to support for further troubleshooting.

***Event Log Retrieval if You Cannot Access the Curator Backend in a Web Browser:***

1. Log on to the web server that hosts Curator.
2. Find the Curator event logs:
   * **Windows**: `C:\InterWorks\Curator\htdocs\storage\logs`
   * **Linux**: `/var/www/html/htdocs/storage/logs`
3. Find the log file with today's date (e.g. system-2025-03-17.log ).
4. Copy the file and send it to Curator support.


# Automatic License Provisioning 
Source: https://docs.curator.interworks.com/users_groups/user_management/automatic_license_provisioning

Automatically provision Tableau Server licenses for users when they access Curator for streamlined license management.

Tableau allows Administrators to manage their licenses in a way that all users can be added as unlicensed and only
[grant them a license][1] once they are logging into Tableau Server. You can now use this feature through your Curator.
All users that are currently unlicensed will receive a license when trying to log into Curator if you have this feature enabled.

## Note This feature is only available when you either use SAML or OAuth/OpenID for authentication

***To grant license on sign-in with SAML***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Tableau** > **Tableau Server Settings** section from the left-hand menu.
3. In the Authentication tab, expand the **SAML Advanced** section and enable the "License Users if Unlicensed" toggle.

***To grant license on sign-in with OAuth/OpenID***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Tableau** > **Tableau Server Settings** section from the left-hand menu.
3. In the Authentication tab, expand the **Customization** section and enable the "License Users if Unlicensed" toggle.

## Active Directory and LDAP Group-Managed Licenses

When Tableau Server is configured to sync licenses through Active Directory (AD) or LDAP groups, the license
lifecycle is managed by Tableau's own group sync process rather than by Curator. This creates an important
distinction in how automatic license provisioning behaves.

**Direct license removal vs. AD/LDAP group removal:**

* **Direct removal** — If a user's Tableau license is removed directly (e.g., by an administrator setting the user
  to Unlicensed in Tableau Server), Curator's "License Users if Unlicensed" feature can automatically restore the
  license the next time the user signs in.
* **AD/LDAP group removal** — If a user's license is removed because they were removed from an AD or LDAP group that
  grants a Tableau site role, Tableau Server manages the license through its group sync schedule. Even after the user
  is re-added to the AD group, the license is not restored until Tableau Server completes its next group sync. Curator
  cannot override this because Tableau's AD/LDAP sync controls the site role assignment for group-managed users.

### Troubleshooting: License Not Restored After AD Group Re-Addition

If a user was removed from an AD or LDAP group and then re-added but still cannot access Curator, verify the
following:

1. **Confirm the user is back in the AD/LDAP group.** Check with your directory administrator that the group
   membership change has replicated across all domain controllers.
2. **Wait for Tableau Server's group sync to complete.** Tableau syncs AD/LDAP groups on a schedule configured by
   your Tableau Server administrator. The user's license will not be restored until this sync runs. You can check
   the sync schedule in **Tableau Server** > **Settings** > **General** under the group sync section.
3. **Manually trigger a group sync if needed.** A Tableau Server administrator can manually sync groups from the
   **Groups** page in Tableau Server to restore the user's site role without waiting for the next scheduled sync.
4. **Verify the user's site role in Tableau Server.** After the sync completes, confirm the user has been assigned
   the expected site role (e.g., Viewer, Explorer) in Tableau Server's **Users** list.
5. **Have the user sign in to Curator again.** Once the Tableau license is restored through the group sync, the user
   should be able to access Curator normally.

If the issue persists after completing these steps, check the Tableau Server background task logs for sync errors
and confirm that the AD/LDAP group is still mapped to the correct site role in Tableau Server's group configuration.

[1]: https://help.tableau.com/current/server/en-us/grant_role.htm


# Custom Attributes
Source: https://docs.curator.interworks.com/users_groups/user_management/custom_attributes

Define and manage custom user attributes for enhanced user profiling and personalized content delivery.

With Tableau Cloud, and Tableau Server versions 2023.1 and above, you can now pass through User Attributes from Curator
or your SAML IdP (e.g. Okta, Azure AD) seamlessly through to your Tableau Dashboards.  This will allow you to use
[a new calculated field `USERATTRIBUTE()`](https://help.tableau.com/current/pro/desktop/en-us/functions_functions_user.htm#userattribute)
in your Dashboard to retrieve the value of the User Attribute and filter your data accordingly.

There are two ways to assign Attributes to users in Curator.  The can either be inherited from their
[SAML profile on login](#enabling-saml-attribute-retrieval-on-login), or
[assigned directly to the user](#assigning-user-attributes-to-a-user-on-curator) or their
[group](#assigning-user-attributes-to-a-group-on-curator) in Curator.

## Enabling SAML Attribute Retrieval on Login

You can automatically assign User Attributes to Curator users based on the Attributes sent from your SAML Identity
Provider (IdP) when they login.  This allows you to centrally manage User Attributes in your IdP, and have them
automatically applied to users in Curator on login.

<Note>
  [SAML Authentication](/setup/authentication/overview) must be enabled to associate your SAML provider's Attributes
  to Curator users on login.
</Note>

1. <BackendNavPath />

2. In the repeater, enter the name of the User Attribute you would like Curator to detect from the user's SAML profile
   on login.
   <Frame>
     <img alt="SAML Custom Attributes Configuration" />
   </Frame>

3. Be sure to Save your changes.

Now, when your users login to Curator, any Attributes you have registered here that are present in their SAML profile
will be automatically assigned to their Curator user profile and passed through to Tableau, allowing you to use the
Tableau `USERATTRIBUTE()` function in your dashboards to show or hide data accordingly.

## Assigning User Attributes in Curator

If you are not using a SAML IdP, or need to assign additional Attributes to your users that are not present in your SAML
profile, you can assign Attributes directly to users or groups in Curator.

### Assigning Group Attributes

1. <BackendNavPath />
2. Find a user group and click on the group to edit details, or click the "New Frontend Group" button to create a new
   group on Curator.
3. Expand the **Custom Attributes** section, and enter the attribute name and value you would like to assign to all
   users that belong to this group.
   <Frame>
     <img alt="User Group Attributes Configuration" />
   </Frame>
4. Click the "Save" button.

Any member of the group will now inherit these Attributes, which will be passed through to Tableau when loading a
dashboard.

### Assigning User Attributes

1. <BackendNavPath />
2. Find a user and click on the user to edit details - if no user exists, you can create one first before proceeding.
3. On the edit-user page, expand the **Custom Attributes** section, and enter the attribute name and value you would
   like to assign to this user.
   <Frame>
     <img alt="User Attributes Configuration" />
   </Frame>
4. Click the "Save" button.

This user will now have these Attributes assigned directly to them, which will be passed through to Tableau when loading
a dashboard.

## User Attribute Inheritance

When a conflict arises due to the same attribute being found in multiple locations, the User attributes will take
highest precedence, followed by Group attributes and then SAML attributes.  So for example, if a user has an attribute
`Region: US` assigned directly to them, but their group has `Region: EU`, the resolved attribute for that user will be
`Region: US`.

### Viewing a User's Resolved Attributes

Because of the inheritance described above, you may wish to see the final set of Attributes that a user has.  To view
the user's resolved attributes:

1. <BackendNavPath />
2. Find a user and click on the user to view the edit-user page.
3. On the edit-user page, expand the **Custom Attributes** section.  Any assigned attributes will appear at the top of
   the section under the **User Attributes** header:
   <Frame>
     <img alt="Resolved User Attributes" />
   </Frame>

These "Resolved Attributes" take into account inheritance from all sources. However, if a user has not yet logged in,
their SAML attributes will not be populated until their first login.


# Frontend Users
Source: https://docs.curator.interworks.com/users_groups/user_management/frontend_users

Manage local Curator user accounts including creation, permissions and configuration for Curator Users authentication.

<Note> This is only relevant for use with the authentication setting **Curator Users** </Note>

If you're using [Curator Users](/setup/authentication/curator_users)
as the authentication source (or SAML IdP), the system will enable administrators to manage the
frontend users.

***To enable management of frontend users:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Security** > **Authentication Settings** in the left navigation.
4. Select "Curator Users" for the authentication type.
5. Click on the "Save" button.

***To manage frontend users:***

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on the **Settings** > **Users** > **Frontend Users** in the left navigation.
4. Click on the "New Frontend User" button to create a new user, or click on an existing user to modify user details or permissions.

<Note>
  The **Password** field has an eye icon at its right edge. Click it to reveal what you have typed, and click it again
  to hide it. This only ever shows text you typed in the current session -- the field is always empty when the form
  loads, so an existing password is never revealed.
</Note>

If you're using an external identity provider instead of Curator Users, see
[Just-in-time (JIT) Provisioning](/users_groups/user_management/just_in_time_jit_provisioning) for how Frontend User
accounts are created automatically on first sign-in.

<Note>
  There is no bulk or CSV import for Frontend Users in the backend UI -- the "New Frontend User" button and each user's
  edit form both create or update one user at a time. To create many users without repeating those steps manually,
  script calls to the [`/user/createFrontendUser`](/curator_api/api_docs/user_api) API endpoint or the
  [`usermgmt:frontendusercreate`](/curator_api/artisan_commands/frontendusercreate) artisan command instead. This is
  unrelated to the Frontend Group [Batch Create](/users_groups/user_management/users_and_groups_overview) feature,
  which creates groups, not users.
</Note>


# Just-in-time (JIT) Provisioning 
Source: https://docs.curator.interworks.com/users_groups/user_management/just_in_time_jit_provisioning

Configure just-in-time user provisioning to automatically create user accounts during first-time authentication.

## JIT Provisioning on Curator

When Curator is configured to authenticate against an external identity provider (SAML, OIDC/OAuth, Tableau Server, or
Power BI), a Frontend User account is created automatically the first time a user successfully signs in. This removes the
need for self-service registration: as long as the user can authenticate with the upstream provider, Curator provisions
the matching local account on demand.

If you'd rather restrict access to users that have been created manually in advance, this behavior can be disabled.
Navigate to **Settings** > **Security** > **Authentication Settings**, expand the **Customization** section, enable
*Disable Just-in-time Provisioning of Curator Users*, and click the "Save" button. With this setting enabled, SSO logins
will only succeed for users who already exist in **Frontend Users**.

## JIT Provisioning on Tableau

Curator can also serve as an intermediary to that process and automatically create the users on Tableau Server after a
successful authentication with Okta or other SAML identity providers.  You will still be required to manually assign any
groups, or license levels (Explorer by default), in Tableau Server.  But this allows simple authentication into Curator if
the user does not yet exist on Tableau.
(/setup/authentication/okta\_saml)
To enable this, complete the steps for SAML setup ([instructions here](/setup/authentication/okta_saml))

Then on the backend under **Settings** > **Security** > **Authentication Settings**, open up the **SAML Advanced** section
and enable *Just-in-time (JIT) Provisioning* then Save your SAML settings.

## Licensing Unlicensed Users on Login

Curator can automatically license a Tableau user who exists on Tableau Server/Cloud but has no assigned role (Unlicensed).
When *License Unlicensed Users on Login* is enabled under **Authentication Settings**, Curator will assign the configured
JIT site role to the user on their next login.

### Tableau Group Minimum Site Roles

If a user belongs to one or more Tableau groups that have a **minimum site role** configured, Tableau will reject any
attempt to assign a role lower than that minimum. When this situation is detected, Curator automatically uses the highest
group minimum site role across all of the user's group memberships instead of the configured JIT role.

For example: if the JIT role is set to *Viewer* but the user belongs to a group whose minimum site role is *Explorer*,
Curator will license the user as *Explorer*.

When Curator raises the role in this way, an informational entry is written to the application log explaining which
user was affected, what the configured JIT role was, and what effective role was applied. Check
`storage/logs/system-YYYY-MM-DD.log` if you expect this to be happening and want to confirm the behavior.


# Reset User's Password
Source: https://docs.curator.interworks.com/users_groups/user_management/reset_users_password

Reset user passwords as an administrator when users cannot access their accounts or have forgotten credentials.

When managing users you may find a need to change a user's password on Curator.  The method used to change user's
passwords will depend on the [authentication type](/setup/authentication/overview)
you are using on Curator: when using *Tableau Server* or *Curator Users* authentication you can reset users passwords
within Curator.  For all other options you will need to use the source-system of your user store (your IdP) to change the
password there.

**To reset a user's password:**

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Tableau** > **Tableau Users** or **Settings** > **Users** > **Frontend Users** section
   from the left-hand menu.
3. Find the user in the list that you're looking for in the list of users, then click on the row to navigate to the
   edit-user page.
4. Type in a new password for the user, then click the save button.  On the **Frontend Users** edit page you can
   click the eye icon at the right edge of the Password field to check what you typed before saving.
5. The end user will **NOT** be notified of this change, so be sure to let them know of the change made.


# SAML Group Mapping
Source: https://docs.curator.interworks.com/users_groups/user_management/saml_group_mapping

Automatically assign users to Frontend Groups based on attributes in their SAML response.

SAML Group Mapping lets you define rules on a Frontend Group so that users are automatically added to that group
when a SAML attribute in their login response matches a specified value. This is useful when your identity provider
(e.g. Okta, Azure AD) already organizes users by department, role, or other attributes that you want to reflect as
Curator Frontend Group membership without manual assignment.

## Prerequisites

* [SAML Authentication](/setup/authentication/overview) must be enabled on your Curator instance.
* The SAML attributes you want to match must be included in your identity provider's assertion. You do not need to
  configure those attributes under **Authentication Settings > SAML Attributes** — SAML Group Mapping works
  independently of the Custom Attributes feature.

## Configuring SAML Group Rules

1. Log in to the backend of your Curator instance (e.g. `https://www.curatorexample.com/backend`).
2. Navigate to **Settings** > **Users** > **Frontend Groups**.
3. Open an existing group or click **New Frontend Group** to create one.
4. Scroll down to the **SAML Groups** section.
5. Click **Add Item** under **SAML Attribute Rules** to add a rule.
6. Enter the **Attribute** name exactly as it appears in the SAML response (e.g. `department`).
7. Enter the **Value** that should trigger membership (e.g. `Finance`).
8. Repeat for any additional rules. A user matching **any** rule will be added to the group.
9. Click **Save**.

## How Membership Is Applied

Membership is evaluated in two ways:

* **On login**: When a user authenticates via SAML, Curator immediately checks their SAML attributes against all
  group rules and adds them to any matching groups. This is the primary sync path and ensures membership is current
  by the time the user's session begins.
* **Batch sync**: Curator's scheduled group membership sync also evaluates SAML rules by querying SAML attributes
  stored against each user record. This allows groups to be updated on a schedule without requiring every user to
  log in first.

## Important: New Rules and Batch Sync

Curator only stores the SAML attribute keys that are actively referenced in at least one group rule. This keeps
personally identifiable information (PII) to a minimum — attributes not used by any rule are never written to the
database.

As a consequence, if you **add a new rule referencing an attribute that was not previously configured in any group**,
that attribute will not yet be present in stored user records. Batch sync will not be able to match users against
the new rule until those users log in again and their stored attributes are refreshed.

**To apply a new rule immediately** without waiting for each user to log in, you can trigger a manual membership
sync after the affected users have logged in, or notify users to log in and then run the sync.

This limitation does not affect the on-login sync path — users will always be evaluated against the current rules
the moment they authenticate.

## Relationship to Custom Attributes

SAML Group Mapping and [Custom Attributes](/users_groups/user_management/custom_attributes) are separate features
that both read from the SAML response. Custom Attributes pass values through to your analytic platforms (e.g. for
Tableau `USERATTRIBUTE()` filtering). SAML Group Mapping uses attribute values solely to determine Curator Frontend
Group membership. You can use both features with the same or different attributes.


# User Sync and Membership Sync Overview 
Source: https://docs.curator.interworks.com/users_groups/user_management/user_sync_and_membership_sync_overview

Overview of user synchronization and membership sync processes between Curator and external authentication systems.

There are two different sync process that run in Curator: the user sync and the group membership sync. There used to be
one sync that did both, but we found bringing over every user and group resulted in very slow syncs and a lot of
redundancy. Separating the one sync into two has led to much greater efficiency but some confusion. This doc aims to
answer frequently asked questions about these syncs and will be updated as new questions are asked.

First, a quick primer on both syncs:

1. **User Sync**:
   * **What is it?**
     The user sync brings user details from your analytic platforms to Curator. This includes full display name, email
     address, user roles, etc. This does not include group membership.
   * **When does it happen?**
     The user sync always happens on login. You can also manually sync a specific user's details from the Curator
     backend > Settings > Users > Frontend Users > select a specific user and use the buttons in the "Platform Users"
     section to sync the details.
     *Note: If the user doesn't exist on Curator the user sync will create it. This results in having a lean user base of
     only the true Curator users.*
     *Note: You cannot disable the on-login user sync.*
2. **Group Membership Sync**:
   * **What is it?**
     The group membership sync builds Curator Frontend Group membership from a user's platform group membership. For
     instance, you can create an "Admins" Frontend Group in Curator and, instead of manually selecting numerous users, you
     can select the "Admins" group from one of your platform connections and Curator will automatically put those users in
     the Curator Frontend Group. This does not include user details.
     *Note: This is only relevant if you use Curator Frontend Groups for restricting access in the navigation or for
     Frontend Group Overrides. If you don't use these features then group membership is irrelevant to Curator.*
   * **When does it happen?**
     The group membership sync will happen on login by default. Some platforms can have slow response times when Curator
     requests the relevant membership, so you can disable the on-login membership sync to speed up the login. If you
     disable the on-login membership sync you can enable a sync to occur on a scheduled cadence to ensure users are in
     their groups by the time they login.
     *Note: If you disable the on-login membership sync, the scheduled membership sync will create users if they don't
     already exist on Curator. This is to preemptively ensure the user has their groups before logging in, which requires a
     Curator user. This is the **only scenario** where the group membership sync also syncs user details.*

**Where are my Users?**
You can find your Frontend Users at the Curator Backend > Settings > Users > Frontend Users. This page will also show the
associated platform-specific users.

**Where are my Groups?**
You can find your Frontend Groups at the Curator Backend > Settings > Users > Frontend Groups. You can trigger syncs and
change sync settings from this page.

**Why would I create groups?**
The primary features that leverage Curator Frontend Groups are:

1. **[Restrict Access](/site_content_design/menus/restrict_access)**
   You can deny permission to see content in Curator by restricting access in the navigation based on group membership. This
   is especially helpful for content created in Curator that doesn't have permissions to pull from an analytic platform (i.e.
   Pages, Files, external URL's, etc.). This can also be useful if your navigation has many items and the permission checks
   add copious load time by restricting access to a high-level menu item, which automatically denies access to all of the
   item's children.
2. **Frontend Group Overrides**
   Overrides are useful if you have groups of users who require a different look-and-feel in the Curator frontend. This is
   common if you have groups/departments or multiple tenants who use different logos, colors, etc. You can also present
   entirely different navigation structures and homepages to your various groups.

**How do I create groups?**
You can create a Frontend Group at Curator Backend > Settings > Users > Frontend Groups by using the "New Frontend Group"
button. You can build membership by either manually selecting uses from the "Group Membership" section or by using a group
from one of your connected analytic platforms. For instance, you can create an "Finance" group that uses a Tableau Group
and ThoughtSpot Group instead of manually selected every use who needs to see finance content.

**Curator used to automatically create Frontend Groups that were in Tableau, but not anymore. Why not?**
If your Curator instance doesn't leverage restricted access by group or Frontend Group Overrides then Tableau Groups are
irrelevant to Curator and syncing them is unnecessary. Even if you do use a couple Tableau Groups for Curator Frontend
Groups you don't need all of them. Now Curator's membership syncs are much leaner and more efficient, resulting in the
same functionality with much better performance.

**I created a user in Tableau, but it doesn’t show they are synced in Curator. How do I get Curator to sync a user?**
The user will be synced to Curator as soon as they log in. Users are always synced during login.
*Caveat: Tableau uses unique user records for each Site they are a member of. To avoid long login times, Curator only
syncs the Tableau User from the Site you've specified in the REST connection (Curator backend > Integrations >
Connections). The other Site users will be synced on a daily cadence.*
*Caveat to the caveat: If you've enabled the Tableau Repository connection every Site user will be synced on login.
Repository queries are much faster than REST API calls so the login time isn't as affected.*

**I linked a Frontend Group to a platform group, but the membership sync never seems to finish. What do I check?**
Only the on-login membership sync runs immediately. The "Sync All Group Memberships" button and the scheduled cadence
instead queue one background job per Frontend Group, so nothing happens while you wait on the Frontend Groups page —
the membership fills in once the queue gets to that job.

To find out where a sync is stuck:

1. Navigate to your Curator Backend > Settings > Curator > Queued Processes and look for a job of type
   `groupSyncSchedule` whose object is the group you just created. Completed jobs are removed from the list, so if no
   such job is there, the sync already ran and the group's membership reflects the last sync.
2. If the job sits in **Pending** for more than a minute or two, the scheduler that drains the queue isn't running.
   On a self-hosted (On-Prem) instance this is almost always a missing or broken cron entry — see
   [Linux Cron Troubleshooting](/server_management/system_administration/linux_cron_troubleshooting) to confirm the
   per-minute `schedule:run` entry is present and executing. On Curator SaaS, InterWorks runs the scheduler for you, so
   open a support ticket instead.
3. Curator won't queue a second sync for a group while one is still listed for it, so a stuck job also silently
   blocks any later sync you trigger. Once you've fixed the underlying cause, clear the old job with **Cancel Selected**
   or **Clear Pending** from the Queued Processes toolbar, then trigger the sync again.

For more detail on reading and clearing the queue, see
[Queued Processes](/site_administration/performance/queued_processes).

*Note: If you need members in the group before the queue catches up, have them log in. Unless you've disabled the
on-login membership sync, logging in syncs that user's group membership immediately.*


# Username Mapping 
Source: https://docs.curator.interworks.com/users_groups/user_management/username_mapping

Map external user identifiers to local usernames for proper authentication and user synchronization across systems.

If your analytic infrastructure was built by several independent groups within your organization, it's possible that the
username formats don't match across the platforms. Authenticating to each platform can usually be solved with a single
sign-on solution, but the issue still exists for embedding these platforms. API's that are used to verify user
information, permission to analytic content, group membership, etc. rely on local platform users and can't leverage SSO
credentials. Curator solves this with a built-in platform username formatting.

<Note>
  Username mapping can only change the **format** of a username, not the username itself. For example, it can convert
  `first.last@example.com` to `example\first.last`, but it cannot convert `first.last@example.com` to
  `flast@example.com`.
</Note>

## How it Works

Curator's username formatting feature will take the username received from your authentication source (SAML IdP, Tableau
Server local auth, ThoughtSpot local auth, etc.) and map it to another format based on the API call being made. For
instance, if Okta is returning the username as an email address but Tableau Server users use the prefixed domain format
the following will happen (assuming the username is InterWorks\Curator in Tableau Server):

1. User logs into Curator via Okta using their Okta credentials.
2. Okta returns the username as `curator@interworks.com`.
3. Curator automatically re-formats the username to InterWorks\Curator in order to sync the Tableau Server user details.

## How to Configure

1. Navigate to the Curator Backend > Settings > Users > Username Formatting
2. Turn on the "Enable Username Mapping" switch
3. Specify the username format your authentication source is returning back to Curator using the "Curator Frontend
   Username Format" field.
4. Specify the username format for each Connection you've configured in Curator. You can use a different format per Connection.

## Supported Formats

The following are the supported username formats assuming the username is "Curator" and the domain is "InterWorks":

* Username Only > Curator
* Username with Prefixed Domain > InterWorks\Curator
* User Email > `curator@interworks.com`

## Domain Formatting

In addition to mapping username formats for multiple platforms, you may also need to map the domains. For instance,
*iw\Curator* doesn't match `curator@interworks.com` in format or domain. To handle this situation, you can configure
domain mapping:

1. Navigate to the Curator Backend > Settings > Users > Username Formatting
2. Turn on the "Enable Domain Mapping" switch
3. Use the "Domain Map" area to specify as many mappings as you need, specifically the following:
   * **Connection**: The connection being mapped to from your Frontend User
   * **Frontend User Domain**: The domain to find in the Frontend User name
   * **\[Platform] User Domain**: The replacement domain for the platform user name

## Example

My SSO system is returning *iw\Curator* but my Tableau user is `curator@interworks.com`. The following settings would
resolve this mismatch:

For the mismatch format

1. Turn on "Enable Username Mapping" switch
2. Choose "Username with Prefixed Domain" for the "Frontend User Username Format" field
3. Choose "User Email" for the "Tableau Username Format"

For the mismatch domain

1. Turn on "Enable Domain Mapping" switch
2. Add a new item under "Domain Map"
3. Choose "Tableau" for the "Connection" field
4. Type "iw" for the "Frontend User Domain"
5. Type "InterWorks" for the "Tableau User Domain"
6. Save all the settings


# Users and Groups Overview
Source: https://docs.curator.interworks.com/users_groups/user_management/users_and_groups_overview

Comprehensive guide to user management in Curator covering frontend users, groups, permissions and authentication methods.

## Frontend Users

"Frontend users" (or local Curator users) are responsible for bringing together your various platforms to create
individual frontend experiences. These users are matched based on their usernames, so it's crucial to ensure consistent
naming across your connected systems - if you do not have them matched exactly, see our [Username Mapping guide](/users_groups/user_management/username_mapping).

To view the list of frontend users, go to the backend and navigate to **Settings** > **Users** > **Frontend Users** from
the left-hand menu. Each user who has signed into Curator will have a corresponding record. Clicking on a user record
will display details about that user, including any connected platforms.

You can also get a [preview of the user's navigation](/users_groups/user_security/frontend_user_permissions)
near the top of this page.

## Platform Users

"Platform users" refer to the records maintained by Curator for users synced from your connected systems (e.g., Tableau
users, ThoughtSpot users, etc.). These platform users store synced information from the respective systems, which can be
leveraged by the Frontend User for permissions and platform-specific actions like favoriting or subscribing to a Tableau
Dashboard.

To access the list of platform users, go to the backend and navigate to
**Curator Backend** > **Settings** > ***\[PlatformName]*** > ***\[PlatformName] Users*** from the left-hand menu.
Some systems may have multiple records per user if they have multiple IDs
(e.g., Tableau has a user record with unique IDs ***per site***). Clicking into a user record will provide more details
about that user. You can also [sync a specific platform user](/users_groups/user_management/user_sync_and_membership_sync_overview)
from this page.

## Frontend Groups

Frontend groups are created within Curator and serve functionalities such as
[restricting access](/site_content_design/menus/restrict_access)
to navigation items or [overriding frontend styles based on group membership](/site_content_design/theme/group_overrides).
To access these groups, go to the backend and navigate to **Curator Backend** > **Settings** > **Users** > **Frontend Groups**.

### Creating Frontend Groups

Membership for frontend groups can be established by manually selecting users or by choosing one or more groups from
other platforms. If a group from another platform is chosen, the membership will automatically be reflected in the
frontend group.

For example, let's say you create a group called "Tableau Users" and select the "All Users" group from your Tableau
Server's default site. In this case, any user who logs in and has a Tableau user account from that site will be
automatically added to the "Tableau Users" frontend group.

#### Batch Create

If you want to create multiple Frontend Groups associated with one platform group each, you can use the batch create
functionality instead of repeating the create process:

1. Go to **Curator Backend** > **Settings** > **Users** > **Frontend Groups**.
2. Click the "Batch Create" button.
3. Select the sources from which you want to pull groups. This action doesn't create Frontend Groups; it only pulls in
   a list of available groups from the selected sources.
4. Click "Preview Available Frontend Groups".
5. Check the boxes next to each group you want to create. If you're having trouble finding the desired groups,
   you can sort the table by clicking on the column headers

## User and Membership Syncing

Curator needs to make API calls to your various platforms to keep the platform user information up to date.
This happens when a user logs into Curator to ensure they have the most current information. At the same time,
Curator checks if the user is in any platform groups associated with a frontend group and updates the membership accordingly.

Curator also provides the option to run a scheduled group sync for all frontend groups. You can find the settings for
this at **Curator Backend** > **Integrations** > **Global Settings**. By default, you can keep this set to "Never" as
the membership is updated on login.

Sometimes, the login process can be slow because the platform takes time to respond with the group information. If this
is the case, there is a feature called "Skip User Group Sync on Login" in **Integrations** > **Global Settings**.
Enabling this feature will skip the membership sync on login and only perform the platform user sync, which tends to be
quick across systems. When this feature is enabled, new users will be created during the scheduled group sync to ensure
they are already in their groups when they first log in to Curator.

***Note:*** We recommend **not** disabling the on-login membership sync unless the Curator login process is very slow.
Allowing the sync to happen on login ensures the most current membership for your users.

***Note:*** If you disable the on-login sync, you also **need to ensure a scheduled group sync is configured** to run.
Ideally, you should do this during low usage hours (e.g., midnight) to ensure group membership is fully synced by the
time users log in.

***Note:*** If a scheduled Frontend Group sync gets stuck or you otherwise need to trigger one manually, see the
[`/User/syncGroup` and `/User/syncGroups` API endpoints](/curator_api/api_docs/user_api). These queue a sync for a
single named group or for all configured Frontend Groups respectively, providing a manual override when the scheduled
sync is not progressing.


# Disabling Link-preview Security 
Source: https://docs.curator.interworks.com/users_groups/user_security/disabling_link_preview_security

Disable link preview security features when needed for specific use cases or legacy browser compatibility.

Curator will automatically check with the source system (e.g. Tableau, ThoughtSpot, Sigma) when a user logs in to
determine their access to linked content from those systems. However, you can bypass this initial check and expose
links to all content to your users while still surfacing an
[Access Denied/403 page](/site_content_design/user_notifications_and_email/error_pages)
to prevent them from accessing content.

## Tableau

In order to disable security-checks on all content a user could see in the menu navigation system, or via a
tile/preview thumbnail:

1. <BackendNavPath />
2. Enable the **Skip checking menu item's Dashboard permissions** and save your settings.
3. If you would like to set up a custom "access denied" page follow the instructions on the [Error Pages document](/site_content_design/user_notifications_and_email/error_pages).

## ThoughtSpot

In order to disable all permission checks for ThoughtSpot content:

1. <BackendNavPath />
2. Enable the **Skip checking all content permissions** and save your settings.

## Power BI

In order to disable security-checks on all Power BI content a user could see in the menu navigation system, or via a
tile/preview thumbnail:

1. <BackendNavPath />
2. Enable the **Skip checking menu item permissions** and save your settings.
3. If you would like to set up a custom "access denied" page follow the instructions on the [Error Pages document](/site_content_design/user_notifications_and_email/error_pages).

To disable all permission checks for Power BI content:

1. <BackendNavPath />
2. Enable the **Skip checking all Power BI permissions** and save your settings.

## Sigma

In order to disable all permission checks for Sigma content:

1. <BackendNavPath />
2. Enable the **Skip checking all workbook permissions** and save your settings.


# Frontend User Permissions
Source: https://docs.curator.interworks.com/users_groups/user_security/frontend_user_permissions

Configure and manage user access permissions for different content types and features within Curator.

In order to manage permissions on Curator, there are a few different ways to control access to content - it's largely
dependent upon which content type you're working with.  First, we'll begin with troubleshooting permission to discover
what a user should have access to.  Below that you'll find specific instructions on how to set permissions on specific content-types.

## Preview An Individual User's Access

In order to see what permissions a user has on Curator, you can preview a user's access via the Menu system.

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Navigate to the **Settings** > **Users** > **Frontend Users** section from the left-hand menu.
3. Find the user that you would like to preview access for and click on the line containing their username.
4. On the Frontend User page click the "User Menu Access" button to view the a preview of the user's menu.  An icon next
   to each menu-link will show whether or not the user has access, and on hover will provide a reasoning why.

## Manage Permissions to Curator Content

Curator content does not have any inherent permissions - all automatic permissions are inherited from source systems that
Curator is connected to (e.g. Tableau permissions for embedded dashboards).  Creating a page without any embedded
analytic-content will result in global access for all your users.

When it comes to inheritance via the Menu, there is an exception to visible content: **Dropdown Placeholders** will only
display if the user has permissions to at least one item nested beneath the Dropdown.  If the user has access to none
of the items beneath the dropdown, it will not be visible to that user.  However, if you wish to apply permissions to a
specific piece of content, you have two options.

**Pages and Files** can be restricted in their own settings, which secures the content everywhere it can be reached
(menu links, direct URLs, search, and tiles).  For pages, see
[Restricting a Page to Groups](/site_content_design/pages/pages_overview#restricting-a-page-to-groups); for files, open
the file's **Security** tab.

For any other content, or to restrict a single menu link, create a menu-link for that content and use the Group-based
[Restrict Access](/site_content_design/menus/restrict_access) option.  You
can find the steps below:

1. Navigate to the backend of the system (e.g. `https://www.curatorexample.com/backend`).
2. Navigate to the **Content** > **Navigation** section from the left-hand menu.
3. Click on the "+ New Menu Link" button to create a new menu item.
4. Fill out the form to select the content you'd like to link to, then scroll to the bottom of the page and enable the
   **[Restrict Access](/site_content_design/menus/restrict_access)** toggle.
5. Check the boxes next to the groups you would like to grant permission to.  **NOTE**: If you do not see any groups,
   see our [Groups document](/users_groups/user_management/users_and_groups_overview)
   on how to add new Frontend Groups.
6. Save the menu item to apply permissions.

With that said, if you would like Curator to assume all content is restricted by default, you can enable it globally by
visiting **Settings** > **Security** > **Authentication Settings** > **Customization** section >
**[Restrict Access](/site_content_design/menus/restrict_access) is Always Enabled**
setting.  You will still need to add groups to each piece of content to allow
users to access them.  This setting applies to menu links and to pages, so every page also needs at least one group
selected in its **Page Details** before users can see it.

## Manage Permissions to Analytic Content

When adding content from a source system (e.g. Tableau) Curator will automatically check the Analytic Connection when a
user logs in to determine their access.  If a user has been granted access in the source-system (e.g. Tableau Server),
then they will have access to it in Curator.  You can override these permissions using the steps in the
*Manage Permissions to Curator Content* above.

Keep in mind that these inherited checks depend on Curator being able to reach the source system. If the Tableau
connection is down or misconfigured, Curator cannot verify a user's Tableau permissions and grants access rather than
blocking it. Restrict Access is checked against Curator's own database and keeps working during an outage. For more
detail, see
[Tableau connection issues](/site_content_design/menus/restrict_access#restrict-access-and-tableau-connection-issues).

### Disabling security to preview content

You can expose all links to analytic content in Curator to your users by bypassing the initial security check, but then
expose an "access denied" message when they visit links.  For steps on how to set that up, see
[Preview Security Settings](users_groups/user_security/disabling_link_preview_security).

### Troubleshooting Access

If you believe a user is getting an incorrect permission-denial, visit the Event Logs on the backend and search the logs
for either "403" or the user's username.  Each time a user is denied access to a page Curator logs the reason why under
a 403 error.


# Password Change
Source: https://docs.curator.interworks.com/users_groups/user_security/password_change

Allow users to change their own passwords through the frontend interface for improved account security.

The Password Change feature allows frontend users to reset their password through Curator. *NOTE: This only works if you
have chosen Curator Users or Tableau Server as your Authentication Type in the* **Settings** > **Security** >
**Authentication Settings**.

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left-hand menu.
4. On the **General** tab, scroll down to the **Security** section and expand it.
5. Toggle the switch **Password Change** on and click the "Save" button.


# Password Expiration and Complexity 
Source: https://docs.curator.interworks.com/users_groups/user_security/password_expiration_and_complexity

Configure password complexity requirements and expiration policies to enhance user account security.

For sites that use password change or password reset options you can now enable password expiration to force
frontend users to change their passwords on a frequent basis. To further bolster security, you can also
require users to have more complex passwords, requiring a specific length, numbers, and special characters.

***Please note that for these options to be able to be turned on, password reset or password change must be
enabled, and the site must be using Curator or Tableau for authentication.***

## Password Complexity Options

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the ‘General’ tab and expand the 'Security’ section.
4. Enable the toggle for **Password Complexity Options**.
5. Enter a minimum password length, and enable toggles for special character and require a number as desired.
6. Save your settings.

The new requirements will now appear on pages where you can change your password.

## Password Expiration

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Curator** > **Portal Settings** section from the left-hand menu.
3. Click on the ‘General’ tab and expand the 'Security’ section.
4. Enable the toggle for **Enable Password Expiration**.
5. Enter the number of days until user passwords will expire
6. Save your settings.

Note, upon updating a Curator site to have these new settings password changed date will be set for all users
of the current day and time. This will prevent a flood of users having to change their passwords. Password
expiration is checked upon login.


# Password Reset 
Source: https://docs.curator.interworks.com/users_groups/user_security/password_reset

Enable self-service password reset functionality for users to regain account access without administrator intervention.

Some users want the ability to reset their Tableau Server account password from Curator. The Password Reset
feature can address that issue but will require some additional setup. To use this it is required that you
enable Tableau Server REST API, setup/configure an SMTP Server, enter the SMTP information into Curator and
ensure that the Tableau Server user has an associated email address on their Tableau Server account.

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Log in if prompted.
3. Click on **Settings** > **Curator** > **Portal Settings** in the left-hand menu.
4. On the **General** tab, scroll to the **Security** section and expand it.
5. Toggle the **Password Reset** switch on and click the "Save" button.


# User Throttling 
Source: https://docs.curator.interworks.com/users_groups/user_security/user_throttling

Configure user request throttling and rate limiting to prevent system abuse and improve performance stability.

As a security measure, Curator throttles certain activities for a user to mitigate malicious activities.
Where possible, this blocks the logged in user.  If there is no logged in user, then it blocks the IP address
of the user.  For instance, logins only allow a limited number of failed attempts within a time period.  If
that limit is exceeded, the user's IP address is blocked for a period of time to help prevent someone from
brute forcing another user's password.

If Curator is behind a load balancer, reverse proxy, or some other network device that makes it look like all
users are sharing the same IP address, Curator won't be able to distinguish users by IP address so they'll
share the same throttle window when tracking activities that can't be tied to a logged in user.  In that
case, if there are several different users who all mistype their password within minutes of each other,
Curator will block all users from logging in.  If this becomes a recurring issue with your Curator site, the
potential fixes are:

* Fix your network device to pass through the IP address of each user instead of proxy-ing them as a single
  IP address.  See: [Reverse Proxy](/setup/proxy_configuration/reverse_proxy)
* Configure Curator's throttle to allow more failed attempts before triggering the throttle or a shorter
  suspension time after a throttle is triggered.

## Configuring Throttle

By default, Curator only allows 5 attempts within a 15 minute period and, if the throttle is triggered, there
is a 15 minute waiting period before the user is unblocked.

To customize these settings, navigate to **Backend** > **Settings** > **Security** >
**Authentication Settings** > **Customization** section.

The **activity throttle limit** determines how many attempts are allowed for throttle activities (failed
logins, password resets, etc.).

The **activity throttle reset period** determines how long the window is before the throttle count resets.
In other words, if the throttle limit is set to 5 and this setting is 15, then the user can only mistype
their password 5 times in a 15 minute window.  If they exceed that, then their account/IP address will be blocked.

The **activity suspension time** determines how long a user/IP address is blocked after the throttle is
triggered.  In other words, if the user is blocked due to failed login attempts and this setting is 30, the
user will need to wait 30 minutes before they are allowed to try logging in again.

## Clearing Suspensions

If you need to clear a suspension for any reason, you can do so by visiting **Backend** > **Settings** > **Security** >
**Suspensions**.  Find the record that needs to be cleared, check the box to the left of it, and click the delete button
at the top of the screen.