Skip to content

Commit

Permalink
Edited Stripe, HubSpot, Intercom docs (#13810)
Browse files Browse the repository at this point in the history 
* Initial edits

* Updated the Stripe connector doc

* Updated the Stripe doc

* Updated HubSpot and Intercom docs

* Minor sidebar edit
  • Loading branch information
@Amruta-Ranade
Amruta-Ranade authored Jun 15, 2022
1 parent 8ab16cc commit bc98dc0
Show file tree
Hide file tree
Showing 4 changed files with 69 additions and 100 deletions.
68 changes: 29 additions & 39 deletions docs/integrations/sources/hubspot.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,10 @@
# HubSpot

This page contains the setup guide and reference information for the HubSpot source connector.
This page guides you through the process of setting up the HubSpot source connector.

## Prerequisites
## Prerequisite

Chose `start date` which is any data before this date will not be replicated and should be UTC date and time in the format 2017-01-25T00:00:00Z.

## Setup guide
### Step 1: Set up HubSpot

If you are using OAuth, most of the streams require the appropriate [scopes](https://legacydocs.hubspot.com/docs/methods/oauth2/initiate-oauth-integration#scopes) enabled for the API account.
You can use OAuth or an API key to authenticate your HubSpot account. If you choose to use OAuth, you need to configure the appropriate [scopes](https://legacydocs.hubspot.com/docs/methods/oauth2/initiate-oauth-integration#scopes) for the following streams:

| Stream | Required Scope |
| :--- | :--- |
Expand All @@ -36,37 +31,32 @@ If you are using OAuth, most of the streams require the appropriate [scopes](htt
| `workflows` | `automation` |


## Step 2: Set up the HubSpot connector in Airbyte

### For Airbyte Cloud:
1. [Log into your Airbyte Cloud](https://cloud.airbyte.io/workspaces) account.
2. In the left navigation bar, click **Sources**. In the top-right corner, click **+new source**.
3. On the Set up the source page, enter the name for the HubSpot connector and select **HubSpot** from the Source type dropdown.
4. Click `Authenticate your account` to sign in with Google and authorize your account.
5. Fill out a `start date`.
6. You're done.

### For Airbyte OSS:
1. Fill out a `API Key`.
2. Fill out a `start date`.
3. You're done.

To obtain the API Key for the account, go to settings -> integrations \(under the account banner\) -> API Key. If you already have an API Key you can use that. Otherwise, generate a new one. See [docs](https://knowledge.hubspot.com/integrations/how-do-i-get-my-hubspot-api-key) for more details.
## Set up the HubSpot source connector

1. Log into your [Airbyte Cloud](https://cloud.airbyte.io/workspaces) or Airbyte OSS account.
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **HubSpot** from the Source type dropdown.
4. Enter a name for your source.
5. For **Start date**, enter the date in YYYY-MM-DDTHH:mm:ssZ format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
6. You can use OAuth or an API key to authenticate your HubSpot account. We recommend using OAuth for Airbyte Cloud and an API key for Airbyte OSS.
- To authenticate using OAuth for Airbyte Cloud, click **Authenticate your HubSpot account** to sign in with HubSpot and authorize your account.
- To authenticate using API key for Airbyte OSS, select **API key** from the Authentication dropdown and enter the [API key](https://knowledge.hubspot.com/integrations/how-do-i-get-my-hubspot-api-key) for your HubSpot account.
:::note
Check the [performance considerations](#performance-considerations) before using an API key.
:::
7. Click **Set up source**.

## Supported sync modes

The HubSpot source connector supports the following [sync modes](https://docs.airbyte.com/cloud/core-concepts#connection-sync-modes):

| Feature | Supported? |
| :--- | :--- |
| Full Refresh Sync | Yes |
| Incremental Sync | Yes |
| Replicate Incremental Deletes | No |
| SSL connection | Yes |
- Full Refresh
- Incremental

## Supported Streams

The HubSpot source connector supports the following streams:

* [Campaigns](https://developers.hubspot.com/docs/methods/email/get_campaign_data)
* [Companies](https://developers.hubspot.com/docs/api/crm/companies) \(Incremental\)
* [Contact Lists](http://developers.hubspot.com/docs/methods/lists/get_lists) \(Incremental\)
Expand Down Expand Up @@ -97,17 +87,17 @@ The HubSpot source connector supports the following [sync modes](https://docs.ai

### A note on the `engagements` stream

Objects in the `engagements` stream can have one of the following types: `note`, `email`, `task`, `meeting`, `call`.

Depending on the type of engagement, different properties will be set for that object in the `engagements_metadata` table in the destination.
Objects in the `engagements` stream can have one of the following types: `note`, `email`, `task`, `meeting`, `call`. Depending on the type of engagement, different properties is set for that object in the `engagements_metadata` table in the destination:

* A `call` engagement will have a corresponding `engagements_metadata` object with non-null values in the `toNumber`, `fromNumber`, `status`, `externalId`, `durationMilliseconds`, `externalAccountId`, `recordingUrl`, `body`, and `disposition` columns.
* An `email` engagement will have a corresponding `engagements_metadata` object with with non-null values in the `subject`, `html`, and `text` columns. In addition, there will be records in four related tables, `engagements_metadata_from`, `engagements_metadata_to`, `engagements_metadata_cc`, `engagements_metadata_bcc`.
* A `meeting` engagement will have a corresponding `engagements_metadata` object with non-null values in the `body`, `startTime`, `endTime`, and `title` columns.
* A `note` engagement will have a corresponding `engagements_metadata` object with non-null values in the `body` column.
* A `task` engagement will have a corresponding `engagements_metadata` object with non-null values in the `body`, `status`, and `forObjectType` columns.
- A `call` engagement has a corresponding `engagements_metadata` object with non-null values in the `toNumber`, `fromNumber`, `status`, `externalId`, `durationMilliseconds`, `externalAccountId`, `recordingUrl`, `body`, and `disposition` columns.
- An `email` engagement has a corresponding `engagements_metadata` object with with non-null values in the `subject`, `html`, and `text` columns. In addition, there will be records in four related tables, `engagements_metadata_from`, `engagements_metadata_to`, `engagements_metadata_cc`, `engagements_metadata_bcc`.
- A `meeting` engagement has a corresponding `engagements_metadata` object with non-null values in the `body`, `startTime`, `endTime`, and `title` columns.
- A `note` engagement has a corresponding `engagements_metadata` object with non-null values in the `body` column.
- A `task` engagement has a corresponding `engagements_metadata` object with non-null values in the `body`, `status`, and `forObjectType` columns.

**Note**: HubSpot API currently only supports `quotes` endpoint using API Key, using OAuth it is impossible to access this stream (as reported by [community.hubspot.com](https://community.hubspot.com/t5/APIs-Integrations/Help-with-using-Feedback-CRM-API-and-Quotes-CRM-API/m-p/449104/highlight/true#M44411)).
:::note
HubSpot API currently only supports `quotes` endpoint using API Key, using OAuth it is impossible to access this stream (as reported by [community.hubspot.com](https://community.hubspot.com/t5/APIs-Integrations/Help-with-using-Feedback-CRM-API-and-Quotes-CRM-API/m-p/449104/highlight/true#M44411)).
:::

## Performance considerations

Expand Down
40 changes: 16 additions & 24 deletions docs/integrations/sources/intercom.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,29 @@
# Intercom

This page contains the setup guide and reference information for the intercom source connector.
This page guides you through the process of setting up the Intercom source connector.

## Setup guide
## Step 1: Set up the intercom connector in Airbyte
## Set up the Intercom connector

### For Airbyte Cloud:

1. [Log into your Airbyte Cloud](https://cloud.airbyte.io/workspaces) account.
2. In the left navigation bar, click **Sources**. In the top-right corner, click **+new source**.
3. On the Set up the source page, enter the name for the intercom connector and select **intercom** from the Source type dropdown.
4. Click Authenticate your account to sign in with Intercom and authorize your account.
5. Fill in the `start date` field.
6. You should be ready to sync data.

### For Airbyte OSS:

1. Fill in the [Access Token](https://developers.intercom.com/building-apps/docs/authentication-types#section-how-to-get-your-access-token).
2. Fill in the `start date` field.
3. You should be ready to sync data.
1. Log into your [Airbyte Cloud](https://cloud.airbyte.io/workspaces) or Airbyte OSS account.
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **Intercom** from the Source type dropdown.
4. Enter a name for your source.
5. For **Start date**, enter the date in YYYY-MM-DDTHH:mm:ssZ format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
6. For Airbyte Cloud, click **Authenticate your Intercom account** to sign in with Intercom and authorize your account.
For Airbyte OSS, enter your [Access Token](https://developers.intercom.com/building-apps/docs/authentication-types#section-how-to-get-your-access-token) to authenticate your account.
7. Click **Set up source**.

## Supported sync modes

| Feature | Supported? |
| :--- | :--- |
| Full Refresh Sync | Yes |
| Incremental - Append Sync | Yes |
| SSL connection | Yes |
| Namespaces | No |
The Intercom source connector supports the following [sync modes](https://docs.airbyte.com/cloud/core-concepts#connection-sync-modes):

- Full Refresh
- Incremental

## Supported Streams

The Intercom source connector supports the following streams:

* [Admins](https://developers.intercom.com/intercom-api-reference/reference#list-admins) \(Full table\)
* [Companies](https://developers.intercom.com/intercom-api-reference/reference#list-companies) \(Incremental\)
* [Company Segments](https://developers.intercom.com/intercom-api-reference/reference#list-attached-segments-1) \(Incremental\)
Expand All @@ -50,7 +42,7 @@ This page contains the setup guide and reference information for the intercom so

The connector is restricted by normal Intercom [requests limitation](https://developers.intercom.com/intercom-api-reference/reference#rate-limiting).

The Intercom connector should not run into Intercom API limitations under normal usage. Please [create an issue](https://github.com/airbytehq/airbyte/issues) if you see any rate limit issues that are not automatically retried successfully.
The Intercom connector should not run into Intercom API limitations under normal usage. [Create an issue](https://github.com/airbytehq/airbyte/issues) if you see any rate limit issues that are not automatically retried successfully.


## Changelog
Expand Down
60 changes: 24 additions & 36 deletions docs/integrations/sources/stripe.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,50 +2,42 @@

This page guides you through the process of setting up the Stripe source connector.

## Prerequisites

* Your [Stripe `Account ID`](https://dashboard.stripe.com/settings/account)
* Your [Stripe `Secret Key`](https://dashboard.stripe.com/apikeys)

## Prerequisites (Airbyte Open Source)
## Set up the Stripe source connector

* Stripe `Account ID` - the `Account ID` of your [Stripe Account](https://dashboard.stripe.com/settings/account)
* Stripe `Secret Key` - the `Secret Key` to be used with [authorized API calls](https://dashboard.stripe.com/apikeys) to retrieve your Stripe data.
* `Lookback Window (in days)` (Optional) - the value in days, which allows you to sync your data with shift equals to the number of days set. If your data is updated after creation, you can use the this option to always reload data from the past N days. This allows you to pick up updates to the data.
Example usage: `Start Date` is set to "2021-01-01T00:00:00Z" then:
* Default is 0, meaning data will be synced from the `Start Date`.
* 1 - means (`Start Date` - 1 day), so the start point of the sync will be "2020-12-31T00:00:00Z"
* 7 - means (`Start Date` - 7 days) then `Start Date` will be "2020-12-25T00:00:00Z"
* 30 - means (`Start Date` - 30 days) then `Start Date` will be "2020-12-02T00:00:00Z"

## Step 1: Set up Stripe
1. Log into your [Airbyte Cloud](https://cloud.airbyte.io/workspaces) or Airbyte OSS account.
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **Stripe** from the Source type dropdown.
4. Enter a name for your source.
5. For **Account ID**, enter your [Stripe `Account ID`](https://dashboard.stripe.com/settings/account).
6. For **Secret Key**, enter your [Stripe `Secret Key`](https://dashboard.stripe.com/apikeys)

We recommend creating a secret key specifically for Airbyte to control which resources Airbyte can access. For ease of use, we recommend granting read permission to all resources and configuring which resource to replicate in the Airbyte UI. You can also use the API keys for the [test mode](https://stripe.com/docs/keys#obtain-api-keys) to try out the Stripe integration with Airbyte.

in the Stripe [dashboard](https://dashboard.stripe.com/apikeys) access the secret key for your account. Secret keys for the live Stripe environment will be prefixed with `sk_live_`or `rk_live`.

We recommend creating a restricted key specifically for Airbyte access. This will allow you to control which resources Airbyte should be able to access. For ease of use, we recommend using read permissions for all resources and configuring which resource to replicate in the Airbyte UI.

If you would like to test Airbyte using test data on Stripe, `sk_test_` and `rk_test_` API keys are also supported.

## Step 2: Set up the source connector in Airbyte

**For Airbyte OSS:**

1. Go to local Airbyte page.
2. In the left navigation bar, click **Sources**. In the top-right corner, click **+ new source**.
3. On the Set up the source page, enter the name for the connector and select **Stripe** from the Source type dropdown.
4. Copy and paste info from step 1:
* account ID
* Secret Key
5. Choose required Start date and type of aggregation report
6. Click `Set up source`.
7. For **Replication start date**, enter the date in YYYY-MM-DDTHH:mm:ssZ format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
8. For **Lookback Window in days (Optional)**, select the number of days the value in days prior to the start date that you to sync your data with. If your data is updated after setting up this connector, you can use the this option to reload data from the past N days. Example: If the Replication start date is set to `2021-01-01T00:00:00Z`, then:
- If you leave the Lookback Window in days parameter to its the default value of 0, Airbyte will sync data from the Replication start date `2021-01-01T00:00:00Z`
- If the Lookback Window in days value is set to 1, Airbyte will consider the Replication start date to be `2020-12-31T00:00:00Z`
- If the Lookback Window in days value is set to 7, Airbyte will sync data from `2020-12-31T00:00:00Z`
9. Click **Set up source**.

## Supported sync modes

The Stripe source connector supports the following [sync modes](https://docs.airbyte.com/cloud/core-concepts#connection-sync-modes):
- Full Refresh
- Incremental

:::note
Since the Stripe API does not allow querying objects which were updated since the last sync, the Stripe connector uses the `created` field to query for new data in your Stripe account.
:::

## Supported Streams

This Source is capable of syncing the following core Streams:
The Stripe source connector supports the following streams:

* [Balance Transactions](https://stripe.com/docs/api/balance_transactions/list) \(Incremental\)
* [Bank accounts](https://stripe.com/docs/api/customer_bank_accounts/list)
Expand All @@ -70,17 +62,13 @@ This Source is capable of syncing the following core Streams:
* [Subscriptions](https://stripe.com/docs/api/subscriptions/list) \(Incremental\)
* [Transfers](https://stripe.com/docs/api/transfers/list) \(Incremental\)

### Note on Incremental Syncs

The Stripe API does not allow querying objects which were updated since the last sync. Therefore, this connector uses the `created` field to query for new data in your Stripe account.

### Data type mapping

The [Stripe API](https://stripe.com/docs/api) uses the same [JSONSchema](https://json-schema.org/understanding-json-schema/reference/index.html) types that Airbyte uses internally \(`string`, `date-time`, `object`, `array`, `boolean`, `integer`, and `number`\), so no type conversions happen as part of this source.
The [Stripe API](https://stripe.com/docs/api) uses the same [JSONSchema](https://json-schema.org/understanding-json-schema/reference/index.html) types that Airbyte uses internally \(`string`, `date-time`, `object`, `array`, `boolean`, `integer`, and `number`\), so no type conversions are performed for the Stripe connector.

### Performance considerations

The Stripe connector should not run into Stripe API limitations under normal usage. Please [create an issue](https://github.com/airbytehq/airbyte/issues) if you see any rate limit issues that are not automatically retried successfully.
The Stripe connector should not run into Stripe API limitations under normal usage. [Create an issue](https://github.com/airbytehq/airbyte/issues) if you see any rate limit issues that are not automatically retried successfully.

## Changelog

Expand Down
1 change: 0 additions & 1 deletion docusaurus/sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,6 @@ module.exports = {
'contributing-to-airbyte/code-style',
'contributing-to-airbyte/gradle-cheatsheet',
'contributing-to-airbyte/gradle-dependency-update',
'contributing-to-airbyte/monorepo-python-development',
{
type: 'link',
label: 'Connector template',
Expand Down

0 comments on commit bc98dc0

Please sign in to comment.