Merge pull request #357 from latchbio/taras/automation-docs

[Automation Docs] Fix overview language and update example

docs/source/automation/automation-usecase.md

@@ -4,9 +4,13 @@ Note: This document is a work in progress and is subject to change.
 
 We will walk through the process of creating an [automation](overview.md) on Latch which will run a _target workflow_ on all children of the target directory. We assume that you understand how to write and register [Workflows](../basics/what_is_a_workflow.md) on Latch.
 
-**Prerequisite:**
-* An existing Table in [Latch Registry](https://latch.wiki/what-is-registry)
-* An target folder in [Latch Data](https://console.latch.bio/data)
+**Prerequisites:**
+* _Target directory in [Latch Data](https://console.latch.bio/data): this is the folder which is watched by the automation. Automation will be triggered if a child is added to this folder.
+
+**Terms:**
+- _Automation Workflow_: workflow which will be called by automation. This is the workflow we create in [steps 3-5](#3-create-the-automation-workflow) of this tutorial.
+- _Target Workflow_: workflow which will be ran by automation workflow on child of the _target directory_. This workflow should contain the logic on how to process the files in child directories. This is the workflow we create in [step 1](#1-create-the-target-workflow) of this tutorial.
+- _Registry Table_: we use a Registry Table in this tutorial to record child directories which are processed by the target workflow to avoid reprocessing same directories in consequent runs of automation. We create this table in [step 2](#2-create-a-new-registry-table) of this tutorial.
 
 ## 1: Create the Target Workflow
 
@@ -96,6 +100,8 @@ This example requires another _target workflow_ which will get executes on every
 
 In this example, we record all processed child directories in the Registry Table to not reprocess directories when automation workflow is runs again. This example requires you to create a new table with no existing columns. The automation workflow will add a column `Processed Directory` with the directory name of processed children.
 
+For many common use cases, Registry serves as the location to track workflow inputs and outputs, and hence we include an example of it here. However, having a registry table is not required, if you don't want to use Registry as a mean to track your inputs and outputs.
+
 To create a new table to be used with the automation:
 
 1. Go to [Latch Registry](https://console.latch.bio/registry).
@@ -145,13 +151,18 @@ To specify the target workflow and the registry table which you have just create
 * `params`: The parameters for your workflow. Refer to [Create The Target Workflow](#1-create-the-target-workflow) to get the parameters.
 * `table_id`: The ID of the table which you created that stores metadata for this automation. Refer to [Create A New Registry Table](#2-create-a-new-registry-table) to create a table and get the ID.
 
+>**Important**:
+Currently, automations are only passing `input_directory` as the parameter to the automation workflow. If your workflow has different parameters automation will fail to start it.
+\
+In case you need more parameters to pass to your automation workflow, we suggest to hard-code them into the workflow while we are working on adding parameter support for automations.
+
+
 ```python
 # __init__.py​
 
 from latch.resources.workflow import workflow
 from latch.types.directory import LatchDir, LatchOutputDir
 from latch.types.metadata import LatchAuthor, LatchMetadata, LatchParameter
-
 from wf.automation import automation_task
 
 metadata = LatchMetadata(
@@ -161,32 +172,31 @@ metadata = LatchMetadata(
         name="Your Name Here",
     ),
     # MODIFY NAMING METADATA ABOVE
+    # IMPORTANT: these exact parameters are required for the workflow to work with automations
     parameters={
         "input_directory": LatchParameter(
             display_name="Input Directory",
-        ),
-        "automation_id": LatchParameter(
-            display_name="Automation ID",
-        ),
+        )
     },
 )
 
 
 @workflow(metadata)
-def automation_workflow(input_directory: LatchDir, automation_id: str) -> None:
+def automation_workflow(input_directory: LatchDir) -> None:
     output_directory = LatchOutputDir(
-        path="fixme"  # fixme: change to remote path of desired output directory
+        path="latch://FIXME"  # fixme: change to remote path of desired output directory
     )
 
     automation_task(
         input_directory=input_directory,
         output_directory=output_directory,
-        target_wf_id="fixme",  # fixme: change wf_id to the desired workflow id
-        table_id="fixme",  # fixme: change table_id to the desired registry table
+        target_wf_id="FIXME",  # fixme: change wf_id to the desired workflow id
+        table_id="FIXME",  # fixme: change table_id to the desired registry table
     )
+
 ```
 
-Change the parameters object in `automation.py` from [step 1.6](#1-create-the-target-workflow):
+(Optional) Change the parameters object in `automation.py` from [step 1.6](#1-create-the-target-workflow) if your target workflow takes different parameters than `input_directory` and `output_directory`:
 ```python
 # automation.py
 
@@ -228,7 +238,6 @@ Modify the function below to change the logic for launching target workflows.
 
 ```python
 # automation.py
-
 import uuid
 from typing import Set
 
@@ -246,7 +255,6 @@ def automation_task(
     output_directory: LatchOutputDir,
     target_wf_id: str,
     table_id: str,
-    params: Dict[T,T],
 ) -> None:
     """
     Logic on how to process the input directory and launch the target workflows.

docs/source/automation/overview.md

@@ -10,69 +10,79 @@ Additionally, you can pause and resume automations by toggling status radio on t
 
 ### Trigger
 
-Automation trigger specifies the conditions after which the automation will run(i.e. child got added to the target directory). It allows you to specify a target directory to watch, the [_event_](#trigger-event-types) which kicks off a workflow, and a [_timer_](#trigger-timer).
+Automation trigger specifies the conditions to run the automation(i.e. child got added to the target directory). It allows you to specify a target directory to watch, the [_event_](#trigger-event-types) which kicks off a workflow, and a [_timer_](#trigger-timer).
 
 #### Trigger Event Types
 
-> Note: currently, only child addition events are supported in automations.
+> Note: currently, only child addition event is supported in automations.
 
 *Available events:*
 
-- _Data Update_ event type specifies when to run the automation if a data tree in Latch Data has been modified. Supported events for this type are:
-    -  _Child Added_ event triggers if a new child has been added to the target directory at any depth. Automation will not run if the child has been modified or deleted.
+- _Data Update_ event type specifies when to run the automation if a data tree in Latch Data has been modified.
+
+    Supported events:
+        -  _Child Added_ event triggers if a new child has been added to the target directory at any depth. Automation will not run if the child has been modified or deleted.
 
 #### Trigger Timer
 
-Automation trigger timer specifies the wait period after the last file has been added to the target directory after which the workflow will run.
+Automation trigger timer specifies the wait period after the last trigger event after which the workflow will run.
+
+For example, if the timer is 10 minutes and the trigger event is `Child Added`, the automation will wait 10 minutes after a child has been added to the target directory and then run automation workflow.
 
 ### Automation Workflow
 
 This is the [workflow](../basics/what_is_a_workflow.md) that will run whenever the automation has been [triggered](#trigger).
 
-Note: Right now, automations are limited to accepting workflows with a fixed set of parameters. Make sure to define your workflow with `input_directory` and `automation_id` as parameters.
+#### Usage Note:
+Currently, automations are only passing `input_directory` as the parameter to the automation workflow. If your workflow has different parameters automation will fail to start it.
+
+In case you need more parameters to pass your workflow, we suggest to hard-code them into your workflow while we are working on adding parameter support for automations.
+
+Make sure that the workflows which you use with automation have the following parameter dictionary:
 
 ```python
 # __init__.py
 
 from latch.resources.workflow import workflow
 from latch.types.directory import LatchDir, LatchOutputDir
 from latch.types.metadata import LatchAuthor, LatchMetadata, LatchParameter
-
 from wf.automation import automation_task
 
 metadata = LatchMetadata(
-    display_name="Automation Workflow",
+    # MODIFY NAMING METADATA BELOW
+    display_name="Workflow Name",
     author=LatchAuthor(
-        name="Your Name",
+        name="Your Name Here",
     ),
+    # MODIFY NAMING METADATA ABOVE
+    # IMPORTANT: these exact parameters are required for the workflow to work with automations
     parameters={
         "input_directory": LatchParameter(
             display_name="Input Directory",
-        ),
-        "automation_id": LatchParameter(
-            display_name="Automation ID",
-        ),
+        )
     },
 )
 
 
 @workflow(metadata)
-def automation_workflow(input_directory: LatchDir, automation_id: str) -> None:
+def automation_workflow(input_directory: LatchDir) -> None:
     pass
 ```
 
 See an [example](automation-usecase.md) of how we create an automation workflow which reads all children of the target directory and kicks off another workflow which runs processing on child directories.
 
 ## Creating an Automation
 
-Navigate to [Automations](https://console.latch.bio/automations) tab via **Worfklows** > **Automations** and click on the **Create Automation** button.
+1. Register automation workflow with Latch. See [Usage Note](#usage-note) to make sure that your workflow can be run by automations.
+
+2. Navigate to [Automations](https://console.latch.bio/automations) tab via **Worfklows** > **Automations** and click on the **Create Automation** button.
 
-Input an **Automation Name** and **Description**.
+    Input an **Automation Name** and **Description**.
 
-Next, select a folder where files/folders will be uploaded using the `Select Target` button. Any items uploaded to this folder will trigger the specified workflow.
+    Next, select a folder where files/folders will be uploaded using the `Select Target` button. Any items uploaded to this folder will trigger the specified workflow.
 
-Finally, select the [automation workflow](#automation-workflow) that you have registered with Latch.
+    Finally, select the [automation workflow](#automation-workflow) that you have registered with Latch.
 
-Checkout an [example](automation-usecase.md) on how to create and register automation workflows.
+    Checkout an [example](automation-usecase.md) on how to create and register automation workflows.
 
-![Create Automation Example](../assets/automation/create-automation-example.png)
+    ![Create Automation Example](../assets/automation/create-automation-example.png)