Merge pull request #150 from orkes-io/temp

Documentation Updates
orkes-io · Sep 26, 2022 · 5c9a520 · 5c9a520
2 parents 9319d5c + f0fb6be
commit 5c9a520
Show file tree

Hide file tree

Showing 49 changed files with 2,667 additions and 1,599 deletions.
diff --git a/blog/authors.yml b/blog/authors.yml
@@ -15,6 +15,7 @@ dilip:
   title: CPO
   url: https://www.linkedin.com/in/diliplukose/
   image_url: /content/img/authors/dilip.jpg
+
 doug:
   name: Doug Sillars
   title: Senior Developer Relations Engineer
@@ -84,7 +85,6 @@ MohammedOsman:
   image_url: https://dl.airtable.com/.attachments/212f5fd8175d487f1642512a99e85d9c/b8be0e84/osman2.jpg?userId=usrLQ2kaNUqxOmv9c
 
 
-
 CameronPavey:
   name: Cameron Pavey
   title: Guest Author

diff --git a/docs/codelab/learningSeries.md b/docs/codelab/learningSeries.md
@@ -0,0 +1,34 @@
+
+# Learning Conductor 
+## Part 1: Configure and execute your first multi-step business process
+
+In this article, we will learn how to implement a sample business use case as a Conductor Workflow.
+:::note Use Case
+For a given user id, we need to read the user details and an order detail. If their age is more than 60, we need to send an SMS notification, and in addition - regardless of age, we need to send an email notification with the order details.
+:::
+To test this we will assume the following (these are mock but working APIs for testing):
+
+1. Read user details API: https://randomuser.me/api
+2. Order details API: https://orkes-api-tester.orkesconductor.com/get
+3. SMS API: https://orkes-api-tester.orkesconductor.com/post
+4. Email API: https://orkes-api-tester.orkesconductor.com/post
+
+This is a multistep workflow that includes a condition (age check). The defined workflow can be accessed here: [Conductor playground](https://play.orkes.io). Please note that you will only have read-only access. If we would like to edit this, we would have to make a copy. 
+
+>Video
+
+:::tip 
+As we can see by using tasks such as HTTP, we can run a sequence of tasks to handle business use cases.
+:::
+
+Now let's add the age related condition. You can find the updated definition here: [Conductor playground](https://play.orkes.io). We can run this workflow to see how everything works. As these are HTTP API calls, its possible the server will fail to respond. In spite of this, executions won't be impacted as Conductor is capable of running our workflows resiliently with in built retries. In this video we show how to update the definition, run and see results.
+
+>Video
+
+### Summary
+
+In this article we learned how to:
+
+1. Create a workflow for a business use case
+2. Use HTTP and SWITCH tasks
+3. Run workflows to see the output
diff --git a/docs/codelab/taskToDomain.md b/docs/codelab/taskToDomain.md
@@ -49,7 +49,7 @@ When you click ```Run Workflow```, the workflow adds a job to the "hello_world"
 
 What if this ```hello_world``` worker is thrashing the database, or has a memory leak that is impacting performance?  A new version must be created that fixes the problem.  We can use Conductor's Task to Domain feature to spin up another version of the task - and run it in the same production workflow (without impacting production traffic!). 
 
-To show an example of how to do this, we'll spin up a second version of ```hellow_world``` on our local computer. We start by cloning [OrkesWorkers](https://github.com/orkes-io/orkesworkers) to our desktop.  Following the instructions in the [codelab](https://orkes.io/content/docs/codelab/helloworld#application-permissions), we set up application permissions:
+To show an example of how to do this, we'll spin up a second version of ```hello_world``` on our local computer. We start by cloning [OrkesWorkers](https://github.com/orkes-io/orkesworkers) to our desktop.  Following the instructions in the [codelab](https://orkes.io/content/docs/codelab/helloworld#application-permissions), we set up application permissions:
 
 * Create an application in the playground.
 * Add the hello_world workflow and task to the application

diff --git a/docs/faq.md b/docs/faq.md
@@ -1,16 +1,14 @@
 # Frequently Asked Questions
 
-## Workflows
+## Conductor Server
 
-* Coming soon
+#### How do I adjust the logging levels?
 
-## Tasks
-
-* coming soon
+See this link: [Adjust logging levels](how-tos/Monitoring/Conductor-LogLevel)
 
 ## Access Control
 
-### How to generate an access token?
+#### How to generate an access token?
 In Orkes Cloud, there are two ways:
 * For testing, use a [token from your dashboard](content/docs/getting-started/concepts/access-control-applications#prototyping).  These expire with your session.
 * Create an [application, and use a key/secret to generate a token](/content/docs/getting-started/concepts/access-control-applications#application). These tokens do not currently expire, but this is expected to change.
diff --git a/docs/getting-started/install/orkes-conductor-community.md b/docs/getting-started/install/orkes-conductor-community.md
@@ -0,0 +1,105 @@
+# Orkes Conductor
+Orkes Conductor is a fully compatible version of Netflix Conductor with **Orkes certified stack**.
+
+[![CI](https://github.com/orkes-io/orkes-conductor-community/actions/workflows/ci.yaml/badge.svg)](https://github.com/orkes-io/orkes-conductor-community/actions/workflows/ci.yml)
+[![CI](https://img.shields.io/badge/license-orkes%20community%20license-green)](https://github.com/orkes-io/licenses/blob/main/community/LICENSE.txt)
+
+
+```
+  ______   .______       __  ___  _______     _______.
+ /  __  \  |   _  \     |  |/  / |   ____|   /       |
+|  |  |  | |  |_)  |    |  '  /  |  |__     |   (----`
+|  |  |  | |      /     |    <   |   __|     \   \    
+|  `--'  | |  |\  \----.|  .  \  |  |____.----)   |   
+ \______/  | _| `._____||__|\__\ |_______|_______/    
+                                                      
+  ______   ______   .__   __.  _______   __    __    ______ .___________.  ______   .______      
+ /      | /  __  \  |  \ |  | |       \ |  |  |  |  /      ||           | /  __  \  |   _  \     
+|  ,----'|  |  |  | |   \|  | |  .--.  ||  |  |  | |  ,----'`---|  |----`|  |  |  | |  |_)  |    
+|  |     |  |  |  | |  . `  | |  |  |  ||  |  |  | |  |         |  |     |  |  |  | |      /     
+|  `----.|  `--'  | |  |\   | |  '--'  ||  `--'  | |  `----.    |  |     |  `--'  | |  |\  \----.
+ \______| \______/  |__| \__| |_______/  \______/   \______|    |__|      \______/  | _| `._____| 
+```
+
+## Stack
+1. **Redis** as the primary store for running workflows
+2. **Postgres** for storing completed workflows and indexing enabling full text search
+3. **[Orkes-Queues](https://github.com/orkes-io/orkes-queues)** Redis based queues that improve upon dyno-queues and providers higher performance and are built from ground up to support Redis standalone and cluster mode
+### Dependency Versions
+
+| Dependency                              | Supported Version |
+|-----------------------------------------|-------------------|
+| Redis (Standalone, Cluster or Sentinel) | 6.2+              |
+| Postgres                                | 14+               |
+
+## Getting Started
+### Docker
+Easiest way to run Conductor.  Each release is published as `orkesio/orkes-conductor-community` docker images.
+
+#### Fully self-contained standalone server with all the dependencies
+Container image useful for local development and testing.  
+>**Note** self-contained docker image shouldn't be used in production environment.
+
+#### Simple self-contained script to launch docker image
+```shell
+curl https://raw.githubusercontent.com/orkes-io/orkes-conductor-community/main/scripts/run_local.sh | sh
+```
+#### Using `docker run` manually (provides more control)
+```shell
+
+# Create volumes for persistent stores
+# Used to create a persistent volume that will preserve the 
+docker volume create postgres
+docker volume create redis
+
+docker run --init -p 8080:8080 -p 1234:5000 --mount source=redis,target=/redis \
+--mount source=postgres,target=/pgdata orkesio/orkes-conductor-community-standalone:latest
+```
+Navigate to http://localhost:1234 once the container starts to launch UI
+
+#### Server + UI Docker
+```shell
+docker pull orkesio/orkes-conductor-community:latest
+```
+>**Note** To use specific version of Conductor, replace `latest` with the release version
+> e.g. 
+> 
+> ```docker pull orkesio/orkes-conductor-community:latest```
+
+### Published Artifacts
+
+* **Group:** `io.orkes.conductor`
+* **Artifacts:** `orkes-conductor-community-{server,persistence,archive}`
+
+| Artifact    | Gradle                                                                            |
+|-------------|-----------------------------------------------------------------------------------|
+| server      | `implementation 'io.orkes.conductor:orkes-conductor-community-server:VERSION'`      |
+| persistence | `implementation 'io.orkes.conductor:orkes-conductor-community-persistence:VERSION'` |  
+| archive     | `implementation 'io.orkes.conductor:orkes-conductor-community-archive:VERSION'`     |
+
+#### Production Configuration Recommendations
+The container and server jar published comes with sensible defaults that works for most use cases.
+
+Please see [CONFIGURATION](CONFIGURATION.md) for details.
+
+### Contributions
+We welcome community contributions and PRs to this repository.
+
+### Get Support 
+Use GitHub issue tracking for filing issues and Discussion Forum for any other questions, ideas or support requests.
+Orkes (http://orkes.io) development team creates and maintains the Orkes-Conductor releases.
+
+## License
+Copyright 2022 Orkes, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/docs/how-tos/continuous_integration.md b/docs/how-tos/continuous_integration.md
@@ -188,8 +188,12 @@ Our Action is built on this template, and so we'll just show the steps (there ar
     * The JSON uploaded is ```super_weather_v1.json```, which contains v1 of the workflow.
 3. This is identical to step 2, except we upload v2 of the workflow.
 
-> Note: The PUT command for Conductor expects a JSON array.  If we examine the JSON files, the JSON is encapsulated in ```[]```.
+:::tip 
+The PUT command for Conductor expects a JSON array.  If we examine the JSON files, the JSON is encapsulated in ```[]```.
+:::
 
-> Note: We could have included both V1 and V1 in the same file, but that does impact readability and editing, so in this case we opted to upload 2 distinct files.
+:::note
+We could have included both V1 and V2 versions in the same file, however for readability we opted to upload 2 distinct files.
+:::
 
 
diff --git a/docs/how-tos/sdks/conductor-clojure/main/README.md b/docs/how-tos/sdks/conductor-clojure/main/README.md
@@ -63,7 +63,7 @@ https://clojars.org/io.orkes/conductor-clojure
 
 ``` clojure
 ;; Creates a worker and starts polling for work. will return an instance of Runner which can then be used to shutdown
-(def instance (runner-executor-for-workers
+(def shutdown-fn (runner-executor-for-workers
                (list {
                       :name "cool_clj_task"
                       :execute (fn [someData]
@@ -72,7 +72,7 @@ https://clojars.org/io.orkes/conductor-clojure
                options ))
 
 ;; Shutsdown the polling for the workers defined above
-(.shutdown instance)
+(shutdown-fn)
 
 ```
 ## Options
@@ -173,74 +173,46 @@ Takes the option map and a list/vector of tasks to register. on success it will
 ```
 
 
-## Client namespace
-The client namespace holds the function to start a workflow and running a worker
+## TaskRunner namespace
+The taskrunner namespace holds the function to start a workflow and running a worker
 
-`[io.orkes.client :as conductor]`
+`[io.orkes.taskrunner :as conductor]`
 
 ``` clojure
 ;; Creates a worker and starts polling for work. will return an instance of Runner which can then be used to shutdown
-(def instance (runner-executor-for-workers
-               (list {
+(def shutdown-fn (conductor/runner-executor-for-workers
+ options              
+(list {
                       :name "cool_clj_task"
                       :execute (fn [someData]
                                  [:completed {:message "Hi From Clj i was created programatically"}])
                       })
-               options ))
+                ))
 
 ;; Shutsdown the polling for the workers defined above
-(.shutdown instance)
+(shutdown-fn)
 
 ```
 The (runner-executor-for-workers) function will take a list of worker implementations map, and options and start pooling for work
 it will return a TaskRunnerConfigurer instance, which you can shutdown by calling the .shutdown() java method
 
-## Mapper-Utils namespace
-The  `[io.orkes.mapper-utils :as mapper-utils]` namespace holds the functions to map to java object which are mostly not necesary.
-
-### The mapper-utils/java-map->clj-map protocol
-Will map a java map to a clojure map which may come in handy for workers implementation. for example consider a worker that sums two input parameters. For a workflow defined like this :
-
-``` clojure
-(metadata/register-workflow-def options {:name "simple_wf"
-                                         :description "created programatically from clj"
-                                         :version 1
-                                         :tasks [{:name "simplest_task"
-                                                  :taskReferenceName "repl_task_ref"
-                                                  :inputParameters {"firstNumber" "${workflow.input.firstNumber}"
-                                                                     "secondNumber" "${workflow.input.secondNumber}"}
-                                                  :type "SIMPLE"}]
-                                         :inputParameters ["firstNumber" "secondNumber"]
-                                         :outputParameters {"result" "${repl_task_ref.output.:result}"}
-                                         :schema-version 2
-                                         :restartable true
-                                         :ownerEmail "[email protected]"
-                                         :timeoutSeconds 0
-                                         :timeoutPolicy "ALERT_ONLY"})
-```
+## Utils.
+Treat conductor workflows as simple tree data structures
 
-To be able to use the input params you would need to use the string names like this:
-
-``` clojure
-(def instance (conductor/runner-executor-for-workers
-               (list {:name "simplest_task"
-                      :execute (fn [someData]
-
-                                 [:completed {"result" (+ (get someData "firstNumber") (get someData "secondNumber"))}])})
-               options))
-```
-
-A more clojure friendly way would be to convert to clojure our map :
 
+`[io.orkes.utils :as ut]`
+
 ``` clojure
-(def instance (conductor/runner-executor-for-workers
-               (list {:name "simplest_task"
-                      :execute (fn [someData]
-                      (let [convertedToClj (-> someData mapper-utils/java-map->clj-map)]
-                        [:completed {"result" (+ (:firstNumber convertedToClj) (:secondNumber convertedToClj))}]
-                      ))})
-               options))
+;; Rename every single task to fakeName. Wil transverce the whole tree and aplly the transformation function.
+
+(ut/map-wf-tasks #(assoc % :name "fakeName")
+                                                  wf-fork-example)
+
+;; Given a workflow wf-fork-example in this case will return a new workflow without the task with the taskReferenceName "cool_clj_task_ref"
+(ut/filter-wf-tasks
+                           #(not= (:taskReferenceName %) "cool_clj_task_ref")
+                           wf-fork-example)
+
 ```
 
 
-
diff --git a/docs/how-tos/sdks/conductor-csharp/main/README.md b/docs/how-tos/sdks/conductor-csharp/main/README.md
@@ -13,7 +13,7 @@
 
 ### Write workers  
 
-```
+```csharp
  internal class MyWorkflowTask : IWorkflowTask
     {
         public MyWorkflowTask(){}
@@ -48,7 +48,7 @@
 
 ### Run workers
 
-```
+```csharp
 using System;
 using System.Threading;
 using System.Threading.Tasks;
@@ -108,12 +108,14 @@ namespace TestOrkesSDK
 }
 ```
 
-####Note:
-Replace KEY and SECRET by obtaining a new key and secret from [Orkes Playground](https://play.orkes.io/)
+>***Note***
+>
+>Replace KEY and SECRET by obtaining a new key and secret from [Orkes Playground](https://play.orkes.io/)
+>
 
 See [Generating Access Keys for Programmatic Access](https://orkes.io/content/docs/getting-started/concepts/access-control#access-keys) for details./
 
-```
+```csharp
     internal class WorkflowsWorkerService : BackgroundService
     {
         private readonly IWorkflowTaskCoordinator workflowTaskCoordinator;
@@ -142,7 +144,7 @@ See [Generating Access Keys for Programmatic Access](https://orkes.io/content/do
 
 ### Worker Configurations
 Worker configuration is handled via Configuration object passed when initializing TaskHandler.
-```
+```csharp
 Configuration configuration = 
     new Configuration(new ConcurrentDictionary<string, string>(), "KEY", "SECRET", "https://play.orkes.io/");
 ```
@@ -151,7 +153,7 @@ Configuration configuration =
 
 Below is the code snippet that shows how to register a simple workflow and start execution:
 
-```
+```csharp
 IDictionary<string, string> optionalHeaders = new ConcurrentDictionary<string, string>();
 Configuration configuration = new Configuration(optionalHeaders, "keyId", "keySecret");
 
@@ -177,11 +179,13 @@ Dictionary<string, object> request = new Dictionary<string, object>();
 request.Add("http_request", requestParams);
 workflowTask.InputParameters = request;
 workflowDef.Tasks = new List<WorkflowTask>() { workflowTask };
+
 //Run a workflow
 WorkflowResourceApi workflowResourceApi = new WorkflowResourceApi(configuration);
 Dictionary<string, Object> input = new Dictionary<string, Object>();
+
 //Fill the input map which workflow consumes.
 workflowResourceApi.StartWorkflow("test_workflow", input, 1);
 Console.ReadLine();
 ```
-Please see [Conductor.Api](https://github.com/conductor-sdk/conductor-csharp/tree/main/Api) for the APIs.
+Please see [Conductor.Api](https://github.com/conductor-sdk/conductor-csharp/tree/main/Api) for the APIs.