Skip to content

Integration templates: Frontmatter parameter reference

Jump to bottom
Erin Cochran edited this page Jun 1, 2018 · 2 revisions

This serves as a reference for the Frontmatter parameters found in integration templates:

Instructions for using the templates can be found here. (soon!)

Each template is grouped into sections to make parameters easier to find. These sections and the parameters they contain are described below.

Page and formatting

These parameters control the layout and formatting used on the page.

Parameter Description
title

The title of the page, typically the name of the integration.

Example values:

  • GitHub
  • Facebook Ads
permalink

The page’s permalink value, used to generate its final URL.

Must be one of the following:

  • /integrations/saas/{integration-name}
  • /integrations/databases/{integration-name}
  • /integrations/webhooks/{integration-name}
tags

The applicable tag for the doc. Do not change the value in this field.

Must be one of the following:

  • [saas_integrations]
  • [database_integrations]
  • [stitch_webhooks]
keywords

Relevant keywords that could be used to search for the doc in a search engine.
layout

The name of the layout (in /_layouts) the page should use. This will usually be set to singer.

Integration details

High-level details about the integration, including who developed it, its name, its repo, etc.

Parameter Description
name

The name of the integration, in lowercase. Spaces should be replaced with underscores (_); periods (.) should be removed.

Example values:

  • google_adwords
  • mysql
  • closeio
display_name

The display name of the integration. The integration’s name should match how the provider uses it, including capitalization, punctuation, etc.

Example values:

  • Google AdWords
  • MySQL
  • Close.io
singer

If true, the integration is a Singer integration.
author

The name of the person/company who created the integration.

Example values:

  • Stitch
  • Fishtown Analytics
author-url

The website URL of the person/company who created the integration.

Example values:

  • https://www.stitchdata.com
repo-url

If this is a Singer integration, the URL of the integration’s Singer GitHub repository.

Example values:

  • https://www.github.com/singer-io/tap-{integration-name}
  • https://www.github.com/singer-io/tap-hubspot
  • https://www.github.com/singer-io/tap-mysql
port

Applicable only to database integrations. The database’s default port.

Example values:

  • 3306
  • 5432
db-type

The type of database backing the integration. For example: MariaDB is powered by MySQL.

Must be one of the following:

  • azure
  • mongo
  • mssql
  • mysql
  • postgres
  • rds

Stitch details

Details about how the integration works within the Stitch application.

Note: There are a few parameters that are specific to webhook integrations.

Parameter Description
status

The release status of the integration.

Must be one of the following:

  • Closed Beta
  • Open Beta
  • Released
  • Deprecated
certified

If true, the integration is Stitch-certified and will be officially supported by the Stitch team. Otherwise, the integration is a Community integration and will be supported by the Singer community.
historical

The default historical replication period for the integration.

Note: For webhook integrations, this must be Webhook.

Example values:

  • 28 days
  • 1 year
  • Webhook
frequency

The default Replication Frequency for the integration.

Note: For webhook integrations, this must be Continuous.

Example values:

  • 30 minutes
  • one hour
  • six hours
  • Continuous
tier

The type of Stitch subscription plan required to use the integration.

Must be one of the following:

  • Free
  • Premium
status-url

If available, the website URL to the integration provider’s status page.
icon

The file location of the .svg version of the integration’s logo, formatted as:

/images/integrations/icons/{integration-name}.svg
whitelist.tables

If true, users can set individual tables to replicate in Stitch.
whitelist.columns

If true, users can track individual columns on selected tables for replication in Stitch.
attribution-window

The default period of time Stitch uses as an attribution window to replicate data. Facebook Ads, Bing Ads, Google Analytics, etc. use attribution windows.

Example values:

  • 28 days
  • 15 days
  • 1 day
attribution-is-configurable

If true, users can configure the integration’s attribution window in the Stitch app.

Webhook-specific parameters

The following parameters are specific to webhook integrations:

Parameter Description
branded

