A sample ByteChef custom component written in Java. It builds into a jar that you upload to ByteChef, where the component shows up in the workflow editor next to the built-in components.
The component is named sampleCustomComponentJava (title Sample Custom Component, version 1). It has one action
that greets the value you give it.
Full reference: Custom Components.
| Name | sampleCustomComponentJava |
| Version | 1 (the ComponentDsl default) |
| Category | Helpers |
| Icon | assets/sample.svg, declared as path:assets/sample.svg |
Sample Action (sampleAction)
| Property | Type | |
|---|---|---|
property1 (Property1) |
string | Any text. |
The action returns {"key": "key1", "message": "Hello <property1>"}. In a workflow it is referenced as
sampleCustomComponentJava/v1/sampleAction.
SampleConnection declares a bearer token authorization against the placeholder base URI https://api.example.com.
Using the component in a workflow therefore needs a connection with any token value. Point the base URI at your API and
swap the authorization for the one it needs (API key, basic auth, OAuth2 and so on), or remove .connection(...) from
SampleComponentHandler if the component does not authenticate.
| Path | |
|---|---|
src/main/java/org/sample/customcomponent/SampleComponentHandler.java |
The ComponentHandler, registered for ServiceLoader with @AutoService. |
src/main/java/org/sample/customcomponent/action/SampleAction.java |
The action. |
src/main/java/org/sample/customcomponent/connection/SampleConnection.java |
The connection. |
src/main/java/org/sample/customcomponent/constant/SampleConstants.java |
The component and action names. |
src/main/resources/assets/sample.svg |
The icon. |
libs/component-api-1.0.jar, libs/definition-api-1.0.jar |
The ByteChef API the component compiles against. |
- JDK 25. The Gradle wrapper (Gradle 9.4.1) is checked in, so you do not need a local Gradle installation.
- A ByteChef Enterprise Edition server with custom components available (see Upload).
./gradlew jarThe jar is written to build/libs/sample-custom-component-java-1.0.0.jar. Check that it contains the ServiceLoader
registration and the icon:
unzip -l build/libs/sample-custom-component-java-1.0.0.jarThe listing must include META-INF/services/com.bytechef.component.ComponentHandler and assets/sample.svg.
- One
ComponentHandlerregistered forServiceLoader.@AutoService(ComponentHandler.class)generates theMETA-INF/servicesentry. The loader uses the first handler it finds, so keep one component per jar. - An icon at
assets/sample.svg. The loader reads the icon from that path whatever.icon(...)says, and a jar without it fails to load. Replace the file's content, not its path. - Every dependency except the ByteChef API inside the jar. Classes in
java.*,jdk.*andcom.bytechef.*come from the server; everything else is loaded only from your jar. Compile againstcomponent-apianddefinition-apiwithout bundling them, and build a fat or shaded jar if you add other runtime dependencies. Do not put your own classes in acom.bytechefpackage.
Custom components are an Enterprise Edition feature. Settings > Custom Components is shown when the ff-1024
feature flag is on, and uploading requires the ADMIN authority.
Java uploads can be switched off by an operator, in which case a .jar upload fails with
JAVA_CUSTOM_COMPONENT_UPLOAD_DISABLED. They are on by default; make sure the server does not set:
| Property | Environment variable | Default |
|---|---|---|
bytechef.component.custom-component.java.enabled |
BYTECHEF_COMPONENT_CUSTOM_COMPONENT_JAVA_ENABLED |
true |
- Open Settings > Custom Components.
- Click New Component > Import Component.
- Pick
build/libs/sample-custom-component-java-1.0.0.jarand click Import.
Deploy from CI or a script with an Admin API key:
curl -X POST "$BYTECHEF_URL/api/platform/v1/custom-components/deploy" \
-H "Authorization: Bearer $BYTECHEF_ADMIN_API_KEY" \
-F "componentFile=@build/libs/sample-custom-component-java-1.0.0.jar"A successful deploy answers 204 No Content.
The component appears as Sample Custom Component, version 1, published and enabled. Add Sample Action to a workflow, fill in Property1 and run the step.
Java components cannot be edited in ByteChef. Change the code, rebuild the jar and upload it again. Uploading the same
name and version replaces that published version in place; to publish a new version next to the old one, set
.version(2) on the component definition first.