Fix Java SDK zero-to-one: NPE on OSS, no run task, helloworld requires Orkes auth

examples/README.md

@@ -1,5 +1,52 @@
 # Examples
 
-This module provides simple, illustrative examples to help users get started with the Conductor Java Client/SDK v4. 
+This module provides examples demonstrating how to use the Conductor Java SDK to create and run workflows, tasks, and workers.
 
-It demonstrates basic use cases and integrations, serving as a reference for developers to understand how to use Conductor from their applications.
+## Prerequisites
+
+- Java 21 or higher
+- A running Conductor server ([start one with the CLI](https://conductor-oss.org))
+
+## Running Examples
+
+Set `CONDUCTOR_SERVER_URL` to point at your Conductor server (defaults to `http://localhost:8080/api`):
+
+```bash
+export CONDUCTOR_SERVER_URL=http://localhost:8080/api
+```
+
+### Hello World (recommended starting point)
+
+Registers a `greetings` workflow, starts it, and waits for completion:
+
+```bash
+./gradlew :examples:run
+```
+
+### Other examples
+
+Pass a fully-qualified class name with `-PmainClass`:
+
+```bash
+# Getting-started examples (OSS-compatible, no auth required)
+./gradlew :examples:run -PmainClass=com.netflix.conductor.gettingstarted.CreateWorkflow
+./gradlew :examples:run -PmainClass=com.netflix.conductor.gettingstarted.StartWorkflow
+./gradlew :examples:run -PmainClass=com.netflix.conductor.gettingstarted.HelloWorker
+
+# Orkes-specific examples (require CONDUCTOR_AUTH_KEY + CONDUCTOR_AUTH_SECRET)
+./gradlew :examples:run -PmainClass=io.orkes.conductor.sdk.examples.WorkflowManagement
+./gradlew :examples:run -PmainClass=io.orkes.conductor.sdk.examples.MetadataManagement
+```
+
+> **Note:** `CreateWorkflow` registers the workflow definition. `StartWorkflow` launches an instance. `HelloWorker` polls and executes tasks. Run `HelloWorker` while `StartWorkflow` is running to see the workflow complete.
+
+### Orkes Conductor (authenticated)
+
+Examples under `io.orkes.*` connect to Orkes Conductor and require credentials:
+
+```bash
+export CONDUCTOR_SERVER_URL=https://your-cluster.orkesconductor.com/api
+export CONDUCTOR_AUTH_KEY=your-key-id
+export CONDUCTOR_AUTH_SECRET=your-key-secret
+./gradlew :examples:run -PmainClass=io.orkes.conductor.sdk.examples.WorkflowManagement
+```

examples/build.gradle

@@ -1,5 +1,10 @@
 plugins {
     id 'java'
+    id 'application'
+}
+
+application {
+    mainClass = project.findProperty('mainClass') ?: 'com.netflix.conductor.sdk.examples.helloworld.Main'
 }
 
 repositories {

examples/src/main/java/com/netflix/conductor/sdk/examples/helloworld/Main.java

@@ -16,15 +16,15 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
+import com.netflix.conductor.client.http.ConductorClient;
 import com.netflix.conductor.sdk.examples.helloworld.workflowdef.GreetingsWorkflow;
 import com.netflix.conductor.sdk.workflow.executor.WorkflowExecutor;
 
-import io.orkes.conductor.sdk.examples.util.ClientUtil;
-
 public class Main {
 
     public static void main(String[] args) throws ExecutionException, InterruptedException, TimeoutException {
-        var workflowExecutor = new WorkflowExecutor(ClientUtil.getClient(), 10);
+        String serverUrl = System.getenv().getOrDefault("CONDUCTOR_SERVER_URL", "http://localhost:8080/api");
+        var workflowExecutor = new WorkflowExecutor(new ConductorClient(serverUrl), 10);
         workflowExecutor.initWorkers("com.netflix.conductor.sdk.examples.helloworld.workers");
         var workflowCreator = new GreetingsWorkflow(workflowExecutor);
         var simpleWorkflow = workflowCreator.create();

orkes-client/src/main/java/io/orkes/conductor/client/ApiClient.java

@@ -183,12 +183,14 @@ protected void applyEnvVariables() {
 
             String conductorAuthKey = System.getenv("CONDUCTOR_AUTH_KEY");
             if (conductorAuthKey == null) {
-                conductorAuthKey = System.getenv("CONDUCTOR_SERVER_AUTH_KEY").trim(); // for backwards compatibility
+                String legacyKey = System.getenv("CONDUCTOR_SERVER_AUTH_KEY"); // for backwards compatibility
+                conductorAuthKey = legacyKey != null ? legacyKey.trim() : null;
             }
 
             String conductorAuthSecret = System.getenv("CONDUCTOR_AUTH_SECRET");
             if (conductorAuthSecret == null) {
-                conductorAuthSecret = System.getenv("CONDUCTOR_SERVER_AUTH_SECRET").trim(); // for backwards compatibility
+                String legacySecret = System.getenv("CONDUCTOR_SERVER_AUTH_SECRET"); // for backwards compatibility
+                conductorAuthSecret = legacySecret != null ? legacySecret.trim() : null;
             }
 
             if (conductorAuthKey != null && conductorAuthSecret != null) {