Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate Client using OpenAPI spec tool, Update Setup Guide and Quickstart #2

Merged
merged 72 commits into from
Jan 16, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
72 commits
Select commit Hold shift + click to select a range
8f81eb5
Generate client code using Ballerina OpenAPI tool
sajitha-tj Dec 17, 2024
a223a5d
[Automated] Update the toml files
sajitha-tj Dec 19, 2024
5382714
Succesfully build the project
sajitha-tj Dec 19, 2024
e33bc2d
[Automated] Update the toml files
sajitha-tj Dec 20, 2024
89119c1
Update package.md file
sajitha-tj Dec 20, 2024
0c916b8
update folder structure of docs
sajitha-tj Dec 20, 2024
71edd2a
[Automated] Update the toml files
sajitha-tj Dec 20, 2024
88bae7a
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
e8f67e2
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
fc2b660
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
611795f
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
6089d34
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
05ebe40
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
2eed490
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
f998b84
[Automated] Update the toml files
sajitha-tj Jan 2, 2025
a6f4dab
Add test cases for some api endpoints
sajitha-tj Jan 3, 2025
c07b3ba
Update package.md
sajitha-tj Jan 3, 2025
bd63241
Add sanitations to the OpenAPI specs
sajitha-tj Jan 3, 2025
41ed355
Update ballerina client after sanitations of openapi spec
sajitha-tj Jan 3, 2025
c57e157
[Automated] Update the toml files
sajitha-tj Jan 3, 2025
5e67e8d
[Automated] Update the toml files
sajitha-tj Jan 6, 2025
3e9e418
[Automated] Update the toml files
sajitha-tj Jan 6, 2025
351babc
Added new test cases for other endpoints
sajitha-tj Jan 6, 2025
4b5c1a2
Add new line at the end of file
sajitha-tj Jan 6, 2025
be968e1
Do sanitations on open API specs
sajitha-tj Jan 6, 2025
d02d126
Add minor changes in package.md file
sajitha-tj Jan 6, 2025
e773018
Add test cases for more API endpoints
sajitha-tj Jan 6, 2025
c808a8a
Change client methods from resource to remote to fix ambiguity issue
sajitha-tj Jan 7, 2025
3a9d066
format tests.bal using bal format command
sajitha-tj Jan 7, 2025
0470213
Update sanitations.md file
sajitha-tj Jan 7, 2025
5ffaed1
Add an example usecase of the CRM lists connector
sajitha-tj Jan 8, 2025
ff8ee73
Update test cases
sajitha-tj Jan 8, 2025
7c977a2
Format example code with bal format command
sajitha-tj Jan 8, 2025
fdb76fe
Update ballerina/Package.md
sajitha-tj Jan 8, 2025
627601f
Update ballerina/Package.md
sajitha-tj Jan 8, 2025
06b4302
Merge branch 'main' of https://github.com/sajitha-tj/module-ballerina…
sajitha-tj Jan 8, 2025
199344e
Update package.md file
sajitha-tj Jan 8, 2025
3290d95
Update Package.md file
sajitha-tj Jan 8, 2025
2e03824
Update Package.md file
sajitha-tj Jan 9, 2025
f3f6cf2
Update tests with better assertions
sajitha-tj Jan 9, 2025
d20ad6c
Update examples code and remove local dependency from Ballerina.toml
sajitha-tj Jan 9, 2025
44e0310
Update Readme file for examples
sajitha-tj Jan 9, 2025
7ae109c
Add another example usecase of the connector
sajitha-tj Jan 9, 2025
12e552a
Update readme file for the new example
sajitha-tj Jan 9, 2025
5afd474
Format leads_tracker example with bal format
sajitha-tj Jan 9, 2025
fbedf9f
Remove local dependencies from Ballerina.toml file
sajitha-tj Jan 9, 2025
d002971
Update README.md and some other documentations
sajitha-tj Jan 9, 2025
b16fa74
Update sanitations.md
sajitha-tj Jan 9, 2025
8497519
Replace relative paths of images in docs with absolute paths
sajitha-tj Jan 9, 2025
a02a5e7
Add a mock service for running mock tests
sajitha-tj Jan 9, 2025
42f0cea
Fix spelling errors on documentations
sajitha-tj Jan 9, 2025
d920614
Update README.md
sajitha-tj Jan 9, 2025
e74d676
Merge branch 'main' of https://github.com/sajitha-tj/module-ballerina…
sajitha-tj Jan 9, 2025
a051732
Update documentations
sajitha-tj Jan 9, 2025
2eb665a
Update ballerina/tests/tests.bal
sajitha-tj Jan 9, 2025
7328b9a
Merge branch 'main' of https://github.com/sajitha-tj/module-ballerina…
sajitha-tj Jan 9, 2025
a1016b3
Remove parenthesis from if statements
sajitha-tj Jan 9, 2025
290d00e
Update example code as per to PR reviews
sajitha-tj Jan 9, 2025
bdf091a
Update leads_tracker example code
sajitha-tj Jan 9, 2025
21653a4
Update documents of examples
sajitha-tj Jan 9, 2025
ca54975
Update documentations
sajitha-tj Jan 10, 2025
055705a
Correct grammar and spelling mistakes in the docs
sajitha-tj Jan 10, 2025
ee9f63b
[Automated] Update the toml files
sajitha-tj Jan 10, 2025
a02b9b1
Add hubspot icon
sajitha-tj Jan 10, 2025
df40d8c
Update tests to work with mock server
sajitha-tj Jan 10, 2025
905536d
Update Ballerina.toml to add hubspot icon
sajitha-tj Jan 10, 2025
e105610
[Automated] Update the toml files
sajitha-tj Jan 10, 2025
d363ea0
Update mock_service.bal file
sajitha-tj Jan 10, 2025
8fcb58d
Update the license
sajitha-tj Jan 10, 2025
a2e8882
Do minor changes on docs
sajitha-tj Jan 10, 2025
beb5b5c
Fix tests with mock server
sajitha-tj Jan 16, 2025
98b218d
[Automated] Update the toml files
sajitha-tj Jan 16, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 170 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,186 @@

