Onboard Teams

Introduction

Only available on DDN Advanced

In order to add subgraph collaborators, your project must be a DDN Advanced project.

Hasura DDN provides a concept of subgraph 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 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 enabled.

When the UX Team joins the project, you'll use the CLI to create a new subgraph for them, named ux and invite developers 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.

In a project directory, run the following:

ddn project subgraph create <subgraph-name>

Step 2. Invite collaborators

Follow the steps 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 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.

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.

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.

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

You can add a new native data connector 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 or commands or relationships which will then be available via your API.

Run this command and follow the prompts for your connector:

ddn connector init -i

Then, introspect your data source to generate configuration files:

ddn connector introspect <connector-name-from-init-step>

Finally, track all your resources:

ddn connector-link add-resources <connector-name-from-init-step>

Run your supergraph locally

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

ddn supergraph build local

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.

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.

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.

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

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.

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

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

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.