Applicable only to webhook integrations. If true, this is a ‘branded’ integration. This will be true for the majority of webhook integrations.
primary-key.defined

Applicable only to webhook integrations. If Stitch hard-codes a primary key for the integration, enter true. Otherwise, leave as false.
primary-key.field

Applicable only to webhook integrations. If Stitch hard-codes a primary key for the integration (primary-key.defined: true), enter the name of the primary key column.

Stitch supports (for database integrations)

Applicable to database integrations only. Details about Stitch’s support for the database integration.

Parameter Description
versions

If Stitch supports only certain versions of the database, enter them into this field. The version should be identical to whatever the provider uses. For example: If a version is called 5.7.1A, then 5.7.1A should entered into this field.

Example values:

  • 9.3
  • 7+
ssh

If true, Stitch supports SSH connections for the database integration.
ssl

If true, Stitch supports SSL connections for the database integration.
sync-views

If true, Stitch supports replicating data from database views for the database integration.

Setup instructions: Requirements

The requirements for setting up and successfully connecting an integration to Stitch.

Parameter Description
requirements-list

The prerequisites for setting up the integration in Stitch. Markdown may be used to write the content in this field. If needed, HTML will also work.

This is formatted as a list, with an - item: parameter underneath requirements-list for each individual requirement. For example:

requirements-list:
  - item: "**Admin permissions in JIRA**. This is required to connect to JIRA."
  - item: "**A special JIRA account.** Because they said so."

Content section types

An integration doc consists of three content sections:

  • Connecting the integration
  • Replication details
  • Schema details

Each of these sections are created from content that lives in the corresponding Frontmatter list, outlined in the table below.

All sections take the same parameters, outlined in the Content sections section.

Parameter Description
setup-steps

The instructions for setting up the integration in Stitch. The content in this section creates the Connecting {integration-name} section in the integration’s doc.
replication-sections

Pertinent information about how Stitch replicates data from the integration. The content in this section creates the {integration-name} Replication section in the integration’s doc.

For example: Integration attribution windows, API rate limit information, etc.
schema-sections

Pertinent information about using the loaded data. The content in this section creates the {integration-name} Schema section in the integration’s doc.

For example: Dealing with UNIX timestamps, converting Google money fields, etc.

Content sections

Each content section type takes the parameters listed below, which Jekyll then parses and renders into content. Formatting is the same regardless of the content section type being used:

{content-section-type}:
  - title: "Select an attribution window"
    anchor: "select-attribution-window"
    content: |
      Do a thing

Using the appropriate layout (Page and formatting, layout), Jekyll will then render the following output:

<h2 id="select-attribution-window">
  Select an attribution window
</h2>

<p>Do a thing</p>
Parameter Description
title

The title of the section.

Example values:

  • Select an attribution window
  • Authorize Stitch to access Facebook Ads
anchor

The value to be used as the anchor for section’s title.

For example: select-attribution-window will create the anchor #select-attribution-window
content

The section content. Markdown may be used to write the content in this field. If needed, HTML will also work. Additionally, note that:

For single lines of content, the copy must be enclosed in double quotes (" "). For example:


  - title:
    anchor: 
    content: "Start content here."

For content requiring line breaks:

  • Add a pipe (|) just after content: to allow Jekyll to correctly parse the YAML,
  • On the new line, indent two spaces, and

  • Begin writing the copy; don’t enclose in double quotes.

For example:


  - title:
    anchor:
    content: |
      Start content here.
substeps

For setup instructions (setup-steps). If smaller steps make up completing a task, then substeps may be used. The substeps array requires the same parameters as its parent (setup-steps). For example:

setup-steps:
  - title: "Add Facebook Ads as a Stitch data source"
    anchor: "connect-to-stitch"
    description: "Last, you'll configure the FB settings in Stitch."
    substeps:
      - title: "Select an attribution window"
        anchor: "select-attribution-window"
        description: |
          Configure the attribution window with these steps:

      1. ...
      2. ...
Clone this wiki locally