This tutorial covers the steps required to add new SaaS integration documentation.

Step 1: Create a new branch

If you haven’t already, create a new branch off of the Stitch Docs master branch. Name it something descriptive to ensure it’s easy to find and tell what you’re working on.

Note: Do not fork the Stitch Docs repo and create a branch. Please clone the repo locally, and then create a new branch.

Step 2: Set up your folders

Each SaaS integration has its own folder in two places:

• _saas-integrations, which is where the main documentation (setup, replication, etc.) is kept
• _integration-schemas, which is where the documentation for tables included in the integration are kept

Step 2.1: In the _saas-integrations folder

The main documentation for SaaS integrations is kept in the _saas-integrations folder. Navigate to this folder, and then:

1. If there isn’t already a folder for that integration, create one. The name of the folder should be the same as the name of the integration. For example: GitHub would have a folder named github, Facebook Ads would have facebook-ads, etc.
2. In the integration’s folder, create a folder that corresponds to the version of the integration. For example: If the version is 1, the folder would be named v1.

The final file structure should be: _saas-integrations/<integration-name>/v<version>

For example: _saas-integrations/facebook-ads/v1

Step 2.2: In the _integration-schemas folder

Navigate to the _integration-schemas folder, and repeat the steps in the previous section.

Step 3: Save a copy of the SaaS base template

1. Locate the SaaS integration template, at /_templates/integrations/saas/saas-base.md.

2. Save a copy of the template into the integration’s folder in _saas-integrations, using this naming convention: [integration-name]-v[version].md.

   For example: facebook-ads-v1.md would be saved in the _saas-integrations/facebook-ads/v1 folder.

Step 4: Fill out the template

Fill out the copy of the template you created in Step 4, using the SaaS Integration Frontmatter Reference as a guide.

At a minimum, integrations must have:

1. Completed integration details (name, display_name, repo-url, this-version, etc.)
2. Completed Stitch attributes (frequency, historical, certified, etc.)
3. Setup requirements, if applicable
4. Setup instructions

Step 4.1: Find/replace

1. In the copy of the template, do a case-sensitive find/replace on SAAS-INTEGRATION, replacing it with the display name of the integration. The display name is how the provider spells/displays their name.

   For example: If the name of the integration is Facebook Ads or Close.io, you would find/replace SAAS-INTEGRATION with Facebook Ads or Close.io.

2. Next, perform a case-sensitive find/replace on saas-integration, replacing it with the key name of the integration.

   This attribute acts as a key for the integration, and is a lowercase version of the display name. It cannot contain anything but alphanumerical characters and dashes (-).

   For example: If the display name of the integration is Facebook Ads or Close.io, you would find/replace saas-integration with facebook-ads and closeio.

Step 4.2: Define the integration's details

In the Integration Details section of the template, define the integration’s details. Refer to the Integration Details section of the SaaS Frontmatter reference for more info and examples on what these parameters do.

Step 4.3: Define the integration's Stitch details

In the Stitch Details section of the template, define the integration’s Stitch details. Refer to the Stitch Details section of the SaaS Frontmatter reference for more info and examples on what these parameters do.

Step 4.4: Add the setup requirements and instructions

1. In the SETUP REQUIREMENTS section of the template is a list named requirements-list. In this section, add the prerequisites for setting up the integration in Stitch.

   Each prerequisite should be its own item. Refer to the Setup instructions: Requirements of the SaaS Frontmatter reference for examples.

2. In the SETUP STEPS section of the template is a list named setup-steps. In this section, add the steps for setting up the integration in Stitch.

   Each action should be its own step. Refer to the Content sections of the SaaS Frontmatter reference for examples.

Step 5: Refer to your release checklist

If you’re working on a release, refer to the release checklist you’re using to wrap up the remaining steps for launch:

• New SaaS integration release checklist
• New SaaS version release checklist
• All release checklists

Last updated: 28 July 2021