diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 9ba05ce1c10..41435465eb0 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -79,6 +79,29 @@ export default defineConfig({ ], collapsed: true, }, + { + label: 'Generate Component', + items: [ + {label: 'Overview', link: '/developer_guide/generate_component/overview'}, + {label: 'Initial Setup', link: '/developer_guide/generate_component/initial_setup'}, + { + label: 'OpenAPI Specification', + link: '/developer_guide/generate_component/open_api_specification' + }, + { + label: 'Customize Component', + link: '/developer_guide/generate_component/customize_component' + }, + ], + collapsed: true, + }, + { + label: 'Testing Triggers', + items: [ + {label: 'Working with Triggers', link: '/developer_guide/testing_triggers/triggers'}, + ], + collapsed: true, + }, { label: 'Component Specification', items: [ diff --git a/docs/src/content/docs/developer_guide/component_specification/connection.md b/docs/src/content/docs/developer_guide/component_specification/connection.md index 57833ae549d..4747a54806a 100644 --- a/docs/src/content/docs/developer_guide/component_specification/connection.md +++ b/docs/src/content/docs/developer_guide/component_specification/connection.md @@ -8,3 +8,73 @@ The connection definition is used to specify the properties of a connection. Bel - `authorizations(ModifiableAuthorization... authorizations)` - Specifies the authorization mechanisms required for the connection, allowing you to define multiple authorization types such as OAuth2, API Key, or Basic Auth. - `baseUri(BaseUriFunction baseUri)` - Sets the base URI for the connection, which is the root URL used for all API requests made through this connection. - `version(int version)` - Defines the version number of the connection, useful for managing changes and updates to the connection configuration over time. + +## Authorizations + +Each authorization is defined under the `ModifiableAuthorization` class which is designed to handle the authorization for components. + +### Modifiable Authorization + +- `authorization(AuthorizationType authorizationType)` - Initializes a new `ModifiableAuthorization` with the specified authorization type. This is the starting point for configuring an authorization. +- `apply(ApplyFunction apply)` - Sets the function that applies the acquired authorization credentials to requests. This function ensures that requests are properly authenticated using the obtained credentials. +- `authorizationUrl(AuthorizationUrlFunction authorizationUrl)` - Sets the function that provides the authorization URL. This URL is used to initiate the authorization process, often involving user consent. +- `description(String description)` - Sets a human-readable description of the authorization. This can be used for documentation or display purposes. +- `refreshTokenFunction(RefreshTokenFunction refreshTokenFunction)` - Sets the function responsible for handling refresh tokens. Refresh tokens are used to obtain new access tokens without re-authenticating the user. +- `properties(P... properties)` - Sets a list of properties associated with the authorization. These properties can include configuration options or metadata. +- `refreshUrl(RefreshUrlFunction refreshUrl)` - Sets the function that provides the URL for refreshing authorization credentials. This URL is used to obtain new tokens or credentials. +- `scopes(ScopesFunction scopes)` - Sets the function that defines the scopes of access requested during authorization. Scopes specify the permissions granted to the application. +- `title(String title)` - Sets a title for the authorization. This can be used for display purposes or to distinguish between different authorizations. +- `tokenUrl(TokenUrlFunction tokenUrl)` - Sets the function that provides the token URL. This URL is used to exchange authorization codes for access tokens in OAuth2 flows. + +### Examples + +Each authorization type has different properties that are required for successful authorization. Below are examples for common authorization types, demonstrating how to configure them effectively. + +#### Basic Auth + +Basic Auth is a simple authentication scheme built into the HTTP protocol. It requires a username and password, which are sent with each request. + +``` +authorization(AuthorizationType.BASIC_AUTH) + .title("Basic Auth") + .properties( + string(USERNAME) + .label("Username") + .required(true), + string(PASSWORD) + .label("Password") + .required(true)) +``` + +#### Bearer Token + +Bearer Token authentication involves sending a token with each request. This token is typically obtained from an authorization server and represents the user's identity. + +``` +authorization(AuthorizationType.BEARER_TOKEN) + .title("Bearer Token") + .properties( + string(TOKEN) + .label("Token") + .required(true)) +``` + +#### OAuth2 Authorization + +OAuth2 Authorization Code is a robust authorization framework that allows third-party applications to obtain limited access to a web service. It involves redirecting the user to an authorization server to obtain an authorization code, which is then exchanged for an access token. + +``` +authorization(AuthorizationType.OAUTH2_AUTHORIZATION_CODE) + .title("OAuth2 Authorization Code") + .properties( + string(CLIENT_ID) + .label("Client Id") + .required(true), + string(CLIENT_SECRET) + .label("Client Secret") + .required(true)) + .authorizationUrl((connectionParameters, context) -> "authorization url") + .scopes((connection, context) -> List.of("scope1", "scope2")) + .tokenUrl((connectionParameters, context) -> "token url") + .refreshUrl((connectionParameters, context) -> "refresh url") +``` diff --git a/docs/src/content/docs/developer_guide/components/component_generator.md b/docs/src/content/docs/developer_guide/components/component_generator.md deleted file mode 100644 index 872bb3fee6d..00000000000 --- a/docs/src/content/docs/developer_guide/components/component_generator.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Component generator" -description: "This is an application that helps you with generating components from OpenApi specifications." ---- - -# ByteChef command-line application - -This is an application that helps you with generating components from OpenApi specifications. It is work in progress. Until the app is published, use ```bytechef.sh``` script to execute the app. - -## Step-by-step guide to generate connector - -1. Crete new package with name of your connector in `server/apps/libs/modules/components/yourconnector` -2. Inside your new package create `openapi.yaml` file and write [OpenAPI specification](https://swagger.io/specification/) for your connector. -3. Change working directory to the `BYTECHEF_HOME/cli/cli-app` folder. -4. Generate YourConnector component/connector by executing the following command: - ```bash - $ ./bytechef.sh component init --open-api-path ../../server/libs/modules/components/yourconnector/openapi.yaml --output-path ../../server/libs/modules/components --name yourconnector - ``` -### Setup gradle -5. In file `bytechef/settings.gradle.kts`, add line: `include("server:libs:modules:components:yourconnector")` -6. In both files `bytechef/server/ee/apps/worker-app/build.gradle.kts` and `bytechef/server/apps/server-app/build.gradle.kts`, add line `implementation(project(":server:libs:modules:components:yourconnector"))` -7. Load gradle changes. After that IntelliJ should recognize your connector as a java module. - -### Connector icon -8. Find and download from internet the user interface icon in .svg format for your connector and put it in `server/libs/modules/components/yourconnector/src/main/resources/assets/yourconnector.svg` -9. In `YourConnectorComponentHandler.class` override method `modifyComponent(ModifiableComponentDefinition modifiableComponentDefinition)` with - ``` - return modifiableComponentDefinition - .customAction(true) - .icon("path:assets/yourconnector.svg"); - ``` -### Connection -If your authentication has some custom parameters then in `YourConnectorComponentHandler.class` override method `modifyConnection(ModifiableConnectionDefinition modifiableConnectionDefinition)`. -For example, look at `ShopifyComponentHandler.class`, `DiscordComponentHandler.class` or `PipelinerComponentHandler.class`. - -### Dynamic options -Similarly, if some parameters should have dynamic options then in `YourConnectorComponentHandler.class` override method `modifyProperty(ActionDefinition actionDefinition, ModifiableProperty modifiableProperty)`. -For example, look at `ShopifyComponentHandler.class`. - -### Dynamic properties -To mark some object as `dynamic properties` type, set `x-property-type: "dynamicProperties"` extension as part of the object definition. diff --git a/docs/src/content/docs/developer_guide/components/triggers.md b/docs/src/content/docs/developer_guide/components/triggers.md deleted file mode 100644 index b6c2e522fc3..00000000000 --- a/docs/src/content/docs/developer_guide/components/triggers.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Working with Triggers" -description: "Working with Triggers as a developer" ---- - -## Before you start testing Triggers -- download [ngrok](https://ngrok.com/download) -- open terminal and type `ngrok http http://127.0.0.1:9555` -- copy the first address under Forwarding -![ngork example](./ngrok.png) - -### If you are on Intellij -- open bytechef code -- go to `bytechef/server/apps/server-app/src/main/resources/config` , create a file called `application-local.yml` (Pay attention that `application-local.yml` is optional, git ignored file, and corresponds to local spring profile. This one shouldn’t miss activating `local` profile on springBoot startup) -- it is important to add local to active profiles in configuration -![intellij_scr](./intellij_scr.png) - -- paste this code in `application-local.yml`: -``` -bytechef: - webhook-url: (first address under Forwarding)/webhooks/{id} -``` -- run Bytechef - -### If you are not on Intellij -- paste this code in shell: -``` -export BYTECHEF_WEBHOOK_URL=(first address under Forwarding)/webhooks/{id} -``` -- run Bytechef diff --git a/docs/src/content/docs/developer_guide/generate_component/customize_component.md b/docs/src/content/docs/developer_guide/generate_component/customize_component.md new file mode 100644 index 00000000000..a17dfe2a924 --- /dev/null +++ b/docs/src/content/docs/developer_guide/generate_component/customize_component.md @@ -0,0 +1,32 @@ +--- +title: "Customize Component" +--- + +### Connector Icon + +1. Find an Icon: + - Search for a suitable user interface icon for your component in `.svg` format. + +2. Save the Icon: + - Place the icon in the following directory: `server/libs/modules/components/newcomponent/src/main/resources/assets/newcomponent.svg`. + +3. Update Component Handler: + - In `NewComponentComponentHandler.class`, override the `modifyComponent(ModifiableComponentDefinition modifiableComponentDefinition)` method: + ```java + @Override + public ModifiableComponentDefinition modifyComponent(ModifiableComponentDefinition modifiableComponentDefinition) { + return modifiableComponentDefinition.icon("path:assets/newcomponent.svg"); + } + ``` + +### Connection + +If your component requires custom authentication parameters, override the `modifyConnection(ModifiableConnectionDefinition modifiableConnectionDefinition)` method in `NewComponentComponentHandler.class`. + +Refer to examples like [`ShopifyComponentHandler.class`](https://github.com/bytechefhq/bytechef/blob/master/server/libs/modules/components/shopify/src/main/java/com/bytechef/component/shopify/ShopifyComponentHandler.java#L72), [`DiscordComponentHandler.class`](https://github.com/bytechefhq/bytechef/blob/master/server/libs/modules/components/discord/src/main/java/com/bytechef/component/discord/DiscordComponentHandler.java#L92), or [`PipelinerComponentHandler.class`](https://github.com/bytechefhq/bytechef/blob/master/server/libs/modules/components/pipeliner/src/main/java/com/bytechef/component/pipeliner/PipelinerComponentHandler.java#L57) for guidance. + +### Dynamic options + +For parameters that require dynamic options, override the `modifyProperty(ActionDefinition actionDefinition, ModifiableProperty modifiableProperty)` method in `NewComponentComponentHandler.class`. + +Check examples such as [`ShopifyComponentHandler.class`](https://github.com/bytechefhq/bytechef/blob/master/server/libs/modules/components/shopify/src/main/java/com/bytechef/component/shopify/ShopifyComponentHandler.java#L96) for implementation details. diff --git a/docs/src/content/docs/developer_guide/generate_component/initial_setup.md b/docs/src/content/docs/developer_guide/generate_component/initial_setup.md new file mode 100644 index 00000000000..ac6c258485d --- /dev/null +++ b/docs/src/content/docs/developer_guide/generate_component/initial_setup.md @@ -0,0 +1,26 @@ +--- +title: "Initial Setup" +--- + +This section provides a clear step-by-step guide for setting up a new component in your project, ensuring it is properly integrated into the build system and recognized by the IDE. + +1. Create a New Package: + - Navigate to `server/apps/libs/modules/components/`. + - Create a new package with the name of your component, e.g., `newcomponent`. + +2. Update Settings: + - Open `bytechef/settings.gradle.kts`. + - Add the following line to include your new component in the build process: + ```kotlin + include("server:libs:modules:components:newcomponent") + ``` + +3. Modify Build Files: + - Open `bytechef/server/ee/apps/worker-app/build.gradle.kts` and `bytechef/server/apps/server-app/build.gradle.kts`. + - Add the following line to both files to ensure your component is included as a dependency: + ```kotlin + implementation(project(":server:libs:modules:components:newcomponent")) + ``` +4. Load Gradle Changes: + - Refresh or reload the Gradle project in IntelliJ IDEA. + - This step ensures that IntelliJ recognizes your new component as a Java module, allowing you to work with it seamlessly within the IDE. diff --git a/docs/src/content/docs/developer_guide/generate_component/open_api_specification.md b/docs/src/content/docs/developer_guide/generate_component/open_api_specification.md new file mode 100644 index 00000000000..3881bb06759 --- /dev/null +++ b/docs/src/content/docs/developer_guide/generate_component/open_api_specification.md @@ -0,0 +1,17 @@ +--- +title: "OpenAPI Specification" +--- + +1. Create OpenAPI Specification: + - Inside your new package, create an `openapi.yaml` file. + - Write the [OpenAPI specification](https://swagger.io/specification/) for your component to define its API structure and endpoints. + +2. Navigate to CLI Directory: + - Change your working directory to the `BYTECHEF_HOME/cli/cli-app` folder. + +3. Generate Component: + - Execute the following command to generate the `NewComponent` in the `newcomponent` directory: + ```bash + ./bytechef.sh component init --open-api-path ../../server/libs/modules/components/newcomponent/openapi.yaml --output-path ../../server/libs/modules/components --name newcomponent + ``` + - This command initializes the component based on the OpenAPI specification, placing the generated files in the specified output path. diff --git a/docs/src/content/docs/developer_guide/generate_component/overview.md b/docs/src/content/docs/developer_guide/generate_component/overview.md new file mode 100644 index 00000000000..244ce006381 --- /dev/null +++ b/docs/src/content/docs/developer_guide/generate_component/overview.md @@ -0,0 +1,7 @@ +--- +title: "Overview" +--- + +In the following steps, we will learn how to generate a new component using our application. This application is designed to assist you in generating components from OpenAPI specifications efficiently and accurately. + +OpenAPI, formerly known as Swagger, is a specification for building APIs that allows developers to define their API's structure in a standardized format. By using this application, you can streamline the process of creating components by automatically generating code based on your OpenAPI definitions. diff --git a/docs/src/content/docs/developer_guide/components/intellij_scr.png b/docs/src/content/docs/developer_guide/testing_triggers/intellij_scr.png similarity index 100% rename from docs/src/content/docs/developer_guide/components/intellij_scr.png rename to docs/src/content/docs/developer_guide/testing_triggers/intellij_scr.png diff --git a/docs/src/content/docs/developer_guide/components/ngrok.png b/docs/src/content/docs/developer_guide/testing_triggers/ngrok.png similarity index 100% rename from docs/src/content/docs/developer_guide/components/ngrok.png rename to docs/src/content/docs/developer_guide/testing_triggers/ngrok.png diff --git a/docs/src/content/docs/developer_guide/testing_triggers/triggers.md b/docs/src/content/docs/developer_guide/testing_triggers/triggers.md new file mode 100644 index 00000000000..1beeab0635b --- /dev/null +++ b/docs/src/content/docs/developer_guide/testing_triggers/triggers.md @@ -0,0 +1,45 @@ +--- +title: "Working with Triggers" +description: "Working with Triggers as a developer" +--- + +## Download and Set Up ngrok + +1. Download ngrok + - Visit [ngrok's download page](https://ngrok.com/download) and download the appropriate version for your operating system +2. Start ngrok + - Open a terminal and run the following command to start ngrok: + ```bash + ngrok http http://127.0.0.1:9555 + ``` + - Copy the first address listed under "Forwarding". This will be used as your webhook URL. + ![ngork example](ngrok.png) + +## If You Are Using IntelliJ IDEA + +1. Open Bytechef Codebase: + - Navigate to bytechef/server/apps/server-app/src/main/resources/config. +2. Create Local Configuration: + - Create a file named `application-local.yml`. + - Note: `application-local.yml` is optional, git-ignored, and corresponds to the `local` Spring profile. Ensure the `local` profile is activated on Spring Boot startup. +3. Configure Webhook URL: + - Add the following configuration to `application-local.yml`, replacing `(first address under Forwarding)` with the copied ngrok URL: + ``` + bytechef: + webhook-url: (first address under Forwarding)/webhooks/{id} + ``` +4. Activate Local Profile: + +- Ensure that the `local` profile is added to active profiles in your IntelliJ configuration. + ![intellij_scr](intellij_scr.png) + +5. Start the ByteChef application. + +## If You Are Not Using IntelliJ + +1. Set Webhook URL: + - Open a terminal and paste the following command, replacing (first address under Forwarding) with the copied ngrok URL: + ``` + export BYTECHEF_WEBHOOK_URL=(first address under Forwarding)/webhooks/{id} + ``` +2. Start the ByteChef application.