## Overview

[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.)
[HubSpot](https://www.hubspot.com/) is an AI-powered customer relationship management (CRM) platform.

The `ballerinax/hubspot.crm.lists` offers APIs to connect and interact with the [HubSpot CRM Lists API](https://developers.hubspot.com/docs/reference/api/crm/lists) endpoints, specifically based on the [HubSpot REST API](https://developers.hubspot.com/docs/reference/api/overview)

## Setup guide

[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.)
To use the HubSpot CRM Lists connector, you must have access to the HubSpot API through a HubSpot developer account and a HubSpot App under it. Therefore you need to register for a developer account at HubSpot if you don't have one already.

### Step 1: Create/Login to a HubSpot Developer Account

If you have an account already, go to the [HubSpot developer portal](https://app.hubspot.com/)

If you don't have a HubSpot Developer Account you can sign up for a free account [here](https://developers.hubspot.com/get-started)

### Step 2 (Optional): Create a Developer Test Account

Within app developer accounts, you can create a [developer test account](https://developers.hubspot.com/beta-docs/getting-started/account-types#developer-test-accounts) under your account to test apps and integrations without affecting any real HubSpot data.

> **Note:** These accounts are only for development and testing purposes. In production, you should not use Developer Test Accounts.

1. Go to the Test Account section from the left sidebar.

![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/test_acc_1.png)

2. Click Create developer test account.

![Creating a hubspot test account](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/test_acc_2.png)

3. In the dialogue box, give a name to your test account and click "Create".

![Adding a name and description for the test account](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/test_acc_3.png)

### Step 3: Create a HubSpot App under your account.

1. In your developer account, navigate to the "Apps" section. Click on "Create App"

![Creating a new App](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/create_app_1.png)

2. Provide the necessary details, including the app name and description.

### Step 4: Configure the Authentication Flow.

1. Move to the Auth Tab.

![Selecting the Auth tab](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/create_app_2.png)

2. In the Scopes section, add the following scopes for your app using the "Add new scope" button.

* `crm.lists.read`
* `crm.lists.write`
* `cms.membership.access_groups.write`

![List of scopes](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/scope_set.png)

The scopes listed above are the mandatory scopes needed to use the HubSpot CRM Lists API. However, you may need to add additional scopes based on your use case. For example, if you are working with contacts, you may need to add `crm.objects.contacts.read` and `crm.objects.contacts.write` scopes as well.

3. Add your Redirect URI in the relevant section. You can also use `localhost` addresses for local development purposes. Click "Create App".

![Adding the redirect URI and save](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/create_app_final.png)

### Step 5: Get your Client ID and Client Secret

- Navigate to the Auth section of your app. Make sure to save the provided Client ID and Client Secret.

![Client ID and secret of the App](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/get_credentials.png)

### Step 6: Setup Authentication Flow

Before proceeding with the Quickstart, ensure you have obtained the Access Token using the following steps:

1. Create an authorization URL using the following format:

```
https://app.hubspot.com/oauth/authorize?client_id=<YOUR_CLIENT_ID>&scope=<YOUR_SCOPES>&redirect_uri=<YOUR_REDIRECT_URI>
```

Replace the `<YOUR_CLIENT_ID>`, `<YOUR_REDIRECT_URI>` and `<YOUR_SCOPES>` with your specific value.

2. Paste it in the browser and select your developer test account to install the app when prompted. Provide consent for all scopes needed.

![Selecting the App for OAuth process](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/main/docs/setup/resources/install_app.png)

3. A code will be displayed in the browser. Copy the code.

4. Run the following curl command. Replace the `<YOUR_CLIENT_ID>`, `<YOUR_REDIRECT_URI`> and `<YOUR_CLIENT_SECRET>` with your specific value. Use the code you received in the above step 3 as the `<CODE>`.

- Linux/macOS

```bash
curl --request POST \
--url https://api.hubapi.com/oauth/v1/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code&code=<CODE>&redirect_uri=<YOUR_REDIRECT_URI>&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>'
```

- Windows

```bash
curl --request POST ^
--url https://api.hubapi.com/oauth/v1/token ^
--header 'content-type: application/x-www-form-urlencoded' ^
--data 'grant_type=authorization_code&code=<CODE>&redirect_uri=<YOUR_REDIRECT_URI>&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>'
```

This command will return the access token necessary for API calls.

```json
{
"token_type": "bearer",
"refresh_token": "<Refresh Token>",
"access_token": "<Access Token>",
"expires_in": 1800
}
```

5. Store the access token securely for use in your application.

## Quickstart

[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.)
To use the `HubSpot CRM Lists` connector in your Ballerina application, update the `.bal` file as follows:

### Step 1: Import the module

Import the `hubspot.crm.lists` module and `oauth2` module.

```ballerina
import ballerinax/hubspot.crm.lists as hslists;
import ballerina/oauth2;
```

### Step 2: Instantiate a new connector

1. Create a `Config.toml` file and, configure the obtained credentials in the above steps as follows:

```toml
clientId = <Client Id>
clientSecret = <Client Secret>
refreshToken = <Refresh Token>
```

2. Instantiate an `OAuth2RefreshTokenGrantConfig` with the obtained credentials and initialize the connector with it.

```ballerina
configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

OAuth2RefreshTokenGrantConfig auth = {
clientId,
clientSecret,
refreshToken,
credentialBearer: oauth2:POST_BODY_BEARER
};

final hslists:Client crmListClient = check new ({auth});
```

### Step 3: Invoke the connector operation

Now, utilize the available connector operations. A sample use case is shown below.

#### Create a CRM List

```ballerina
public function main() returns error? {
hslists:ListCreateRequest payload = {
objectTypeId: "0-1",
processingType: "MANUAL",
name: "my-test-list"
};
hslists:ListCreateResponse response = check crmListClient->/crm/v3/lists.post(payload);
}
```

## Examples

The `HubSpot CRM Lists` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-hubspot.crm.lists/tree/main/examples/), covering the following use cases:

[//]: # (TODO: Add examples)
1. [Customer Support Ticket Manager](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/tree/main/examples/customer_support_tickets_manager) - Integrates with HubSpot CRM Lists to create filtered lists of customer support tickets based on the priority level of the ticket.
2. [Leads Tracker](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.lists/tree/main/examples/leads_tracker) - Integrates with HubSpot CRM Lists to create Manual Lists and add leads(contacts) to the lists.

## Build from the source

Expand All @@ -41,7 +206,7 @@ The `HubSpot CRM Lists` connector provides practical examples illustrating usage

> **Note**: Ensure that the Docker daemon is running before executing any tests.

4. Export Github Personal access token with read package permissions as follows,
4. Export the GitHub Personal access token with read package permissions as follows,

```bash
export packageUser=<Username>
Expand Down
6 changes: 3 additions & 3 deletions ballerina/Ballerina.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ name = "hubspot.crm.lists"
version = "0.1.0"
license = ["Apache-2.0"]
authors = ["Ballerina"]
keywords = []
# icon = "icon.png" # TODO: update icon.png
keywords = ["hubspot", "crm", "lists"]
icon = "icon.png"
repository = "https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.lists"

[build-options]
observabilityIncluded = true

[platform.java21]
[platform.java17]
graalvmCompatible = true
Loading
Loading