Proposal for a unified docs structure across SDKs

README.md

@@ -2,54 +2,37 @@
 
 The `conductor-javascript` repository provides the client SDKs to build task workers in javascript/typescript.
 
-Building the task workers in javascript mainly consists of the following steps:
+## Getting Started
 
-1. Setup conductor-javascript package
-2. [Create and run task workers](workers_sdk.md)
-3. [Create workflows using code](workflow_sdk.md)
-
-### Setup Conductor Javascript Package
+Check out [Getting Started](docs/getting-started.md) to learn how to get started with the JS SDK.
 
-* Get the package from npm
+## Create Workflows, Tasks, and more.
 
-```shell
-npm i @io-orkes/conductor-javascript
-```
-or
+See [definitions](docs/definitions.md) to learn how to create workflows, tasks, and more with the JS SDK.
 
-```shell
-yarn add @io-orkes/conductor-javascript
-```
+## Running Workflows
 
-## Configurations
+Read the [execute](docs/execute.md) page to learn how to execute Workflows.
 
-### Authentication Settings (Optional)
-Configure the authentication settings if your Conductor server requires authentication.
-* keyId: Key for authentication.
-* keySecret: Secret for the key.
+## Running Workers
 
-### Access Control Setup
-See [Access Control](https://orkes.io/content/docs/getting-started/concepts/access-control) for more details on role-based access control with Conductor and generating API keys for your environment.
+See [create and run task workers](docs/workers.md) to learn how to create and run task workers with the JS SDK.
 
-### Configure API Client
+## Search for Executions
 
-```typescript
-/**
- * Application keys generated from the Application menu > Create Application
- * then edit and create Access Keys
- *
- */
-import { OrkesApiConfig, orkesConductorClient } from "@io-orkes/conductor-javascript";
+See [search for executions](docs/search.md) to learn how to query the executions.
 
-const config: Partial<OrkesApiConfig> = {
-  keyId: "XXX", // optional
-  keySecret: "XXXX", // optional
-  refreshTokenInterval: 0, // optional (in milliseconds) defaults to 30 minutes (30 * 60 * 1000). 0 no refresh
-  serverUrl: "https://play.orkes.io/api",
-};
+## About
+
+Find more about the design decisions behind this implementation in the [about](docs/about.md) page.
+
+## Other SDKs
+
+* [Python](https://github.com/conductor-sdk/conductor-python)
+* [C#](https://github.com/conductor-sdk/conductor-csharp)
+* [Java](https://github.com/orkes-io/orkes-conductor-client)
+* [Go](https://github.com/conductor-sdk/conductor-go)
+* [Clojure](https://github.com/conductor-sdk/conductor-clojure)
 
-orkesConductorClient(config).then(client => ..... );
 
-```
 
-### Next: [Create and run task workers](workers_sdk.md)

DECISIONS.md → docs/about.md

@@ -37,4 +37,13 @@ I considered `mocha` and `ava` (which i've also used and like) but `jest` struck
 
 who: @nicktomlin
 
-Typescript publication can be a wacky process and `tsup` simplifies a lot of this. 
+Typescript publication can be a wacky process and `tsup` simplifies a lot of this.
+
+### More Docs
+
+* [Getting Started](getting-started.md)
+* [Create and run task workers](workers.md)
+* [Create Workflows](create.md)
+* [Execute Workflows](execute.md)
+* [Search for entities](search.md)
+

docs/create.md

@@ -0,0 +1,54 @@
+# Authoring Workflows with the Javascript SDK
+
+## A simple two-step workflow
+
+```typescript
+import {
+  OrkesApiConfig,
+  orkesConductorClient,
+  TaskRunner,
+  simpleTask,
+} from "@io-orkes/conductor-javascript";
+
+//API client instance with server address and authentication details
+const clientPromise = orkesConductorClient({
+  keyId: "XXX", // optional
+  keySecret: "XXXX", // optional
+  serverUrl: "https://play.orkes.io/api",
+});
+
+const client = await clientPromise;
+
+//Create new workflow executor
+const executor = new WorkflowExecutor(client);
+
+// Using Factory function
+const factoryWf = {
+  name: "my_first_workflow",
+  version: 1,
+  ownerEmail: "[email protected]",
+  tasks: [simpleTask("simple_task_ref", "simple_task", {})],
+  inputParameters: [],
+  outputParameters: {},
+  timeoutSeconds: 0,
+};
+const workflow = executor.registerWorkflow(true, factoryWf);
+```
+
+## Using Workflow Executor to start previously registered workflow
+
+```typescript
+const executor = new WorkflowExecutor(client);
+const executionId = await executor.startWorkflow({ name, version, input: {} });
+```
+
+See [execute](docs/execute.md) page to learn more about how to execute Workflows.
+
+### More Docs
+
+* [Getting Started](getting-started.md)
+* [Create and run task workers](workers.md)
+* [Execute Workflows](execute.md)
+* [Search for entities](search.md)
+* [About](about.md)
+

workflow_sdk.md → docs/execute.md

@@ -1,50 +1,6 @@
-# Authoring Workflows with the Javascript SDK
+# Executing Workflows
 
-## A simple two-step workflow
-
-```typescript
-import {
-  OrkesApiConfig,
-  orkesConductorClient,
-  TaskRunner,
-  simpleTask,
-} from "@io-orkes/conductor-javascript";
-
-//API client instance with server address and authentication details
-const clientPromise = orkesConductorClient({
-  keyId: "XXX", // optional
-  keySecret: "XXXX", // optional
-  serverUrl: "https://play.orkes.io/api",
-});
-
-const client = await clientPromise;
-
-//Create new workflow executor
-const executor = new WorkflowExecutor(client);
-
-// Using Factory function
-const factoryWf = {
-  name: "my_first_workflow",
-  version: 1,
-  ownerEmail: "[email protected]",
-  tasks: [simpleTask("simple_task_ref", "simple_task", {})],
-  inputParameters: [],
-  outputParameters: {},
-  timeoutSeconds: 0,
-};
-const workflow = executor.registerWorkflow(true, factoryWf);
-```
-
-### Execute Workflow
-
-#### Using Workflow Executor to start previously registered workflow
-
-```typescript
-const executor = new WorkflowExecutor(client);
-const executionId = await executor.startWorkflow({ name, version, input: {} });
-```
-
-#### Using Workflow Executor to execute a workflow and get the output as a result
+## Using Workflow Executor to execute a workflow and get the output as a result
 
 ```typescript
 import {
@@ -129,7 +85,11 @@ export type Workflow = {
 };
 ```
 
-### More Examples
+### More Docs
+
+* [Getting Started](getting-started.md)
+* [Create and run task workers](workers.md)
+* [Create Workflows](create.md)
+* [Search for entities](search.md)
+* [About](about.md)
 
-You can find more examples at the following GitHub repository:
-https://github.com/conductor-sdk/javascript-sdk-examples

docs/getting-started.md

@@ -0,0 +1,54 @@
+# Getting Started
+
+### Setup Conductor Javascript Package
+
+* Get the package from npm
+
+```shell
+npm i @io-orkes/conductor-javascript
+```
+or
+
+```shell
+yarn add @io-orkes/conductor-javascript
+```
+
+## Configurations
+
+### Authentication Settings (Optional)
+Configure the authentication settings if your Conductor server requires authentication.
+* keyId: Key for authentication.
+* keySecret: Secret for the key.
+
+### Access Control Setup
+See [Access Control](https://orkes.io/content/docs/getting-started/concepts/access-control) for more details on role-based access control with Conductor and generating API keys for your environment.
+
+### Configure API Client
+
+```typescript
+/**
+ * Application keys generated from the Application menu > Create Application
+ * then edit and create Access Keys
+ *
+ */
+import { OrkesApiConfig, orkesConductorClient } from "@io-orkes/conductor-javascript";
+
+const config: Partial<OrkesApiConfig> = {
+  keyId: "XXX", // optional
+  keySecret: "XXXX", // optional
+  refreshTokenInterval: 0, // optional (in milliseconds) defaults to 30 minutes (30 * 60 * 1000). 0 no refresh
+  serverUrl: "https://play.orkes.io/api",
+};
+
+orkesConductorClient(config).then(client => ..... );
+
+```
+
+### More Docs
+
+* [Create and run task workers](workers.md)
+* [Create Workflows](create.md)
+* [Search for entities](search.md)
+* [Execute Workflows](execute.md)
+* [About](about.md)
+

docs/search.md

@@ -0,0 +1,129 @@
+# Searching for Entities and Executions
+
+The Conductor API provides a search endpoint to search for entities in Conductor. The search endpoint supports searching for workflows, tasks, and more.
+
+Use the search API to retrieve information about entities and executions in Conductor.
+
+## Search for Workflow Executions
+
+```typescript
+import { orkesConductorClient, WorkflowExecutor } from "@io-orkes/conductor-javascript";
+
+async function searchExecution(
+  start = 0,
+  size = 15,
+  query = "startTime>1719842897739",
+  freeText = "",
+  sort = "startTime:DESC"
+) {
+  const client = await orkesConductorClient({
+    TOKEN: "yourToken",
+    serverUrl: "http://yourServer.url/api"
+  });
+  const executor = new WorkflowExecutor(client);
+  const results = await executor.search(start, size, query, freeText, sort );
+
+  return results;
+  }
+
+  searchExecution();
+```
+
+## Search for Task Executions
+
+```typescript
+import { orkesConductorClient, TaskClient } from "@io-orkes/conductor-javascript";
+
+async function searchTask(
+  start = 0,
+  size = 15,
+  sort = "startTime:DESC",
+  freeText = "",
+  query = "startTime>1719843016751",
+) {
+  const client = await orkesConductorClient({
+    TOKEN: "yourToken",
+    serverUrl: "http://yourServer.url/api"
+  });
+  const taskClient = new TaskClient(client);
+  const results = await taskClient.search(start, size, sort, freeText, query);
+
+  return results;
+}
+
+const doSearch = async () => {
+  const tasks = await searchTask();
+  console.log(tasks);
+}
+
+doSearch();
+```
+
+## Search for Human Tasks Executions
+
+```typescript
+import {
+    orkesConductorClient,
+    HumanExecutor
+  } from "@io-orkes/conductor-javascript";
+
+  const clientPromise = orkesConductorClient({
+    TOKEN: "yourToken",
+    serverUrl: "http://yourServer.url/api"
+  });
+
+  const searchHumanTask = async () => {
+    const client = await clientPromise;
+    const executor = new HumanExecutor(client);
+
+    const tasks = await executor.search({
+      start: 1,
+      size: 15,
+      claimants: [{"userType":"CONDUCTOR_USER","user":"test"}],
+      assignees: [{"userType":"CONDUCTOR_USER","user":"test123"}],
+      states: ["IN_PROGRESS","ASSIGNED"],
+      taskInputQuery: "",
+      taskOutputQuery: "",
+      taskRefNames: ["ref1","ref2"],
+      definitionNames: ["name1","name2"],
+    });
+
+    return tasks;
+  }
+
+  searchHumanTask();
+```
+
+## Search for Scheduler Executions
+
+```typescript
+import { orkesConductorClient, SchedulerClient } from "@io-orkes/conductor-javascript";
+
+async function searchSchedule(
+  start = 0,
+  size = 15,
+  sort = "startTime:DESC",
+  freeText = "*",
+  query = "",
+) {
+  const client = await orkesConductorClient({
+    TOKEN: "yourToken",
+    serverUrl: "http://yourServer.url/api"
+  });
+  const executor = new SchedulerClient(client);
+  const results = await executor.search(start, size, sort, freeText, query);
+
+  return results;
+}
+
+searchSchedule();
+```
+
+### More Docs
+
+* [Getting Started](getting-started.md)
+* [Create and run task workers](workers.md)
+* [Create Workflows](create.md)
+* [Execute Workflows](execute.md)
+* [About](about.md)
+