Skip to content

Commit

Permalink
update web app docs
Browse files Browse the repository at this point in the history
  • Loading branch information
aeluce committed Dec 23, 2024
1 parent aa508b4 commit 59f07d9
Show file tree
Hide file tree
Showing 3 changed files with 59 additions and 44 deletions.
103 changes: 59 additions & 44 deletions site/docs/concepts/web-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ With the Flow web app, you can perform most common workflows, including:
* Viewing users and permissions.
* Granting permissions to other users.
* Authenticating with the flowctl CLI.
* Manage billing details.
* Managing billing details.

Some advanced workflows, like transforming data with **derivations**, aren't fully available in the web app.

Expand All @@ -31,7 +31,7 @@ it provides a quicker and easier path to create captures and materializations. Y

## Signing in

You use a Google, Microsoft, or GitHub account to sign into Flow.
You use a Google, Microsoft, or GitHub account to sign into Flow. Alternatively, [contact us](https://estuary.dev/contact-us) about Single Sign-On (SSO) options.

![](<./webapp-images/login-screen.png>)

Expand All @@ -54,14 +54,14 @@ import Mermaid from '@theme/Mermaid';
`}/>

While you may choose to [use the tabs in this sequence](../guides/create-dataflow.md), it's not necessary.
All Flow entities exist individually, outside of the context of complete Data Flow.
All Flow entities exist individually, outside of the context of a complete Data Flow.
You can use the different pages in the web app to monitor and manage your items in a number of other ways, as described below.

## Captures page

The **Captures** page shows you a table of existing Flow [captures](./captures.md) to which you have [access](../reference/authentication.md).
The **New Capture** button is also visible.
You use the table to monitor your captures.
You can use the table to monitor your captures.

![](<./webapp-images/capture-page.png>)

Expand Down Expand Up @@ -93,12 +93,11 @@ you can find it by filtering for `acmeCo*source-postgres`.

**8:** Capture [statistics](./advanced/logs-stats.md#statistics). The **Data Written** column shows the total amount of data, in bytes and in [documents](./collections.md#documents),
that the capture has written to its associated collections within a configurable time interval.
Click the time interval in the header to select from **Today**, **Yesterday**, **This Week**, **Last Week**, **This Month**, or **Last Month**.
Note that the time intervals are in UTC.
Click the time interval in the header to select from **Today**, **Yesterday**, **This Week**, **Last Week**, **This Month**, **Last Month**, or **All Time**.

**9:** Associated collections. The **Writes to** column shows all the collections to which the capture writes data. For captures with a large number of collections, there is a chip stating how many collections are hidden. Clicking on this will all you to hover over this column and scroll to view the full list. These are also links to the details page of the collection.
**9:** Associated collections. The **Writes to** column shows all the collections to which the capture writes data. For captures with a large number of collections, there is a chip stating how many collections are hidden. Clicking on this will allow you to hover over this column and scroll to view the full list. These also link to the details page of the collection.

**10:** Publish time. Hover over this value to see the exact UTC time the capture was last published.
**10:** Publish time. Hover over this value to see the exact time the capture was last published.

**11:** Options. Click to open the menu to **Edit Specification**.

Expand All @@ -125,7 +124,8 @@ You can proceed to the materialization, or opt to exit to a different page of th

## Collections page

The **Collections** page shows a read-only table of [collections](./collections.md) to which you have access.
The **Collections** page shows a table of [collections](./collections.md) to which you have access. There is also a button to begin a new derivation, or transformation.

The table has nearly all of the same features as the **Captures** table, with several important distinctions
that are called out in the image below.

Expand Down Expand Up @@ -155,17 +155,16 @@ In the event that the server cannot be reached, the indicator will show "Unknown

**6:** Collection [statistics](./advanced/logs-stats.md#statistics). The **Data Written** column shows the total amount of data, in bytes and in [documents](./collections.md#documents),
that has been written to each collection from its associated capture or derivation within a configurable time interval.
Click the time interval in the header to select from **Today**, **Yesterday**, **This Week**, **Last Week**, **This Month**, or **Last Month**.
Note that the time intervals are in UTC.
Click the time interval in the header to select from **Today**, **Yesterday**, **This Week**, **Last Week**, **This Month**, **Last Month**, or **All Time**.

**7:** Publish time. Hover over this value to see the exact UTC time the collection was last published.
**7:** Publish time. Hover over this value to see the exact time the collection was last published.

## Materializations page

The **Materializations** page shows you a table of existing Flow [materializations](./materialization.md) to which you have [access](../reference/authentication.md).
The **New Materialization** button is also visible.

You use the table to monitor your materializations. It's nearly identical to the table on the [Captures page](#captures-page), with a few exceptions.
You can use the table to monitor your materializations. It's nearly identical to the table on the [Captures page](#captures-page), with a few exceptions.

![](<./webapp-images/materialization-page.png>)

Expand Down Expand Up @@ -194,12 +193,11 @@ you can find it by filtering for `acmeCo*mysql`.

**7:** Materialization [statistics](./advanced/logs-stats.md#statistics). The **Data Read** column shows the total amount of data, in bytes and in [documents](./collections.md#documents),
that the materialization has read from its associated collections within a configurable time interval.
Click the time interval in the header to select from **Today**, **Yesterday**, **This Week**, **Last Week**, **This Month**, or **Last Month**.
Note that the time intervals are in UTC.
Click the time interval in the header to select from **Today**, **Yesterday**, **This Week**, **Last Week**, **This Month**, **Last Month**, or **All Time**.

**8:** Associated collections. The **Reads from** column shows all the collections from which the materialization reads data. For materializations with a large number of collections, there is a chip stating how many collections are hidden. Clicking on this will all you to hover over this column and scroll to view the full list. These are also links to the details page of the collection.
**8:** Associated collections. The **Reads from** column shows all the collections from which the materialization reads data. For materializations with a large number of collections, there is a chip stating how many collections are hidden. Clicking on this will allow you to hover over this column and scroll to view the full list. These also link to the details page of the collection.

**9:** Publish time. Hover over this value to see the exact UTC time the materialization was last published.
**9:** Publish time. Hover over this value to see the exact time the materialization was last published.

**10:** Options. Click to open the menu to **Edit Specification**.

Expand Down Expand Up @@ -239,15 +237,15 @@ When you click on the **name** of a capture on the [captures page](#captures-pag

**1:** The full name of the capture.

**2:** Capture [statistics](./advanced/logs-stats.md#statistics). The **Usage** section displays the total amount of data, in bytes and in [documents](./collections.md#documents) written by the capture, per hour. The number of hours being displayed in the chart can be changed by clicking the time interval in the header to select from **6 hours**, **12 hours**, **24 hours**.
**2:** Capture [statistics](./advanced/logs-stats.md#statistics). The **Usage** section displays the total amount of data, in bytes and in [documents](./collections.md#documents) written by the capture, per hour. The number of hours being displayed in the chart can be changed by clicking the time interval in the header to select from **6 hours**, **12 hours**, **24 hours**, **48 hours**, or **30 days**.

**3:** The **Details** section shows different pieces of information about the capture. When it was last updated, when it was created, the connector being used, and the collections to which the capture writes data.
**3:** The **Details** section shows information about the capture: when it was last updated, when it was created, the connector being used, and the collections to which the capture writes data.

**4:** Detailed tooltip. You can hover over a section in the graph to see the specific data of that hour.

**5:** The most recent hour. This will automatically update every 15 seconds with the most recent data and docs.

**6:** Associated collections. Shows all the collections to which the capture writes data and when clicked will take you to the collection's [detail page](#collection-details-page)
**6:** Associated collections. Shows all the collections to which the capture writes data and when clicked will take you to the collection's [detail page](#collection-details-page).

**7:** The **Shard Information** section shows the full identifier of the shard(s) that back your capture. If there's an error, you'll see an alert identifying the failing shard(s). Use the drop-down to open an expanded view of the failed shard's logs.

Expand All @@ -266,15 +264,15 @@ When you click on the **name** of a collection on the [collections page](#collec

**1:** The full name of the collection.

**2:** Collection [statistics](./advanced/logs-stats.md#statistics). The **Usage** section shows the total amount of data, in bytes and in [documents](./collections.md#documents) passing through a collection, per hour. The number of hours being displayed in the chart can be changed by clicking the time interval in the header to select from **6 hours**, **12 hours**, **24 hours**.
**2:** Collection [statistics](./advanced/logs-stats.md#statistics). The **Usage** section shows the total amount of data, in bytes and in [documents](./collections.md#documents) passing through a collection, per hour. The number of hours being displayed in the chart can be changed by clicking the time interval in the header to select from **6 hours**, **12 hours**, **24 hours**, **48 hours**, or **30 days**.

**3:** The **Details** section shows different pieces of information about the collection. When it was last updated, when it was created, and the associated collections (if any).
**3:** The **Details** section shows information about the collection: when it was last updated, when it was created, and the associated collections (if any).

**4:** Detailed tooltip. You can hover over a section in the graph to see the specific data of that hour.

**5:** The most recent hour. This will automatically update every 15 seconds with the most recent data and docs.

**6:** Associated collections. Shows all the collections to which the capture writes data and when clicked will take you to the collection's [detail page](#collection-details-page)
**6:** Associated collections. Shows source collections that this collection reads from. Click to go to the collection's [detail page](#collection-details-page).

**7:** The **Shard Information** section (for derivations) shows the full identifier of the shard(s) that back your derivation. If there's an error, you'll see an alert identifying the failing shard(s). Use the drop-down to open an expanded view of the failed shard's logs.

Expand All @@ -289,7 +287,7 @@ Documents are organized by their collection key value. Click a key from the list
**2:** The collection's [schema](./schemas.md) displayed in a read only table. The table columns can be sorted to more easily find what you need.

:::tip
If you need to modify a collection, edit the [capture](#editing-captures) that it came from.
If you need to modify a collection, edit the [capture](#editing-captures) or [derivation](./derivations.md) that provides its data.
:::

## Materialization Details Page
Expand All @@ -303,15 +301,15 @@ When you click on the **name** of a materialization on the [materializations pag

**1:** The full name of the materialization.

**2:** Materialization [statistics](./advanced/logs-stats.md#statistics). The **Usage** section shows the total amount of data, in bytes and in [documents](./collections.md#documents) read by a materialization, per hour. The number of hours being displayed in the chart can be changed by clicking the time interval in the header to select from **6 hours**, **12 hours**, **24 hours**.
**2:** Materialization [statistics](./advanced/logs-stats.md#statistics). The **Usage** section shows the total amount of data, in bytes and in [documents](./collections.md#documents) read by a materialization, per hour. The number of hours being displayed in the chart can be changed by clicking the time interval in the header to select from **6 hours**, **12 hours**, **24 hours**, **48 hours**, or **30 days**.

**3:** The **Details** section shows different pieces of information about the materialization. When it was last updated, when it was created, and the associated collections.
**3:** The **Details** section shows information about the materialization: when it was last updated, when it was created, and the associated collections.

**4:** Detailed tooltip. You can hover over a section in the graph to see the specific data of that hour.

**5:** The most recent hour. This will automatically update every 15 seconds with the most recent data and docs.

**6:** Associated collections. Shows all the collections to which the capture writes data and when clicked will take you to the collection's [detail page](#collection-details-page)
**6:** Associated collections. Shows all the collections that provide data to this materialization. Click to go to the collection's [detail page](#collection-details-page).

**7:** The **Shard Information** section shows the full identifier of the shard(s) that back your materialization. If there's an error, you'll see an alert identifying the failing shard(s). Use the drop-down to open an expanded view of the failed shard's logs.

Expand All @@ -323,46 +321,63 @@ In the **Spec** tab, you can view the specification of the materialization itsel
## Admin page

On the **Admin** page, you can view users' access grants, your organization's cloud storage locations, and a complete list of connectors.
You can also get an access token to authenticate with flowctl and update your cookie preferences.
You can also get an access token to authenticate with flowctl and manage billing information.

#### Users
### Account Access

The **Users** tab shows you all provisioned access grants on objects to which you also have access.
The **Account Access** tab shows you all provisioned access grants on objects to which you also have access.
Both users and catalog prefixes can receive access grants.
These are split up into two tables called **Users** and **Prefixes**.
These are split up into two tables called **Organization Membership** and **Data Sharing**.
Each access grant has its own row, so a given user or prefix may have multiple rows.

For example, if you had read access to `foo/` and write access to `bar/`, you'd have a separate table row in the **Users** table for each of these capabilities.
For example, if you had read access to `foo/` and write access to `bar/`, you'd have a separate table row in the **Organization Membership** table for each of these capabilities.
If users Alice, Bob, and Carol each had write access on `foo/`, you'd see three more table rows representing these access grants.

Taking this a step further, the prefix `foo/` could have read access to `buz/`. You'd see this in the **Prefixes** table,
Taking this a step further, the prefix `foo/` could have read access to `buz/`. You'd see this in the **Data Sharing** table,
and it'd signify that everyone who has access to `foo/` also inherits read access to `buz/`.

Use the search boxes to filter by username, prefix, or object.

You can manage access by generating new user invitations, granting data sharing access, or selecting users or prefixes to revoke access.

![](<./webapp-images/access-grant-invitation.png>)

Generating a new invitation will create a URL with a grant token parameter. This token will allow access based on the prefix, capability, and type you select. Copy the URL and share it with its intended recipient to invite them to your organization.

[Learn more about capabilities and access.](../reference/authentication.md)

#### Storage Mappings
### Settings

The **Settings** tab includes additional configuration, such as organization notifications and storage mappings.

#### Organization Notifications

The **Storage Mappings** tab includes a table of the cloud storage locations that back your Flow collections.
Here, you are able to configure which email address(es) will receive notifications related to your organization or prefix.

#### Cloud Storage

This section provides a table of the cloud storage locations that back your Flow collections.
You're able to view the table if you're an admin.

Each top-level Flow [prefix](./catalogs.md#namespace) is backed by one or more cloud storage bucket that you own.
You typically have just one prefix: your organization name, which you provided when configuring your Flow organizational account.
If you're a trial user, your prefix is `trial/`, and this tab isn't applicable to you;
your data is stored temporarily in Estuary's cloud storage bucket for your trial period.
If you're a trial user, your data is stored temporarily in Estuary's cloud storage bucket for your trial period.

[Learn more about storage mappings.](./storage-mappings.md)

#### Connectors
### Billing

The **Connectors** tab offers a complete view of all connectors that are currently available through the web application, including both capture and materialization connectors.
If a connector you need is missing, you can request it.
The **Billing** tab allows you to view and manage information related to past usage, the current billing cycle, and payment methods.

#### CLI-API
Your usage is broken down by the amount of data processed and number of task hours. View usage trends across previous months in the **Usage by Month** chart and preview your bill based on usage for the current month. If you are on the free tier (up to 2 connectors and 10 GB per month), you will still be able to preview your bill breakdown, and will have a "Free tier credit" deduction. To help estimate your bill, also see the [Pricing Calculator](https://estuary.dev/pricing/#pricing-calculator).

The **CLI-API** tab provides the access token required to [authenticate with flowctl](../reference/authentication.md#authenticating-flow-using-the-cli).
To pay your bill, add a payment method to your account. You can choose to pay via card or bank account. You will not be charged until you exceed the free tier's limits.

### Connectors

The **Connectors** tab offers a complete view of all connectors that are currently available through the web application, including both capture and materialization connectors.
If a connector you need is missing, you can [request it](https://github.com/estuary/connectors/issues/new/choose).

#### Cookie Preferences
### CLI-API

You use the **Cookie Preferences** tab to view and modify cookie settings.
The **CLI-API** tab provides the access token required to [authenticate with flowctl](../reference/authentication.md#authenticating-flow-using-the-cli). You can also revoke old tokens.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified site/docs/concepts/webapp-images/login-screen.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 59f07d9

Please sign in to comment.