https://github.com/camunda/connector-template-outbound
Template repository to create Camunda Platform 8 Connectors using Connector SDK
https://github.com/camunda/connector-template-outbound
camunda connector
Last synced: 6 months ago
JSON representation
Template repository to create Camunda Platform 8 Connectors using Connector SDK
- Host: GitHub
- URL: https://github.com/camunda/connector-template-outbound
- Owner: camunda
- License: apache-2.0
- Created: 2022-07-29T05:56:01.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-16T18:04:06.000Z (6 months ago)
- Last Synced: 2024-10-18T10:25:12.270Z (6 months ago)
- Topics: camunda, connector
- Language: Java
- Homepage: https://github.com/camunda/connector-sdk
- Size: 140 KB
- Stars: 12
- Watchers: 3
- Forks: 17
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> A Connector template for new C8 outbound connector
>
> To use this template update the following resources to match the name of your connector:
>
> * [README](./README.md) (title, description)
> * [Element Template](./element-templates/template-connector.json)
> * [POM](./pom.xml) (artifact name, id, description)
> * [Connector Function](src/main/java/io/camunda/example/MyConnectorFunction.java) (rename, implement, update `OutboundConnector` annotation)
> * [Service Provider Interface (SPI)](./src/main/resources/META-INF/services/io.camunda.connector.api.outbound.OutboundConnectorFunction) (rename)
>
> ...and delete this hint.
>
> Read more about [creating Connectors](https://docs.camunda.io/docs/components/connectors/custom-built-connectors/connector-sdk/#creating-a-custom-connector)
>
> Check out the [Connectors SDK](https://github.com/camunda/connector-sdk)
# Connector Template
Camunda Outbound Connector Template
Emulates a simple outbound connector function that takes a message and echoes it back.
The function will throw an exception if your message starts with `fail`. This can be used to test error handling.
## Build
You can package the Connector by running the following command:
```bash
mvn clean package
```
This will create the following artifacts:
- A thin JAR without dependencies.
- An fat JAR containing all dependencies, potentially shaded to avoid classpath conflicts. This will not include the SDK artifacts since those are in scope `provided` and will be brought along by the respective Connector Runtime executing the Connector.
### Shading dependencies
You can use the `maven-shade-plugin` defined in the [Maven configuration](./pom.xml) to relocate common dependencies
that are used in other Connectors and the [Connector Runtime](https://github.com/camunda-community-hub/spring-zeebe/tree/master/connector-runtime#building-connector-runtime-bundles).
This helps to avoid classpath conflicts when the Connector is executed.
Use the `relocations` configuration in the Maven Shade plugin to define the dependencies that should be shaded.
The [Maven Shade documentation](https://maven.apache.org/plugins/maven-shade-plugin/examples/class-relocation.html)
provides more details on relocations.
## API
### Input
| Name | Description | Example | Notes |
|----------|------------------|-------------------|----------------------------------------------------------------------------|
| username | Mock username | `alice` | Has no effect on the function call outcome. |
| token | Mock token value | `my-secret-token` | Has no effect on the function call outcome. |
| message | Mock message | `Hello World` | Echoed back in the output. If starts with 'fail', an error will be thrown. |
### Output
```json
{
"result": {
"myProperty": "Message received: ..."
}
}
```
### Error codes
| Code | Description |
|------|--------------------------------------------|
| FAIL | Message starts with 'fail' (ignoring case) |
## Test locally
Run unit tests
```bash
mvn clean verify
```
### Test with local runtime
Use the [Camunda Connector Runtime](https://github.com/camunda-community-hub/spring-zeebe/tree/master/connector-runtime#building-connector-runtime-bundles) to run your function as a local Java application.
In your IDE you can also simply navigate to the `LocalContainerRuntime` class in test scope and run it via your IDE.
If necessary, you can adjust `application.properties` in test scope.
## Element Template
The element template for this sample connector is generated automatically based on the connector
input class using the [Element Template Generator](https://github.com/camunda/connectors/tree/main/element-template-generator/core).
The generation is embedded in the Maven build and can be triggered by running `mvn clean package`.
It is not mandatory to generate the element template for your connector and you can also create it manually.
However, the generator provides a convenient way to create the template and keep it in sync with the connector input class
and empowers you to prototype and iterate quickly.
The generated element template can be found in [element-templates/template-connector.json](./element-templates/template-connector.json).