diff --git a/README.md b/README.md index 7d55502..ff8a17b 100644 --- a/README.md +++ b/README.md @@ -8,37 +8,204 @@ ## Overview -[HubSpot ](https://www.hubspot.com/) is an AI-powered customer relationship management (CRM) platform. +[HubSpot](https://www.hubspot.com/) is an AI-powered customer relationship management (CRM) platform. The `ballerinax/module-ballerinax-hubspot.crm.extensions.timelines` connector offers APIs to connect and interact with the [ HubSpot CRM Timelines API](https://developers.hubspot.com/docs/reference/api/crm/extensions/timeline), specifically based on the [HubSpot REST API](https://developers.hubspot.com/docs/reference/api/overview). ## Setup guide -To use the HubSpot Properties 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. +To use the HubSpot CRM Timelines API, 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 +### 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 to a free account [here](https://developers.hubspot.com/get-started). -If you don't have a HubSpot Developer Account you can sign up to a free account [here](https://developers.hubspot.com/get-started) +If you have an account already, go to the [HubSpot developer portal](https://app.hubspot.com/) -### Step 2 (Optional): Create a Developer Test Account under your account +### Step 2: Create a developer test account (Optional) Within app developer accounts, you can create [developer test accounts](https://developers.hubspot.com/beta-docs/getting-started/account-types#developer-test-accounts) 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.** +> **Note:** These accounts are only for development and testing purposes. In production you should not use developer test accounts. + +1. Go to test account section from the left sidebar. + ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/test_acc_1.png) + +2. Click create developer test account. + ![Hubspot developer testacc](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/test_acc_2.png) + +3. In the dialogue box, give a name to your test account and click create. + ![Hubspot developer testacc3](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/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" + ![Hubspot app creation 1](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/create_app_1.png) + +2. Provide the necessary details, including the app name and description. + ![Hubspot app creation 2](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/create_app_2.png) + +### Step 4: Configure the authentication flow + +1. Move to the "Auth" Tab. + +2. In the "Scopes" section, add necessary scopes for your app using the "Add new scope" button. + ![Hubspot set scope](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/set_scope.png) + +3. Add your redirect URI in the relevant section. You can also use localhost addresses for local development purposes. Click create app. + ![Hubspot create app final](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/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. + ![Hubspot get credentials](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/get_credentials.png) + +### Step 6: Setup authentication flow + +Before proceeding with the quickstart, ensure you have obtained the necessary authentication credentials. + +#### Method 1: OAuth 2.0 authentication (access token) + +Some APIs require an access token for authentication. Follow these steps to obtain one: + +1. Create an authorization URL using the following format: + + ```markdown + https://app.hubspot.com/oauth/authorize?client_id=&scope=&redirect_uri= + ``` + + Replace the ``, ``, and `` with your specific value. + +2. Paste it in the browser and select your developer test account to install the app when prompted. +3. A code will be displayed in the browser. Copy the code. +4. Run the following curl command. Replace the ``, ``, and `` with your specific value. Use the code you received in the above step 3 as the ``. + + - 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=&redirect_uri=&client_id=&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=&redirect_uri=&client_id=&client_secret=' + ``` + + This command will return the access token necessary for API calls. + + ```json + { + "token_type": "bearer", + "refresh_token": "", + "access_token": "", + "expires_in": 1800 + } + ``` +5. Store the access token securely for use in your application. +#### Method 2: Developer API key authentication + +Some APIs use a developer API key as a query parameter for authentication. + +1. In your developer account, navigate to Keys -> Developer API key. It will list down the active API key that you can copy. + +![Hubspot get credentials](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/developer_key.png) + +2. Use the key by appending it to API requests as a query parameter: + +```text +https://api.hubapi.com/crm/v3/timeline/events?hapikey= +``` + +No OAuth flow is required for this authentication method. ## Quickstart -[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.) +To use the `HubSpot CRM Timelines` in your Ballerina application, update the `.bal` file as follows: + +### Step 1: Import the module + +Import the `hubspot.crm.extensions.timelines` module and `oauth2` module. + +```ballerina +import ballerina/oauth2; +import ballerinax/hubspot.crm.extensions.timelines as hstimeline; +``` + +### Step 2: Instantiate a new connector + +1. Instantiate a `hstimeline:OAuth2RefreshTokenGrantConfig` or `ApiKeysConfig` with the obtained credentials and initialize the connector with it. +Since different APIs use varying authentication mechanisms, initialize two separate clients to handle both OAuth 2.0 and developer API key authentication. + + ```ballerina + configurable string clientId = ?; + configurable string clientSecret = ?; + configurable string refreshToken = ?; + configurable string hapikey = ?; + configurable int appId = ?; + + + hstimeline:OAuth2RefreshTokenGrantConfig accessToken = { + clientId, + clientSecret, + refreshToken, + credentialBearer: oauth2:POST_BODY_BEARER + }; + + hstimeline:ApiKeysConfig apikeys = { + hapikey, + private\-app: "", + private\-app\-legacy: "" + }; + + final hstimeline:Client hubSpotTimelineOAuth2 = check new({auth: accessToken}); + final hstimeline:Client hubSpotTimelineApiKey = check new ({auth: apikeys}); + + ``` + +2. Create a `Config.toml` file and, configure the obtained credentials in the above steps as follows: + + ```toml + clientId = + clientSecret = + refreshToken = + hapikey = + appId = + + ``` + +### Step 3: Invoke the connector operation + +Now, utilize the available connector operations. A sample use case is shown below. + +#### Get all event templates + +```ballerina +public function main() returns error? { + hstimeline:CollectionResponseTimelineEventTemplateNoPaging response = check hubSpotTimelineApiKey->/[appIdSigned32]/event\-templates.get(); + io:println("Event Templates: ", response); +} +``` + +#### Run the Ballerina application + +```bash +bal run +``` ## Examples -The `HubSpot CRM Timelines` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/), covering the following use cases: +The `HubSpot CRM Timelines` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/), covering the following use cases: -[//]: # (TODO: Add examples) +1. [Event Creation](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/create-event): This example demonstrates how to create a timeline event template, retrieving existing events, and creating an event using the template with their details in a structured format. ## Build from the source @@ -46,8 +213,8 @@ The `HubSpot CRM Timelines` connector provides practical examples illustrating u 1. Download and install Java SE Development Kit (JDK) version 21. You can download it from either of the following sources: - * [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) - * [OpenJDK](https://adoptium.net/) + - [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) + - [OpenJDK](https://adoptium.net/) > **Note:** After installation, remember to set the `JAVA_HOME` environment variable to the directory where JDK was installed. @@ -128,7 +295,7 @@ All the contributors are encouraged to read the [Ballerina Code of Conduct](http ## Useful links -* For more information go to the [`hubspot.crm.extensions.timelines` package](https://central.ballerina.io/ballerinax/hubspot.crm.extensions.timelines/latest). -* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/). -* Chat live with us via our [Discord server](https://discord.gg/ballerinalang). -* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag. +- For more information go to the [`hubspot.crm.extensions.timelines` package](https://central.ballerina.io/ballerinax/hubspot.crm.extensions.timelines/latest). +- For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/). +- Chat live with us via our [Discord server](https://discord.gg/ballerinalang). +- Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag. diff --git a/ballerina/Ballerina.toml b/ballerina/Ballerina.toml index c291aac..d66f861 100644 --- a/ballerina/Ballerina.toml +++ b/ballerina/Ballerina.toml @@ -5,7 +5,7 @@ name = "hubspot.crm.extensions.timelines" version = "1.0.0" license = ["Apache-2.0"] authors = ["Ballerina"] -keywords = [] # TODO: Add keywords +keywords = ["hubspot", "crm", "timelines", "events",] # icon = "icon.png" # TODO: Add icon repository = "https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines" diff --git a/ballerina/Module.md b/ballerina/Module.md deleted file mode 100644 index 9a4aadb..0000000 --- a/ballerina/Module.md +++ /dev/null @@ -1,17 +0,0 @@ -## Overview - -[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.) - -## Setup guide - -[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.) - -## Quickstart - -[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.) - -## Examples - -The `HubSpot CRM Timelines` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/), covering the following use cases: - -[//]: # (TODO: Add examples) diff --git a/ballerina/Package.md b/ballerina/Package.md deleted file mode 100644 index 9a4aadb..0000000 --- a/ballerina/Package.md +++ /dev/null @@ -1,17 +0,0 @@ -## Overview - -[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.) - -## Setup guide - -[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.) - -## Quickstart - -[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.) - -## Examples - -The `HubSpot CRM Timelines` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/), covering the following use cases: - -[//]: # (TODO: Add examples) diff --git a/ballerina/README.md b/ballerina/README.md new file mode 100644 index 0000000..5a040c2 --- /dev/null +++ b/ballerina/README.md @@ -0,0 +1,200 @@ +## Overview + +[HubSpot](https://www.hubspot.com/) is an AI-powered customer relationship management (CRM) platform. + +The `ballerinax/module-ballerinax-hubspot.crm.extensions.timelines` connector offers APIs to connect and interact with the [ HubSpot CRM Timelines API](https://developers.hubspot.com/docs/reference/api/crm/extensions/timeline), specifically based on the [HubSpot REST API](https://developers.hubspot.com/docs/reference/api/overview). + +## Setup guide + +To use the HubSpot CRM Timelines API, 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 don't have a HubSpot developer account you can sign up to a free account [here](https://developers.hubspot.com/get-started). + +If you have an account already, go to the [HubSpot developer portal](https://app.hubspot.com/) + +### Step 2: Create a developer test account (Optional) + +Within app developer accounts, you can create [developer test accounts](https://developers.hubspot.com/beta-docs/getting-started/account-types#developer-test-accounts) 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 test account section from the left sidebar. + ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/test_acc_1.png) + +2. Click create developer test account. + ![Hubspot developer testacc](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/test_acc_2.png) + +3. In the dialogue box, give a name to your test account and click create. + ![Hubspot developer testacc3](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/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" + ![Hubspot app creation 1](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/create_app_1.png) + +2. Provide the necessary details, including the app name and description. + ![Hubspot app creation 2](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/create_app_2.png) + +### Step 4: Configure the authentication flow + +1. Move to the "Auth" Tab. + +2. In the "Scopes" section, add necessary scopes for your app using the "Add new scope" button. + ![Hubspot set scope](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/set_scope.png) + +3. Add your redirect URI in the relevant section. You can also use localhost addresses for local development purposes. Click create app. + ![Hubspot create app final](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/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. + ![Hubspot get credentials](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/get_credentials.png) + +### Step 6: Setup authentication flow + +Before proceeding with the quickstart, ensure you have obtained the necessary authentication credentials. + +#### Method 1: OAuth 2.0 authentication (access token) + +Some APIs require an access token for authentication. Follow these steps to obtain one: + +1. Create an authorization URL using the following format: + + ```markdown + https://app.hubspot.com/oauth/authorize?client_id=&scope=&redirect_uri= + ``` + + Replace the ``, ``, and `` with your specific value. + +2. Paste it in the browser and select your developer test account to install the app when prompted. +3. A code will be displayed in the browser. Copy the code. +4. Run the following curl command. Replace the ``, ``, and `` with your specific value. Use the code you received in the above step 3 as the ``. + + - 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=&redirect_uri=&client_id=&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=&redirect_uri=&client_id=&client_secret=' + ``` + + This command will return the access token necessary for API calls. + + ```json + { + "token_type": "bearer", + "refresh_token": "", + "access_token": "", + "expires_in": 1800 + } + ``` + +5. Store the access token securely for use in your application. + +#### Method 2: Developer API key authentication + +Some APIs use a developer API key as a query parameter for authentication. + +1. In your developer account, navigate to Keys -> Developer API key. It will list down the active API key that you can copy. + +![Hubspot get credentials](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/refs/heads/main/docs/resources/developer_key.png) + +2. Use the key by appending it to API requests as a query parameter: + +```text +https://api.hubapi.com/crm/v3/timeline/events?hapikey= +``` + +No OAuth flow is required for this authentication method. + +## Quickstart + +To use the `HubSpot CRM Timelines` in your Ballerina application, update the `.bal` file as follows: + +### Step 1: Import the module + +Import the `hubspot.crm.extensions.timelines` module and `oauth2` module. + +```ballerina +import ballerina/oauth2; +import ballerinax/hubspot.crm.extensions.timelines as hstimeline; +``` + +### Step 2: Instantiate a new connector + +1. Instantiate a `hstimeline:OAuth2RefreshTokenGrantConfig` or `ApiKeysConfig` with the obtained credentials and initialize the connector with it. +Since different APIs use varying authentication mechanisms, initialize two separate clients to handle both OAuth 2.0 and developer API key authentication. + + ```ballerina + configurable string clientId = ?; + configurable string clientSecret = ?; + configurable string refreshToken = ?; + configurable string hapikey = ?; + configurable int appId = ?; + + + hstimeline:OAuth2RefreshTokenGrantConfig accessToken = { + clientId, + clientSecret, + refreshToken, + credentialBearer: oauth2:POST_BODY_BEARER + }; + + hstimeline:ApiKeysConfig apikeys = { + hapikey, + private\-app: "", + private\-app\-legacy: "" + }; + + final hstimeline:Client hubSpotTimelineOAuth2 = check new({auth: accessToken}); + final hstimeline:Client hubSpotTimelineApiKey = check new ({auth: apikeys}); + + ``` + +2. Create a `Config.toml` file and, configure the obtained credentials in the above steps as follows: + + ```toml + clientId = + clientSecret = + refreshToken = + hapikey = + appId = + + ``` + +### Step 3: Invoke the connector operation + +Now, utilize the available connector operations. A sample use case is shown below. + +#### Get all event templates + +```ballerina +public function main() returns error? { + hstimeline:CollectionResponseTimelineEventTemplateNoPaging response = check hubSpotTimelineApiKey->/[appIdSigned32]/event\-templates.get(); + io:println("Event Templates: ", response); +} +``` + +#### Run the Ballerina application + +```bash +bal run +``` + +## Examples + +The `HubSpot CRM Timelines` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/), covering the following use cases: + +1. [Event Creation](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/create-event): This example demonstrates how to create a timeline event template, retrieving existing events, and creating an event using the template with their details in a structured format. diff --git a/docs/resources/create_app_1.png b/docs/resources/create_app_1.png new file mode 100644 index 0000000..dc6c160 Binary files /dev/null and b/docs/resources/create_app_1.png differ diff --git a/docs/resources/create_app_2.png b/docs/resources/create_app_2.png new file mode 100644 index 0000000..78ae3e4 Binary files /dev/null and b/docs/resources/create_app_2.png differ diff --git a/docs/resources/create_app_final.png b/docs/resources/create_app_final.png new file mode 100644 index 0000000..88713af Binary files /dev/null and b/docs/resources/create_app_final.png differ diff --git a/docs/resources/developer_key.png b/docs/resources/developer_key.png new file mode 100644 index 0000000..ec3a142 Binary files /dev/null and b/docs/resources/developer_key.png differ diff --git a/docs/resources/get_credentials.png b/docs/resources/get_credentials.png new file mode 100644 index 0000000..0c587a9 Binary files /dev/null and b/docs/resources/get_credentials.png differ diff --git a/docs/resources/set_scope.png b/docs/resources/set_scope.png new file mode 100644 index 0000000..0032ed3 Binary files /dev/null and b/docs/resources/set_scope.png differ diff --git a/docs/resources/test_acc_1.png b/docs/resources/test_acc_1.png new file mode 100644 index 0000000..d9317bd Binary files /dev/null and b/docs/resources/test_acc_1.png differ diff --git a/docs/resources/test_acc_2.png b/docs/resources/test_acc_2.png new file mode 100644 index 0000000..7d3acfc Binary files /dev/null and b/docs/resources/test_acc_2.png differ diff --git a/docs/resources/test_acc_3.png b/docs/resources/test_acc_3.png new file mode 100644 index 0000000..5301aa7 Binary files /dev/null and b/docs/resources/test_acc_3.png differ diff --git a/examples/README.md b/examples/README.md index 0e2f910..21b48af 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,14 +1,22 @@ # Examples -The `ballerinax/hubspot.crm.extensions.timelines` connector provides practical examples illustrating usage in various scenarios. +The `HubSpot CRM Timelines` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/), covering the following use cases: -[//]: # (TODO: Add examples) -1. -2. +1. [Event Creation](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/tree/main/examples/create-event): This example demonstrates how to create a timeline event template, retrieving existing events, and creating an event using the template with their details in a structured format. ## Prerequisites -[//]: # (TODO: Add prerequisites) +1. Generate HubSpot credentials to authenticate the connector as described in the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/blob/main/ballerina/Package.md#setup-guide). + +2. For each example, create a `Config.toml` file the related configuration. Here's an example of how your `Config.toml` file should look: + + ```toml + clientId = + clientSecret = + refreshToken = + hapikey = + appId = + ``` ## Running an example diff --git a/examples/create-event/Ballerina.toml b/examples/create-event/Ballerina.toml new file mode 100644 index 0000000..ea64b87 --- /dev/null +++ b/examples/create-event/Ballerina.toml @@ -0,0 +1,8 @@ +[package] +org = "wso2" +name = "create_evenTemplates" +version = "0.1.0" +distribution = "2201.11.0" + +[build-options] +observabilityIncluded = true diff --git a/examples/create-event/Dependencies.toml b/examples/create-event/Dependencies.toml new file mode 100644 index 0000000..9beef1a --- /dev/null +++ b/examples/create-event/Dependencies.toml @@ -0,0 +1,330 @@ +# AUTO-GENERATED FILE. DO NOT MODIFY. + +# This file is auto-generated by Ballerina for managing dependency versions. +# It should not be modified by hand. + +[ballerina] +dependencies-toml-version = "2" +distribution-version = "2201.11.0" + +[[package]] +org = "ballerina" +name = "auth" +version = "2.13.0" +dependencies = [ + {org = "ballerina", name = "crypto"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.array"}, + {org = "ballerina", name = "lang.string"}, + {org = "ballerina", name = "log"} +] + +[[package]] +org = "ballerina" +name = "cache" +version = "3.9.0" +dependencies = [ + {org = "ballerina", name = "constraint"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "task"}, + {org = "ballerina", name = "time"} +] + +[[package]] +org = "ballerina" +name = "constraint" +version = "1.6.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerina" +name = "crypto" +version = "2.8.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "time"} +] + +[[package]] +org = "ballerina" +name = "data.jsondata" +version = "1.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.object"} +] + +[[package]] +org = "ballerina" +name = "file" +version = "1.11.0" +dependencies = [ + {org = "ballerina", name = "io"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "os"}, + {org = "ballerina", name = "time"} +] + +[[package]] +org = "ballerina" +name = "http" +version = "2.13.3" +dependencies = [ + {org = "ballerina", name = "auth"}, + {org = "ballerina", name = "cache"}, + {org = "ballerina", name = "constraint"}, + {org = "ballerina", name = "crypto"}, + {org = "ballerina", name = "data.jsondata"}, + {org = "ballerina", name = "file"}, + {org = "ballerina", name = "io"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "jwt"}, + {org = "ballerina", name = "lang.array"}, + {org = "ballerina", name = "lang.decimal"}, + {org = "ballerina", name = "lang.int"}, + {org = "ballerina", name = "lang.regexp"}, + {org = "ballerina", name = "lang.runtime"}, + {org = "ballerina", name = "lang.string"}, + {org = "ballerina", name = "lang.value"}, + {org = "ballerina", name = "log"}, + {org = "ballerina", name = "mime"}, + {org = "ballerina", name = "oauth2"}, + {org = "ballerina", name = "observe"}, + {org = "ballerina", name = "time"}, + {org = "ballerina", name = "url"} +] + +[[package]] +org = "ballerina" +name = "io" +version = "1.7.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.value"} +] +modules = [ + {org = "ballerina", packageName = "io", moduleName = "io"} +] + +[[package]] +org = "ballerina" +name = "jballerina.java" +version = "0.0.0" + +[[package]] +org = "ballerina" +name = "jwt" +version = "2.14.0" +dependencies = [ + {org = "ballerina", name = "cache"}, + {org = "ballerina", name = "crypto"}, + {org = "ballerina", name = "io"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.int"}, + {org = "ballerina", name = "lang.string"}, + {org = "ballerina", name = "log"}, + {org = "ballerina", name = "time"} +] + +[[package]] +org = "ballerina" +name = "lang.__internal" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.object"} +] + +[[package]] +org = "ballerina" +name = "lang.array" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.__internal"} +] + +[[package]] +org = "ballerina" +name = "lang.decimal" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerina" +name = "lang.int" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.__internal"}, + {org = "ballerina", name = "lang.object"} +] + +[[package]] +org = "ballerina" +name = "lang.object" +version = "0.0.0" + +[[package]] +org = "ballerina" +name = "lang.regexp" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerina" +name = "lang.runtime" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] +modules = [ + {org = "ballerina", packageName = "lang.runtime", moduleName = "lang.runtime"} +] + +[[package]] +org = "ballerina" +name = "lang.string" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.regexp"} +] + +[[package]] +org = "ballerina" +name = "lang.value" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerina" +name = "log" +version = "2.11.0" +dependencies = [ + {org = "ballerina", name = "io"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.value"}, + {org = "ballerina", name = "observe"} +] + +[[package]] +org = "ballerina" +name = "mime" +version = "2.11.0" +dependencies = [ + {org = "ballerina", name = "io"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "lang.int"}, + {org = "ballerina", name = "log"} +] + +[[package]] +org = "ballerina" +name = "oauth2" +version = "2.13.0" +dependencies = [ + {org = "ballerina", name = "cache"}, + {org = "ballerina", name = "crypto"}, + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "log"}, + {org = "ballerina", name = "time"}, + {org = "ballerina", name = "url"} +] +modules = [ + {org = "ballerina", packageName = "oauth2", moduleName = "oauth2"} +] + +[[package]] +org = "ballerina" +name = "observe" +version = "1.4.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerina" +name = "os" +version = "1.9.0" +dependencies = [ + {org = "ballerina", name = "io"}, + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerina" +name = "task" +version = "2.6.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "time"} +] + +[[package]] +org = "ballerina" +name = "time" +version = "2.6.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerina" +name = "url" +version = "2.5.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"} +] + +[[package]] +org = "ballerinai" +name = "observe" +version = "0.0.0" +dependencies = [ + {org = "ballerina", name = "jballerina.java"}, + {org = "ballerina", name = "observe"} +] +modules = [ + {org = "ballerinai", packageName = "observe", moduleName = "observe"} +] + +[[package]] +org = "ballerinax" +name = "hubspot.crm.extensions.timelines" +version = "1.0.0" +dependencies = [ + {org = "ballerina", name = "http"}, + {org = "ballerina", name = "lang.runtime"}, + {org = "ballerina", name = "oauth2"}, + {org = "ballerina", name = "os"}, + {org = "ballerina", name = "url"}, + {org = "ballerinai", name = "observe"} +] +modules = [ + {org = "ballerinax", packageName = "hubspot.crm.extensions.timelines", moduleName = "hubspot.crm.extensions.timelines"} +] + +[[package]] +org = "thinuri" +name = "create_evenTemplates" +version = "0.1.0" +dependencies = [ + {org = "ballerina", name = "io"}, + {org = "ballerina", name = "lang.runtime"}, + {org = "ballerina", name = "oauth2"}, + {org = "ballerinai", name = "observe"}, + {org = "ballerinax", name = "hubspot.crm.extensions.timelines"} +] +modules = [ + {org = "thinuri", packageName = "create_evenTemplates", moduleName = "create_evenTemplates"} +] + diff --git a/examples/create-event/README.md b/examples/create-event/README.md new file mode 100644 index 0000000..4e3d2c6 --- /dev/null +++ b/examples/create-event/README.md @@ -0,0 +1,51 @@ +# Event Creation + +This example demonstrates how to create a timeline event template, retrieving existing events, and creating an event using the template with their details in a structured format. + +## Prerequisites + +1. Generate HubSpot credentials to authenticate the connector as described in the [Setup guide](https://github.com/ballerina-platform/module-ballerinax-hubspot.crm.extensions.timelines/blob/main/ballerina/Package.md#setup-guide). + +2. For each example, create a `Config.toml` file the related configuration. Here's an example of how your `Config.toml` file should look: + + ```toml + clientId = + clientSecret = + refreshToken = + hapikey = + appId = + ``` + +## Running an example + +Execute the following commands to build an example from the source: + +* To build an example: + + ```bash + bal build + ``` + +* To run an example: + + ```bash + bal run + ``` + +## Building the examples with the local module + +**Warning**: Due to the absence of support for reading local repositories for single Ballerina files, the Bala of the module is manually written to the central repository as a workaround. Consequently, the bash script may modify your local Ballerina repositories. + +Execute the following commands to build all the examples against the changes you have made to the module locally: + +* To build all the examples: + + ```bash + ./build.sh build + ``` + +* To run all the examples: + + ```bash + ./build.sh run + ``` diff --git a/examples/create-event/main.bal b/examples/create-event/main.bal new file mode 100644 index 0000000..a43feb2 --- /dev/null +++ b/examples/create-event/main.bal @@ -0,0 +1,122 @@ +// Copyright (c) 2025, WSO2 LLC. (http://www.wso2.com). +// +// WSO2 LLC. licenses this file to you under the Apache License, +// Version 2.0 (the "License"); you may not use this file except +// in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +import ballerina/io; +import ballerina/lang.runtime; +import ballerina/oauth2; +import ballerinax/hubspot.crm.extensions.timelines as hstimeline; + +configurable string clientId = ?; +configurable string clientSecret = ?; +configurable string refreshToken = ?; +configurable int appId = ?; +configurable string hapikey = ?; +final int:Signed32 appIdSigned32 = check appId.ensureType(); + +hstimeline:OAuth2RefreshTokenGrantConfig accessToken = { + clientId, + clientSecret, + refreshToken, + credentialBearer: oauth2:POST_BODY_BEARER +}; + +hstimeline:ApiKeysConfig apikeys = { + hapikey, + private\-app: "", + private\-app\-legacy: "" +}; + +final hstimeline:Client hubSpotTimelineOAuth2 = check new ({auth: accessToken}); +final hstimeline:Client hubSpotTimelineApiKey = check new ({auth: apikeys}); + +public function main() returns error? { + // Define a timeline event template + hstimeline:TimelineEventTemplateCreateRequest eventTemplate = { + detailTemplate: "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}\n\n#### Questions\n{{#each extraData.questions}}\n **{{question}}**: {{answer}}\n{{/each}}", + name: "PetSpot Registration", + tokens: [ + { + name: "petName", + 'type: "string", + label: "Pet Name" + }, + { + name: "petAge", + 'type: "number", + label: "Pet Age" + }, + { + name: "petColor", + 'type: "enumeration", + label: "Pet Color", + options: [ + {label: "White", value: "white"}, + {label: "Black", value: "black"}, + {label: "Brown", value: "brown"}, + {label: "Other", value: "other"} + ] + } + ], + headerTemplate: "Registered for [{{petName}}](https://my.petspot.com/pets/{{petName}})", + objectType: "contacts" + }; + // Create the template in HubSpot + hstimeline:TimelineEventTemplate eventTimelineResponse = check hubSpotTimelineApiKey->/[appIdSigned32]/event\-templates.post(eventTemplate); + io:println("Event Template Created: ", eventTimelineResponse.id); + string eventTemplateId = eventTimelineResponse.id; + + runtime:sleep(60); // Pause execution for 60 seconds to allow template creation. + + //Get all event templates + hstimeline:CollectionResponseTimelineEventTemplateNoPaging eventTemplatesResponse = check hubSpotTimelineApiKey->/[appIdSigned32]/event\-templates.get(); + io:println("Event Templates: ", eventTemplatesResponse); + + // Create an Event + hstimeline:TimelineEvent event = { + eventTemplateId, + domain: "string", + id: "string", + utk: "string", + email: "art3mis-pup@petspot.com", + timestamp: "2025-02-14T09:12:09.990Z", + extraData: { + "questions": [ + { + "answer": "Bark!", + "question": "Who's a good girl?" + }, + { + "answer": "Woof!", + "question": "Do you wanna go on a walk?" + } + ] + }, + timelineIFrame: { + linkLabel: "View Art3mis", + headerLabel: "Art3mis dog", + width: 600, + url: "https://my.petspot.com/pets/Art3mis", + height: 400 + }, + tokens: { + "petAge": "3", + "petName": "Art3mis", + "petColor": "black" + } + }; + hstimeline:TimelineEventResponse eventResponse = check hubSpotTimelineOAuth2->/events.post(event); + io:println("Event Created: ", eventResponse.id); +}