docs: Hubspot stream labels (#44177)

nataliekwong · aldogonzalez8 · web-flow · commit d29e15471613 · 2024-08-19T02:15:52.000-07:00
Co-authored-by: Aldo Gonzalez &lt;168454423+aldogonzalez8@users.noreply.github.com&gt;
diff --git a/docs/integrations/sources/hubspot.md b/docs/integrations/sources/hubspot.md
@@ -17,42 +17,23 @@ This page contains the setup guide and reference information for the [HubSpot](h
 
 ## Setup guide
 
-<!-- env:cloud -->
-
-**For Airbyte Cloud:**
-
-We highly recommend you use OAuth rather than Private App authentication, as it significantly simplifies the setup process.
-
-<!-- /env:cloud -->
-
-<!-- env:oss -->
-
-**For Airbyte Open Source:**
-
-We recommend Private App authentication.
-
-<!-- /env:oss -->
-
-More information on HubSpot authentication methods can be found
-[here](https://developers.hubspot.com/docs/api/intro-to-auth).
-
 ### Step 1: Set up HubSpot
 
 <!-- env:cloud -->
 
 **For Airbyte Cloud:**
 
-**- OAuth** (Recommended)
+**- OAuth** (Recommended). We highly recommend you use OAuth rather than Private App authentication, as it significantly simplifies the setup process.
 
-**- Private App:** If you are using a Private App, you will need to use your Access Token to set up the connector. Please refer to the [official HubSpot documentation](https://developers.hubspot.com/docs/api/private-apps) for a detailed guide.
+**- Private App:** If you are using a Private App, you will need to use your Access Token to set up the connector. Please refer to the [official HubSpot documentation](https://developers.hubspot.com/docs/api/private-apps) to learn how to obtain the access token.
 
 <!-- /env:cloud -->
 
 <!-- env:oss -->
 
 **For Airbyte Open Source:**
 
-**- Private App setup** (Recommended): If you are authenticating via a Private App, you will need to use your Access Token to set up the connector. Please refer to the [official HubSpot documentation](https://developers.hubspot.com/docs/api/private-apps) for a detailed guide.
+**- Private App setup** (Recommended): If you are authenticating via a Private App, you will need to use your Access Token to set up the connector. Please refer to the [official HubSpot documentation](https://developers.hubspot.com/docs/api/private-apps) to learn how to obtain the access token.
 
 **- OAuth setup:** If you are using Oauth to authenticate on Airbyte Open Source, please refer to [Hubspot's detailed walkthrough](https://developers.hubspot.com/docs/api/working-with-oauth). To set up the connector, you will need to acquire your:
 
@@ -61,11 +42,18 @@ More information on HubSpot authentication methods can be found
 - Refresh Token
 <!-- /env:oss -->
 
-### Step 2: Configure the scopes for your streams
+More information on HubSpot authentication methods can be found
+[here](https://developers.hubspot.com/docs/api/intro-to-auth).
+
+### Step 2: Configure the scopes for your streams (Private App only)
+
+These instructions are only relevant if you are using a **Private App** for authentication. You can ignore this if you are authenticating via OAuth.
 
-Unless you are authenticating via OAuth on **Airbyte Cloud**, you must manually configure scopes to ensure Airbyte can sync all available data. To see a breakdown of the specific scopes each stream uses, see our full [Hubspot documentation](https://docs.airbyte.com/integrations/sources/hubspot/).
+To set up a Private App, you must manually configure scopes to ensure Airbyte can sync all available data. Each scope relates to a specific stream or streams. Please refer to [Hubspot's page on scopes](https://legacydocs.hubspot.com/docs/methods/oauth2/initiate-oauth-integration#scopes) for instructions.
+
+<details>
+  <summary>Expand to review scopes</summary>
 
-Next, you need to configure the appropriate scopes for the following streams. Please refer to [Hubspot's page on scopes](https://legacydocs.hubspot.com/docs/methods/oauth2/initiate-oauth-integration#scopes) for instructions.
 
 | Stream                      | Required Scope                                                                                               |
 | :-------------------------- | :----------------------------------------------------------------------------------------------------------- |
@@ -94,6 +82,8 @@ Next, you need to configure the appropriate scopes for the following streams. Pl
 | `tickets`                   | `tickets`                                                                                                    |
 | `workflows`                 | `automation`                                                                                                 |
 
+</details>
+
 ### Step 3: Set up the HubSpot connector in Airbyte
 
 <!-- env:cloud -->
@@ -105,14 +95,19 @@ Next, you need to configure the appropriate scopes for the following streams. Pl
 3. On the Set up the source page, select HubSpot from the Source type dropdown.
 4. Enter a name for the HubSpot connector.
 5. From the **Authentication** dropdown, select your chosen authentication method:
-   - **Recommended:** To authenticate using OAuth, select **OAuth** and click **Authenticate your HubSpot account** to sign in with HubSpot and authorize your account.
-     :::tip HubSpot Authentication issues
-     You might encounter errors during the connection process in the popup window, such as `An invalid scope name was provided`.
-     To resolve this, close the window and attempt authentication again.
+   - (Recommended) To authenticate using OAuth, select **OAuth** and click **Authenticate your HubSpot account** to sign in with HubSpot and authorize your account.
+
+     :::note HubSpot Authentication issues
+     You may encounter an error during the authentication process in the popup window with the message `An invalid scope name was provided`. To resolve this, close the window and retry authentication.
      :::
-   - **Not Recommended:**To authenticate using a Private App, select **Private App** and enter the Access Token for your HubSpot account.
-6. For **Start date**, use the provided datepicker or enter the date programmatically in the following format:
-   `yyyy-mm-ddThh:mm:ssZ`. The data added on and after this date will be replicated. If not set, "2006-06-01T00:00:00Z" (Hubspot creation date) will be used as start date. It's recommended to provide relevant to your data start date value to optimize synchronization.
+   - (Not Recommended) To authenticate using a Private App, select **Private App** and enter the Access Token for your HubSpot account.
+
+<FieldAnchor field="start_date">
+
+6. For **Start date**, use the provided datepicker or enter the date in the following format: `yyyy-mm-ddThh:mm:ssZ`. Data added on and after this date will be replicated. If this is not set, "2006-06-01T00:00:00Z" (the date Hubspot was created) will be used as a start date. 
+
+</FieldAnchor>
+
 7. Click **Set up source** and wait for the tests to complete.
 <!-- /env:cloud -->
 
@@ -124,36 +119,20 @@ Next, you need to configure the appropriate scopes for the following streams. Pl
 2. From the Airbyte UI, click **Sources**, then click on **+ New Source** and select **HubSpot** from the list of available sources.
 3. Enter a **Source name** of your choosing.
 4. From the **Authentication** dropdown, select your chosen authentication method:
-   - **Recommended:** To authenticate using a Private App, select **Private App** and enter the Access Token for your HubSpot account.
-   - **Not Recommended:**To authenticate using OAuth, select **OAuth** and enter your Client ID, Client Secret, and Refresh Token.
-5. For **Start date**, use the provided datepicker or enter the date programmatically in the following format:
+   - (Recommended) To authenticate using a Private App, select **Private App** and enter the Access Token for your HubSpot account.
+   - (Not Recommended:) To authenticate using OAuth, select **OAuth** and enter your Client ID, Client Secret, and Refresh Token.
+5. For **Start date**, use the provided datepicker or enter the date in the following format:
    `yyyy-mm-ddThh:mm:ssZ`. The data added on and after this date will be replicated. If not set, "2006-06-01T00:00:00Z" (Hubspot creation date) will be used as start date. It's recommended to provide relevant to your data start date value to optimize synchronization.
 6. Click **Set up source** and wait for the tests to complete.
 
 <FieldAnchor field="enable_experimental_streams">
 
 ### Experimental streams
 
-[Web Analytics](https://developers.hubspot.com/docs/api/events/web-analytics) streams may be enabled as an experimental feature but please note that they are based on API which is currently in beta and may change at some point of time or be unstable.
+[Web Analytics](https://developers.hubspot.com/docs/api/events/web-analytics) streams may be enabled as an experimental feature. Note that these streams use a Hubspot API that is currently in beta, and they may be modified or unstable as the API continues to develop.
 
 </FieldAnchor>
 
-### Custom CRM Objects
-
-Custom CRM Objects and Custom Web Analytics will appear as streams available for sync, alongside the standard objects listed above.
-
-If you set up your connections before April 15th, 2023 (on Airbyte Cloud) or before 0.8.0 (OSS) then you'll need to do some additional work to sync custom CRM objects.
-
-First you need to give the connector some additional permissions:
-
-<!-- env:cloud -->
-
-- **If you are using OAuth on Airbyte Cloud** go to the Hubspot source settings page in the Airbyte UI and re-authenticate via OAuth to allow Airbyte the permissions to access custom objects.
-<!-- /env:cloud -->
-- **If you are using OAuth on OSS or Private App auth** go into the Hubspot UI where you created your Private App or OAuth application and add the `crm.objects.custom.read` scope to your app's scopes. See HubSpot's instructions [here](https://developers.hubspot.com/docs/api/working-with-oauth#scopes).
-
-Then, go to the replication settings of your connection and click **refresh source schema** to pull in those new streams for syncing.
-
 <HideInUI>
 
 ## Supported sync modes
@@ -223,7 +202,7 @@ The HubSpot source connector supports the following streams:
 
 ### Notes on the `property_history` streams
 
-Even though the stream is Incremental, there are some record types that are not affected by the last sync timestamp pointer. For example records of type `CALCULATED` will allways have most recent timestamp equal to the requset time, so whenever you sync there will be a bunch of records in return.
+`Property_history` streams can be synced using an `Incremental` sync mode, which uses a cursor timestamp to determine which records have been updated since the previous sync. Within these streams, some fields types (ex. `CALCULATED` type) will always have a cursor timstamp that mirrors the time of the latest sync. This results in each sync including many more records than were necessarily changed since the previous sync.
 
 ### Notes on the `engagements` stream
 
@@ -242,11 +221,25 @@ Even though the stream is Incremental, there are some record types that are not
   - Fewer than 10,000 records are being synced
 - **EngagementsAll** if either of these criteria are not met.
 
-Because of this, the `engagements` stream can be slow to sync if it hasn't synced within the last 30 days and/or is generating large volumes of new data. We therefore recommend scheduling frequent syncs.
+Because of this, the `engagements` stream can be slow to sync if it hasn't synced within the last 30 days and/or is generating large volumes of new data. To accomodate for this limitation, we recommend scheduling more frequent syncs.
 
 ### Notes on the `Forms` and `Form Submissions` stream
 
-This stream sync only marketing forms. If you need other forms types try sync `Contacts Form Submissions`.
+This stream only syncs marketing forms. If you need other forms types, sync `Contacts Form Submissions`.
+
+### Notes on the `Custom CRM` Objects
+
+Custom CRM Objects and Custom Web Analytics will appear as streams available for sync, alongside the standard objects listed above.
+
+If you set up your connections before April 15th, 2023 (on Airbyte Cloud) or before 0.8.0 (OSS) then you'll need to do some additional work to sync custom CRM objects.
+
+First you need to give the connector some additional permissions:
+
+- **If you are using OAuth on Airbyte Cloud** go to the Hubspot source settings page in the Airbyte UI and re-authenticate via OAuth to allow Airbyte the permissions to access custom objects.
+
+- **If you are using OAuth on OSS or Private App auth** go into the Hubspot UI where you created your Private App or OAuth application and add the `crm.objects.custom.read` scope to your app's scopes. See HubSpot's instructions [here](https://developers.hubspot.com/docs/api/working-with-oauth#scopes).
+
+Then, go to the schema tab of your connection and click **refresh source schema** to pull in those new streams for syncing.
 
 ## Limitations & Troubleshooting
 
@@ -257,7 +250,7 @@ Expand to see details about Hubspot connector limitations and troubleshooting.
 
 ### Connector limitations
 
-#### Rate limiting
+### Rate limiting
 
 The connector is restricted by normal HubSpot [rate limitations](https://legacydocs.hubspot.com/apps/api_guidelines).
 
@@ -269,7 +262,6 @@ The connector is restricted by normal HubSpot [rate limitations](https://legacyd
 
 ### Troubleshooting
 
-- Consider checking out the following Hubspot tutorial: [Build a single customer view with open-source tools](https://airbyte.com/tutorials/single-customer-view).
 - **Enabling streams:** Some streams, such as `workflows`, need to be enabled before they can be read using a connector authenticated using an `API Key`. If reading a stream that is not enabled, a log message returned to the output and the sync operation will only sync the other streams available.
 
   Example of the output message when trying to read `workflows` stream with missing permissions for the `API Key`:
@@ -284,7 +276,9 @@ The connector is restricted by normal HubSpot [rate limitations](https://legacyd
   }
   ```
 
-- **Unnesting top level properties**: Since version 1.5.0, in order to not make the users query their destinations for complicated json fields, we duplicate most of nested data as top level fields.
+- **Hubspot object labels** In Hubspot, a label can be applied to a stream that differs from the original API name of the stream. Hubspot's UI shows the label of the stream, whereas Airbyte shows the name of the stream. If you are having issues seeing a particular stream your user should have access to, search for the `name` of the Hubspot object instead. 
+
+- **Unnesting top level properties**: Since version 1.5.0, in order to offer users access to nested fields, we also denest the top-level fields into individual fields in the destination. This is most commonly observed in the `properties` field, which is now split into each attribute in the destination. 
 
   For instance:
 
