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.

Workflow

Steps for supergraph admin

Step 1. Create a new subgraph

Using the CLI, 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.

Steps for subgraph collaborators

Step 1. Accept the invite

Reference these docs to accept an invitation and explore the existing supergraph.

Step 2. Create a new local project

To get started with local development on your subgraph, create a new local project.

Run the following in a new directory for your project:

ddn supergraph init .

With Hasura DDN, we understand that each team may have their own unique workflows and design patterns, so each team can create a new repository for their new project; there is no need for all subgraphs to live in the same repository as the existing supergraph.

In the next step, we'll map this local project to the existing cloud project.

Step 3. Set the project context

Using the CLI, set the project's context by passing its name to the following command.

Pass the cloud project's name of the existing supergraph:

ddn context set project <project-name>

Step 4. Create a new subgraph

You'll need to create a subgraph in your local metadata that matches the name of the subgraph created in the cloud project by your supergraph admin. This ensures proper mapping between the metadata you generate and what is eventually served by your cloud project.

Create a subgraph matching the name of the subgraph provisioned for you by the supergraph admin and add it to your supergraph's configuration file:

ddn subgraph init <subgraph-name> --dir <subgraph-name> --target-supergraph ./supergraph.yaml

Step 5. Add a data connector and track your models

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 and 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, 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-previous-step>

Finally, track all your resources:

ddn connector-link add-resources "*"

Run your supergraph locally

At this point, you can run the following command — with any adjustments made to the --env-file path — to start your supergraph and data connector:

ddn run docker-start

Note: You'll only see your subgraph available locally. This is because 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 6. Deploy the connector

You'll need to deploy the connector so its available in your cloud project.

Step 7. Validate your metadata

Next, you can validate your metadata by creating a build using the latest applied supergraph metadata.

Create a new subgraph build:

ddn subgraph build create

Step 8. Test your subgraph changes

And then 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-id> --base-supergraph-version <applied-supergraph-build-id>

Please note the Build Version from the output of this command. We will need it in the next step.

Step 9. Deploy your subgraph changes

When you're satisfied with the state of your supergraph after testing the subgraph changes, create a new supergraph build.

Using the build ID returned from the previous step:

ddn supergraph build apply <build-id>

To apply a build

$ ddn subgraph build apply <Build Version>

Only subgraph admins or supergraph admins can apply a subgraph build.