Skip to content

Commit

Permalink
edited connector docs (#18855)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Amruta-Ranade
Amruta-Ranade authored Nov 2, 2022
1 parent 7c2c701 commit fbe16d1
Show file tree
Hide file tree
Showing 12 changed files with 208 additions and 352 deletions.
84 changes: 28 additions & 56 deletions docs/integrations/sources/chargebee.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,47 +4,27 @@ This page contains the setup guide and reference information for the Chargebee s

## Prerequisites

This Chargebee source uses the [Chargebee Python Client Library](https://github.com/chargebee/chargebee-python/).

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

Log into Chargebee and then generate an [API Key](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2#api_authentication).
Then follow [these](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2) instructions, under `API Version` section, on how to find your Product Catalog version.

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

#### For Airbyte Cloud:
1. Log into your [Airbyte Cloud](https://cloud.airbyte.io/workspaces) account.
2. Click **Sources** and then click **+New source**.
3. On the Set up the source page, enter the name for the Harvest connector and select **Chargebee** from the Source type dropdown.
4. Enter a name for your source
5. Enter your `site_api_key`
6. Enter your `site`
7. Enter your `product_catalog`
8. Enter the `start_date` you want your sync to start from
9. Click **Set up source**

#### For Airbyte OSS:
1. Navigate to the Airbyte Open Source dashboard
2. Enter a name for your source
3. Enter your `site_api_key`
4. Enter your `site`
5. Enter your `product_catalog`
6. Enter the `start_date` you want your sync to start from
7. Click **Set up source**
To set up the Chargebee source connector, you'll need the [Chargebee API key](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2#api_authentication) and the [Product Catalog version](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2).

## Set up the Chargebee connector in Airbyte

1. [Log into your Airbyte Cloud](https://cloud.airbyte.io/workspaces) account or navigate to the Airbyte Open Source dashboard.
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **Chargebee** from the Source type dropdown.
4. Enter the name for the Chargebee connector.
5. For **Site**, enter the site prefix for your Chargebee instance.
6. For **Start Date**, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated.
7. For **API Key**, enter the [Chargebee API key](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2#api_authentication).
8. For **Product Catalog**, enter the Chargebee [Product Catalog version](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2).
9. Click **Set up source**.

## Supported sync modes

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

| Feature | Supported? |
| :--- | :--- |
| Full Refresh Sync | Yes |
| Incremental - Append Sync | Yes |
| Replicate Incremental Deletes | No |
| SSL connection | Yes |
| Namespaces | No |
* [Full Refresh - Overwrite](https://docs.airbyte.com/understanding-airbyte/glossary#full-refresh-sync)
* [Full Refresh - Append](https://docs.airbyte.com/understanding-airbyte/connections/full-refresh-append)
* [Incremental - Append](https://docs.airbyte.com/understanding-airbyte/connections/incremental-append)

## Supported Streams

Expand All @@ -58,16 +38,9 @@ The Chargebee source connector supports the following [sync modes](https://docs.
* [Item Prices](https://apidocs.chargebee.com/docs/api/item_prices?prod_cat_ver=2#list_item_prices)
* [Attached Items](https://apidocs.chargebee.com/docs/api/attached_items?prod_cat_ver=2#list_attached_items)

## Performance considerations

The Chargebee connector should not run into [Chargebee API](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2#api_rate_limits) 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.
Some streams are available only for specific on Product Catalog versions:

## Tutorials

Some streams may depend on Product Catalog version and be accessible only on sites with specific Product Catalog version. This means that we have following streams:

1. presented in both `Product Catalog 1.0` and `Product Catalog 2.0`:
1. Available in `Product Catalog 1.0` and `Product Catalog 2.0`:
* Customers
* Events
* Invoices
Expand All @@ -76,27 +49,26 @@ Some streams may depend on Product Catalog version and be accessible only on sit
* Coupons
* Subscriptions
* Transactions
2. presented only in `Product Catalog 1.0`:
2. Available only in `Product Catalog 1.0`:
* Plans
* Addons
3. presented only in `Product Catalog 2.0`:
3. Available only in `Product Catalog 2.0`:
* Items
* Item Prices
* Attached Items

Also, 12 streams from the above 13 incremental streams are pure incremental meaning that they:
Note that except the `Attached Items` stream, all the streams listed above are incremental streams, which means they:

* read only new records;
* output only new records.
* Read only new records
* Output only new records

`Attached Items` incremental stream is also incremental but with one difference, it:
The `Attached Items` stream is also incremental but it reads _all_ records and outputs only new records, which is why syncing the `Attached Items` stream, even in incremental mode, is expensive in terms of your Chargebee API quota.

* read all records;
* output only new records.
Generally speaking, it incurs a number of API calls equal to the total number of attached items in your chargebee instance divided by 100, regardless of how many `AttachedItems` were actually changed or synced in a particular sync job.

## Performance considerations

This means that syncing the `Attached Items` stream, even in incremental mode, is expensive in terms of your Chargebee API quota.
Generally speaking, it incurs a number of API calls equal to the total number of attached items in your chargebee instance divided by 100,
regardless of how many AttachedItems were actually changed or synced in a particular sync job.
The Chargebee connector should not run into [Chargebee API](https://apidocs.chargebee.com/docs/api?prod_cat_ver=2#api_rate_limits) limitations under normal usage. [Create an issue](https://github.com/airbytehq/airbyte/issues) if you encounter any rate limit issues that are not automatically retried successfully.

## Changelog

Expand Down
66 changes: 17 additions & 49 deletions docs/integrations/sources/freshdesk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,56 +4,26 @@ This page guides you through the process of setting up the Freshdesk source conn

## Prerequisites

* Freshdesk Account
* Domain URL
* Freshdesk API Key
To set up the Freshdesk source connector, you'll need the Freshdesk [domain URL](https://support.freshdesk.com/en/support/solutions/articles/50000004704-customizing-your-helpdesk-url) and the [API key](https://support.freshdesk.com/support/solutions/articles/215517).

## Step 1: Set up Freshdesk
## Set up the Freshdesk connector in Airbyte

### Get Domain URL
1. [Log into your Airbyte Cloud](https://cloud.airbyte.io/workspaces) account or navigate to the Airbyte Open Source dashboard.
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **Freshdesk** from the Source type dropdown.
4. Enter the name for the Freshdesk connector.
5. For **Domain**, enter your [Freshdesk domain URL](https://support.freshdesk.com/en/support/solutions/articles/50000004704-customizing-your-helpdesk-url).
6. For **API Key**, enter your [Freshdesk API key](https://support.freshdesk.com/support/solutions/articles/215517).
7. For **Start Date**, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated.
8. For **Requests per minute**, enter the number of requests per minute that this source allowed to use. The Freshdesk rate limit is 50 requests per minute per app per account.
9. Click **Set up source**.

You can find your domain URL by logging into your account and check the URL in your browser, the domain url should look like: `https://myaccount.freshdesk.com/...`, where `myaccount.freshdesk.com` - is your domain URL.
## Supported sync modes

### Get Freshdesk API Key

Follow the link to read more about [how to find your API key](https://support.freshdesk.com/support/solutions/articles/215517). You need the admin permissions to access the account settings.


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

**For Airbyte Cloud**

1. Log into your [Airbyte Cloud](https://cloud.airbyte.io/workspaces) account.
2. Click **Sources** and then click **+ New source**.
3. On the source setup page, select **Freshdesk** from the Source type dropdown and enter a name for this connector.
4. Enter your `Domain URL`.
5. Enter your `Freshdesk API Key`.
6. Choose the `Start Date` as the starting point for your data replication.
5. Click `Set up source`.

**For Airbyte Open Source:**

1. Go to local Airbyte page.
2. Click **Sources** and then click **+ New source**.
3. On the source setup page, select **Freshdesk** from the Source type dropdown and enter a name for this connector.
4. Enter your `Domain URL`.
5. Enter your `Freshdesk API Key`.
6. Choose the `Start Date` as the starting point for your data replication.
5. Click `Set up source`.

## Supported sync modes & Features

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

The Freshdesk supports full refresh and incremental sync. You can choose if this connector will copy only the new or updated data, or all rows in the tables and columns you set up for replication, every time a sync is run. There are two types of incremental sync:

* server level \(native\) - when API supports filter on specific columns that Airbyte use to track changes \(`updated_at`, `created_at`, etc\)
* client level - when API doesn't support filter and Airbyte performs filtration on its side.
* [Full Refresh - Overwrite](https://docs.airbyte.com/understanding-airbyte/glossary#full-refresh-sync)
* [Full Refresh - Append](https://docs.airbyte.com/understanding-airbyte/connections/full-refresh-append)
* [Incremental - Append](https://docs.airbyte.com/understanding-airbyte/connections/incremental-append)
* [Incremental - Deduped History](https://docs.airbyte.com/understanding-airbyte/connections/incremental-deduped-history)

## Supported Streams

Expand All @@ -71,11 +41,9 @@ Several output streams are available from this source:
* [Tickets](https://developers.freshdesk.com/api/#tickets) \(Native Incremental Sync\)
* [Time Entries](https://developers.freshdesk.com/api/#time-entries)

If there are more endpoints you'd like Airbyte to support, please [create an issue.](https://github.com/airbytehq/airbyte/issues/new/choose)

## Performance considerations

The Freshdesk connector should not run into Freshdesk 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 Freshdesk connector should not run into Freshdesk API limitations under normal usage. [Create an issue](https://github.com/airbytehq/airbyte/issues) if you encounter any rate limit issues that are not automatically retried successfully.


## Changelog
Expand Down
43 changes: 12 additions & 31 deletions docs/integrations/sources/greenhouse.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,25 @@ This page contains the setup guide and reference information for the Greenhouse

## Prerequisites

Please follow the [Greenhouse documentation for generating an API key](https://developers.greenhouse.io/harvest.html#authentication).
To set up the Greenhouse source connector, you'll need the [Harvest API key](https://developers.greenhouse.io/harvest.html#authentication) with permissions to the resources Airbyte should be able to access.

## Set up the Greenhouse 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 **Source**. In the top-right corner, click **+New source**.
3. On the Set up the source page, enter the name for the Greenhouse connector and select **Greenhouse** from the Source type dropdown.
4. Enter your `api_key`
5. Click **Set up source**

### For Airbyte OSS:

1. Navigate to the Airbyte Open Source dashboard
2. Set the name for your source
3. Enter your `api_key`
4. Click **Set up source**
1. [Log into your Airbyte Cloud](https://cloud.airbyte.io/workspaces) account or navigate to the Airbyte Open Source dashboard.
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **Greenhouse** from the Source type dropdown.
4. Enter the name for the Greenhouse connector.
4. Enter your [**Harvest API Key**](https://developers.greenhouse.io/harvest.html#authentication) that you obtained from Greenhouse.
5. Click **Set up source**.

## Supported sync modes

The Greenhouse 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 | Coming soon |
| SSL connection | Yes |
| Namespaces | No |
* [Full Refresh - Overwrite](https://docs.airbyte.com/understanding-airbyte/glossary#full-refresh-sync)
* [Full Refresh - Append](https://docs.airbyte.com/understanding-airbyte/connections/full-refresh-append)
* [Incremental - Append](https://docs.airbyte.com/understanding-airbyte/connections/incremental-append)
* [Incremental - Deduped History](https://docs.airbyte.com/understanding-airbyte/connections/incremental-deduped-history)

## Supported Streams

Expand All @@ -56,17 +45,9 @@ The Greenhouse source connector supports the following [sync modes](https://docs
* [Sources](https://developers.greenhouse.io/harvest.html#get-list-sources)
* [Users](https://developers.greenhouse.io/harvest.html#get-list-users)

## Setting permissions for API Keys
You can specify which API endpoints your API keys have access to from the Greenhouse Dev Center. This will allow you to permit or deny access to each endpoint individually. Any API keys created before January 18th, 2017 will have full permissions to all API endpoints that existed at that time, but any new API keys created after that point will need the required endpoint permissions to be explicitly granted.
To add or remove endpoint permissions on an API key, go to the Dev Center in Greenhouse, click “API Credential Management”, then click “Manage Permissions” next to your Harvest API Key. From there, check or uncheck permissions for any endpoints.

**Important Note**: Users with Harvest API keys may access all the data in the endpoint. Access to data in Harvest is binary: everything or nothing. Harvest API keys should be given to internal developers with this understanding and to third parties with caution. Each key should only be allowed to access the endpoints it absolutely needs.
See more on this [here](https://developers.greenhouse.io/harvest.html#authentication).

## Performance considerations

The Greenhouse connector should not run into Greenhouse 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 Greenhouse connector should not run into Greenhouse API limitations under normal usage. [Create an issue](https://github.com/airbytehq/airbyte/issues) if you encounter any rate limit issues that are not automatically retried successfully.

## Changelog

Expand Down
48 changes: 25 additions & 23 deletions docs/integrations/sources/harvest.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,38 +4,40 @@ This page contains the setup guide and reference information for the Harvest sou

## Prerequisites

See [Harvest documentation](https://help.getharvest.com/api-v2/authentication-api/authentication/authentication/) for more details.
To set up the Harvest source connector, you'll need the [Harvest Account ID and API key](https://help.getharvest.com/api-v2/authentication-api/authentication/authentication/).

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

This connector supports only authentication with API Key. To obtain API key follow the instructions below:
### For Airbyte Cloud

1. Go to Account Settings page;
2. Under Integrations section press Authorized OAuth2 API Clients button;
3. New page will be opened on which you need to click on Create New Personal Access Token button and follow instructions.
1. [Log into your Airbyte Cloud](https://cloud.airbyte.io/workspaces).
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **Harvest** from the Source type dropdown.
4. Enter the name for the Harvest connector.
5. Enter your [Harvest Account ID](https://help.getharvest.com/api-v2/authentication-api/authentication/authentication/).
6. For **Start Date**, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated.
7. For Authentication mechanism, select **Authenticate via Harvest (OAuth)** from the dropdown and click **Authenticate your Harvest account**. Log in and authorize your Harvest account.
8. Click **Set up source**.

## Step 2: Set up the Harvest connector in Airbyte
### For Airbyte Open Source

1. Navigate to the Airbyte Open Source dashboard
2. Set the name for your source
3. Enter your `api_token`
4. Enter your `account_id`
5. Enter the `replication_start_date` you want your sync to start from
6. Click **Set up source**
1. Navigate to the Airbyte Open Source dashboard.
2. Click **Sources** and then click **+ New source**.
3. On the Set up the source page, select **Harvest** from the Source type dropdown.
4. Enter the name for the Harvest connector.
5. Enter your [Harvest Account ID](https://help.getharvest.com/api-v2/authentication-api/authentication/authentication/).
6. For **Start Date**, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated.
7. For **Authentication mechanism**, select **Authenticate with Personal Access Token** from the dropdown. Enter your [Personal Access Token](https://help.getharvest.com/api-v2/authentication-api/authentication/authentication/#personal-access-tokens).
8. Click **Set up source**.

## Supported sync modes

The Harvest 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 |
| Namespaces | No |

* [Full Refresh - Overwrite](https://docs.airbyte.com/understanding-airbyte/glossary#full-refresh-sync)
* [Full Refresh - Append](https://docs.airbyte.com/understanding-airbyte/connections/full-refresh-append)
* [Incremental - Append](https://docs.airbyte.com/understanding-airbyte/connections/incremental-append)
* [Incremental - Deduped History](https://docs.airbyte.com/understanding-airbyte/connections/incremental-deduped-history)

## Supported Streams

Expand Down Expand Up @@ -67,7 +69,7 @@ The Harvest source connector supports the following [sync modes](https://docs.ai

## Performance considerations

The Harvest connector will gracefully handle rate limits. For more information, see [the Harvest docs for rate limitations](https://help.getharvest.com/api-v2/introduction/overview/general/#rate-limiting).
The connector is restricted by the [Harvest rate limits](https://help.getharvest.com/api-v2/introduction/overview/general/#rate-limiting).

## Changelog

Expand Down
Loading

0 comments on commit fbe16d1

Please sign in to comment.