collaboration.txt

--- File: ../ddn-docs/docs/collaboration/invite.mdx ---

---
sidebar_position: 2
sidebar_label: Invite others & allow access
description: "Learn how to invite others to a project."
keywords:
  - hasura ddn
  - graphql api
  - quickstart
  - getting started
  - guide
  - collaborate
---

import Thumbnail from "@site/src/components/Thumbnail";
import Roles from "./_roles.mdx";
import Permissions from "./_permissions.mdx";

# Invite Collaborators

## Introduction

Hasura DDN allows multiple users and teams to work together as collaborators on projects by assigning each user specific
roles and permissions.

You can [invite users](#invite-collaborators) to a project, or allow them to [request access](#request-access).

:::info Only available on DDN Base and higher

In order to add collaborators, your project must either be a
[DDN Base or DDN Advanced project](https://hasura.io/pricing/ddn).

:::

## Available roles {#roles}

<Roles />

\* Subgraph roles are only available on [DDN Advanced projects](https://hasura.io/pricing/ddn).

The following are the detailed permissions for the above roles:

<Permissions />

\* Only available on [DDN Advanced projects](https://hasura.io/pricing/ddn).

## How to invite collaborators {#invite-collaborators}

### Step 1. Navigate to the Collaborators section

Open your project's console at [https://console.hasura.io](https://console.hasura.io) and select it from the list of
available projects. Once the project is open, click `Settings` in the bottom-left corner and then select `Collaborators`
from the `Project Settings` menu:

<Thumbnail src="/img/ci-cd/0.0.1_console_invite-collaborator.png" alt="Invite a collaborator" width="1000" />

### Step 2. Enter information

Click the `+ Invite Collaborator` button in the top-right corner of the `Collaborators` section and enter the
collaborator's email address, select the access level you'd like to assign them, and click `Invite`.

<Thumbnail src="/img/ci-cd/0.0.1_console_assign-collaborator-role.png" alt="Invite a collaborator" width="1000" />

<br />
:::info Granular Access (Subgraph Collaborators) Only available on DDN Advanced

In order to add subgraph collaborators, your project must be a [DDN Advanced project](https://hasura.io/pricing/ddn).

:::

The invitee will receive an email with a link allowing them to accept the invite and join the project.

## How to accept a collaboration invite {#accept-invite}

### Step 1. Click the link in your email

From your email, click the `View invitation` button. This will send you to
[https://console.hasura.io](https://console.hasura.io) where you can accept it and then explore and contribute to the
project according your [role](#roles).

### Step 2. Explore the project

From your new project, you can explore the console by:

- [Running queries](/graphql-api/queries/) from the GraphiQL explorer.
- Visualizing the supergraph with the Explorer tab.
- Seeing other collaborators present in the project.

### Step 3. Learn how to develop locally

The owner of the project most likely has a Git repository with the project's contents available on a service such as
GitHub. To run the supergraph locally, and make contributions to the deployed supergraph,
[pick up here](/quickstart.mdx) in our getting started docs.

## Allow users to request access {#request-access}

You can adjust your project's settings to allow users to request access when navigating to your project's URL. To do
this, click the `Share` button in the top navigation of your project and select `Request Access`.

<Thumbnail
  src="/img/get-started/console_read-only.png"
  alt="Allow users to request access to your project"
  width="1000"
/>

Each time a user requests access, you'll be able to approve or deny the request from this modal.

## More information

See more about Hasura DDN plans and pricing [here](/reference/pricing.mdx).



--- File: ../ddn-docs/docs/collaboration/overview.mdx ---

---
sidebar_position: 1
sidebar_label: Overview
description:
  "Hasura DDN allows multiple users and teams to work together as collaborators on projects by assigning each user
  specific roles and permissions."
keywords:
  - hasura ddn
  - graphql api
hide_table_of_contents: true
---

import { OverviewTopSectionIconNoVideo } from "@site/src/components/OverviewTopSectionIconNoVideo";
import { OverviewPlainCard } from "@site/src/components/OverviewPlainCard";
import Icon from "@site/static/icons/features/collaborators.svg";

# Collaboration

## Introduction

Hasura DDN allows multiple users and teams to work together as collaborators on projects by assigning each user specific
roles and permissions.

## Find out more

- [Invite users](/collaboration/invite.mdx)
- [Onboard teams](/collaboration/federation.mdx)
- [Best practices](/collaboration/best-practices.mdx)
- [Comment on metadata](/collaboration/comment.mdx)



--- File: ../ddn-docs/docs/collaboration/index.mdx ---

---
sidebar_position: 1
sidebar_label: Collaborate
description: "Learn how to get collaborate with others on a DDN project."
keywords:
  - hasura ddn
  - graphql api
  - quickstart
  - getting started
  - guide
  - collaborate
---

# Collaborate

## Introduction

In this section, you'll find everything you need to effectively collaborate with your and other teams when developing a
Hasura DDN project. After inviting others to your project and following the best practices found in this section you'll
be able to quickly and iteratively build out your API, all while knowing your downstream consumers enjoy uninterrupted
service.

## Next steps

- [Learn how to invite others](/collaboration/invite.mdx) to a project
- Read about the [best practices](/collaboration/best-practices.mdx) for developing as a team



--- File: ../ddn-docs/docs/collaboration/federation.mdx ---

---
sidebar_position: 3
sidebar_label: Onboard Teams
description: "Learn how to invite others to a collaborate on a subgraph."
keywords:
  - hasura ddn
  - graphql api
  - quickstart
  - getting started
  - guide
  - collaborate
  - federation
  - teams
  - onboard
toc_max_heading_level: 4
---

import Thumbnail from "@site/src/components/Thumbnail";

# Onboard Teams

## Introduction

:::info Only available on DDN Advanced

In order to add subgraph collaborators, your project must be a [DDN Advanced project](https://hasura.io/pricing/ddn).

:::

Hasura DDN provides a concept of [subgraph](/project-configuration/subgraphs/#introduction) which allows you to manage
your Hasura metadata more efficiently by allowing it to be split based on ownership. Hasura DDN allows multiple users
and teams to [work together as collaborators](/collaboration/invite.mdx) on subgraphs by assigning each user specific
roles and permissions.

In this guide, you'll learn how to onboard multiple teams into a collaborative project using a supergraph. This approach
allows for efficient collaboration making it easier to manage and scale your project as more teams are added.

## Collaboration Scenario

Let's imagine an example with two teams: The Fulfillment Team and the UX team, and you as the supergraph admin. The
Fulfillment Team is responsible for products and orders, whereas the UX handles everything related to users.

| Team | Name        | Responsibilities |
| ---- | ----------- | ---------------- |
| 1    | Fulfillment | Products, Orders |
| 2    | UX          | Users            |

The Fulfillment team is already using Hasura DDN and has created a supergraph project with their Products and Orders
[models](/supergraph-modeling/models.mdx) enabled.

When the UX Team joins the project, you'll use the [CLI](/cli/installation.mdx) to create a new subgraph for them, named
`ux` and [invite developers](/collaboration/invite.mdx) from the team to collaborate on this subgraph via the console.

The UX team will start by initializing a new local DDN project with their own new version control repository and set the
project context to match the existing project set up by the Fulfillment team.

The UX team will then set up their data connector in their subgraph, track the `Users` model, deploy the connector, then
create and apply a new subgraph build which will be added to the supergraph.

The UX team can also add relationships and permissions in their that integrate with the Fulfillment team's existing
subgraphs too.

This process can be easily repeated for any additional teams, allowing each team to contribute their models and features
while maintaining a cohesive project structure with a distributed workflow.

## As a supergraph admin, onboard collaborators to a new subgraph

### Step 1. Create a new subgraph

Using the CLI, as a supergraph admin, create a new subgraph on your DDN project.

```bash title="In a project directory, run the following:"
ddn project subgraph create <subgraph-name>
```

### Step 2. Invite collaborators

[Follow the steps ](/collaboration/invite.mdx#invite-collaborators) to invite subgraph collaborators. Take care to
select the appropriate role — either **Admin** or **Developer** — for each subgraph team member.

## As a subgraph developer, collaborate on the new subgraph

### Step 1. Accept the invite

[Reference these docs](/collaboration/invite.mdx#accept-invite) to accept an invitation and explore the existing
supergraph.

### Step 2. Create a new local project, supergraph and subgraph

To get started with local development on your new subgraph, initialize a new local supergraph.

```bash title="Run the following in a new directory for your project:"
ddn supergraph init . --create-subgraph <subgraph-name>
```

By providing the `--create-subgraph` flag, you'll also create a new subgraph in your local project and set it in
context. Importantly, use the same name as the subgraph you were invited to collaborate on. At this point the local
project does not know about the project on Hasura DDN.

:::info Subgraph prefixing

It's a good idea at this stage to determine whether you will need a prefix for your subgraph. This is useful if there is
the possibility of name clashes between subgraphs. [Read more here](/project-configuration/subgraphs.mdx).

:::

### Step 3. Add a data connector, track your resources, make changes to your metadata

You can add a new [native data connector](/data-sources/overview.mdx) to your subgraph using the CLI. Data connectors
are what allow you to integrate various data sources to your API.

In the following sequence, we'll do a few things:

- Initialize a new data connector, which will allow you to connect a data source to your API.
- Introspect the source to create a configuration that your connector understands and can use to generate Hasura
  metadata.
- Track all the entities in your data source as either [models](/supergraph-modeling/models.mdx) or
  [commands](/supergraph-modeling/commands.mdx) or [relationships](/supergraph-modeling/relationships.mdx) which will
  then be available via your API.

```bash title="Run this command and follow the prompts for your connector:"
ddn connector init -i
```

```bash title="Then, introspect your data source to generate configuration files:"
ddn connector introspect <connector-name-from-init-step>
```

```bash title="Finally, track all your resources:"
ddn connector-link add-resources <connector-name-from-init-step>
```

:::info Run your supergraph locally

At this point, you can run the following commands to build, run and iterate on your supergraph locally.

```bash
ddn supergraph build local
```

```bash
ddn run docker-start
```

**Note: You'll only see your subgraph locally. This is by design as your local supergraph only contains _your_ subgraph.
You are free to iterate on it and make changes without causing disruption to other subgraphs or downstream consumers. To
test your subgraph within the project's supergraph, follow the next steps.**

:::

### Step 4. Map your local project to the project on Hasura DDN

Run the following command to specify that you're initializing with an existing project on Hasura DDN. This will set the
project context for you locally.

```bash
ddn project init --with-project <project-name>
```

### Step 5. Create a subgraph build on Hasura DDN

Next, you can create a build of your subgraph in the project on Hasura DDN.

```bash title="Create a new subgraph build:"
ddn subgraph build create
```

This will also create a build of your data connectors on Hasura DDN. Subgraph builds do not have an API and you cannot
query them in isolation.

### Step 6. Create a supergraph build on Hasura DDN

You can test your changes by creating a new supergraph build with your latest subgraph build.

```bash title="Create a supergraph build using your subgraph build:"
ddn supergraph build create --subgraph-version <subgraph-name:build-version> --base-supergraph-version <supergraph-build-id>
```

Please note the `Build Version` from the output of this command. We will need it in the next step. You can now query and
test your changes in the context of the whole supergraph on Hasura DDN.

### Step 7. Deploy your subgraph changes

:::warning Permissions required to apply a build

Only subgraph admins or supergraph admins can apply a subgraph build. If you are not a supergraph admin, you can ask one
to apply the build for you.

:::

When you're satisfied with the state of your subgraph after testing, you can apply the build to make it the available
subgraph build at the default project endpoint.

```bash
$ ddn subgraph build apply <subgraph-build-version>
```

Or, to apply the whole supergraph build which you made in the previous step:

```bash title="Using the build version returned from the previous step:"
ddn supergraph build apply <supergraph-build-version>
```

### Step 8. Version control

It's a good idea to create a new git repository for this supergraph containing the new isolated subgraph.

You can then also add new collaborators to the repository who are also invited to collaborate on the subgraph.

## What did this do?

- A supergraph admin has created a new subgraph and invited a new team to collaborate on it.
- The new team has onboarded by initializing a new local supergraph project with the same new subgraph name, added a
  data connector and made changes locally.
- The new team mapped the existing DDN supergraph project to their local supergraph project.
- The new team created a new build of their subgraph with data connector on Hasura DDN.
- The new team created a new supergraph build using the new subgraph build on Hasura DDN.
- The new team tested their changes in the context of the whole supergraph on Hasura DDN.
- The new team or supergraph admin applied their subgraph changes to make it available via the API.

The new team has now been onboarded to your project in their own subgraph, forming a distinct governance and ownership
boundary between the supergraph and its subgraphs.



--- File: ../ddn-docs/docs/collaboration/best-practices.mdx ---

---
sidebar_position: 4
sidebar_label: Best Practices
description: "Learn how to collaborate with others on a project."
keywords:
  - hasura ddn
  - graphql api
  - quickstart
  - getting started
  - guide
  - collaborate
---

# Best Practices for Collaboration

## Introduction

Hasura DDN is engineered to streamline collaboration within and across teams in your organization by directly addressing
the inefficiencies with traditional development workflows. When bringing different services together in one API using
traditional methods, known as "federation", the complexity of coordinating API changes frequently leads to bottlenecks,
risking disruptions to internal customers and, more critically, to end users. Traditional methods, such as manual
deployments or siloed development practices, often result in delayed feedback and increased time to market, making it
challenging to maintain agility and responsiveness.

By contrast, Hasura DDN leverages near-instant feedback loops facilitated by local development, streamlined data-source
composability, and an optimized CI/CD workflow. This approach not only mitigates the risks associated with conventional
workflows but also empowers your team to deliver updates with unprecedented speed and reliability.

## Recommended deployment workflow

In the following sections, we will outline a recommended deployment workflow for Hasura DDN. This workflow is designed
to ensure that your team can iterate quickly and confidently, while also minimizing the risk of disruptions to deployed
projects.

:::tip Version control is necessary

While it's assumed you've created a Git repository — or are using some other form of version control — for the steps
below to be reproducible, you should initialize a Git repository and commit your project's code to a remote source, such
as GitHub.

:::

### Develop

Hasura allows for local development to independently and iteratively add functionality to your API. This allows each
member on the team to have their own development environment for testing and iteration; this also protects any deployed
projects from disruptions.

This means that each developer has their own development environment to which they can iteratively — and confidently —
test their changes. As these changes all exist in their metadata, they can then commit these to version control and use
familiar git workflows to test and deploy their changes to a deployed project.

A common scenario would be a user updating the permissions for a model. In this case, they would write their permissions
in metadata, test them locally using the Hasura DDN console, and then create a new build on Hasura DDN:

```bash
ddn supergraph build create --supergraph ./supergraph.cloud.yaml
```

:::tip The CLI will respond with a build ID

This ID — and the accompanying URL — can be easily be shared with teammates for easy testing and review.

:::

Then, they can commit the changes:

```bash
git add .
git commit -m "Add ModelPermissions to Users model"
git push
```

### Review

With the changes above pushed to the remote repository, a pull request would then be opened. This would allow other team
members to checkout the changes and run them from the hosted project's console.

### Deploy

Once the PR has been approved and merged, the build can then be applied to the project's endpoint:

```bash
ddn supergraph build apply <supergraph-build-version>
```

Then, the cycle would begin again for further iteration.

## Automate deployments

While the steps above can be performed manually, automation is key to ensuring that deployments are consistent and
reliable. The Hasura CLI can be used to automate deployments to Hasura DDN, and GitHub Actions can be used to automate
the process of running the Hasura CLI.

You can drop this [GitHub Action](https://github.com/marketplace/actions/ddn-deployment) into your repository and
configure it to run on merges to specific branches to automate the deployment process 🎉

This Action will take care of not only creating builds for each change to the PR's branch, but also in generating
preview links for easy review from teammates.



--- File: ../ddn-docs/docs/collaboration/_permissions.mdx ---

| Permissions                                                         | Owner | Admin | Read Only | Subgraph<br/> Admin \* | Subgraph<br/> Developer \* |
| ------------------------------------------------------------------- | ----- | ----- | --------- | ---------------------- | -------------------------- |
| View Supergraph Explorer                                            | ✅    | ✅    | ✅        | ✅                     | ✅                         |
| Make GraphQL API requests                                           | ✅    | ✅    | ✅        | ✅                     | ✅                         |
| View project insights                                               | ✅    | ✅    | ✅        | ✅                     | ✅                         |
| Create supergraph builds<br/> - using all subgraphs' metadata       | ✅    | ✅    | ❌        | ❌                     | ❌                         |
| Create supergraph builds<br/> - using single subgraph's metadata \* | ✅    | ✅    | ❌        | ✅                     | ✅                         |
| Apply supergraph builds to project endpoint                         | ✅    | ✅    | ❌        | ❌                     | ❌                         |
| Create subgraph builds \*                                           | ✅    | ✅    | ❌        | ✅                     | ✅                         |
| Apply subgraph builds to project endpoint \*                        | ✅    | ✅    | ❌        | ✅                     | ❌                         |
| Admin permissions on all subgraphs                                  | ✅    | ✅    | ❌        | ❌                     | ❌                         |
| Create / Delete subgraphs                                           | ✅    | ✅    | ❌        | ❌                     | ❌                         |
| Add / Remove collaborators                                          | ✅    | ✅    | ❌        | ❌                     | ❌                         |
| Manage project plans and billing                                    | ✅    | ✅    | ❌        | ❌                     | ❌                         |
| Delete project                                                      | ✅    | ❌    | ❌        | ❌                     | ❌                         |



--- File: ../ddn-docs/docs/collaboration/_roles.mdx ---

| Role                      | Abilities                                                                                            |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Owner**                 | All Project abilities including deletion. At this time, project ownership is not transferable.       |
| **Admin**                 | Same as a Project Owner, excluding deletion of the project.                                          |
| **Read Only**             | Only explore and visualize the supergraph.                                                           |
| **Subgraph Admin** \*     | All subgraph development-related abilities: create subgraph build, apply subgraph build to endpoint. |
| **Subgraph Developer** \* | Same as a subgraph admin, excluding the ability to apply subgraph build to endpoint.                 |



--- File: ../ddn-docs/docs/collaboration/comment.mdx ---

---
sidebar_position: 4
sidebar_label: Comment on Metadata
description: "Collaborate with your peers by commenting on your Supergraph Metadata"
keywords:
  - hasura ddn
  - graphql api
  - quickstart
  - getting started
  - guide
  - collaborate
  - comment
---

import Thumbnail from "@site/src/components/Thumbnail";

# Commenting on Metadata

## Introduction

Hasura DDN provides a commenting feature that allows your API producers and consumers to start conversations directly on
the API metadata. This feature enhances collaboration by closing the feedback loop and helps teams communicate more
effectively about their API design and implementation.

:::tip Getting Access

This feature is currently in limited access and only available for Hasura Cloud projects. To get access, please fill out
this [form](https://forms.gle/tudE2jzD7get5iJF7).

:::

## How to comment

You can add comments on various objects from your metadata.

1. Navigate to any model page in your project via the `Explorer` tab.
2. Hover over the field or section you want to comment on.
3. Click on the comment icon that appears.

<Thumbnail src="/img/get-started/console_comment-create.png" alt="Hover over fields to add comments" width="1000" />

## Commenting areas

You can add comments to the following areas:

### Explorer Tab

#### Supergraph Page

<Thumbnail src="/img/get-started/comments_supergraph.png" alt="Hover over fields to add comments" width="800" />
<br />

#### Subgraph Page

<Thumbnail src="/img/get-started/comments_subgraph.png" alt="Hover over fields to add comments" width="500" />
<br />

#### Models --> General

- Description
- Signature
- GraphQL root fields

<Thumbnail src="/img/get-started/console_comment-general.png" alt="Comments on General" width="1000" />

#### Models --> Fields & Relationships

- Output fields
- Arguments
- Relationships

<Thumbnail
  src="/img/get-started/console_comment-fields-and-relationships.png"
  alt="Comments on Fields and Relationships"
  width="1000"
/>

#### Models --> Permissions

- Role
- Read
- Create
- Update
- Delete

<Thumbnail src="/img/get-started/console_comment-permissions.png" alt="Comments on Permissions" width="1000" />
<br />
<br />

### GraphiQL Tab

<Thumbnail src="/img/get-started/comments_graphql.png" alt="Alt text" />
<br />
<br />

### Insights Tab

<Thumbnail src="/img/get-started/comments_insights.png" alt="Comments on Permissions" width="1000" />

<br />
<br />

### Builds Tab

<Thumbnail src="/img/get-started/comments_builds.png" alt="Comments on Permissions" width="1000" />

## Notifications

To ensure effective collaboration, you can tag subgraph collaborators in your comments:

1. Type `@` in your comment.
2. Select the collaborator you want to notify.

Tagged collaborators will receive an email with your comments and a notification on the notification hub on the console,
keeping them informed of any discussions or questions.

The notification hub can be found in the top right corner of the console. On clicking the comments button, you will see
all the comments where you are tagged in one place. The messages will be grouped based on the underlying commenting
thread. You can click on a particular comment (deep linking) and go to the original thread on the console. You can also
delete notifications from that menu.

{/* <Thumbnail src="/img/get-started/comments_notification.png" alt="Alt text" width="100" height="100" /> */}
![Alt text](/img/get-started/comments_notification.png)

<br />
<br />

:::info Invite collaborators

You can learn how to invite collaborators [here](/collaboration/invite.mdx).

:::

## Limitations

The feature is in early access and has known limitations, which are in our backlog. Let us know if you would like to
prioritize any specific functionality.

1. Notification Email on Resolving comments.
2. Ability to auto notify subgraph admin and developers.
3. History Tab for comments.
4. Figma Style (Canvas) Commenting.