resolve conflict

adaptors/odk.md

@@ -1,54 +1,49 @@
 ---
-title: Open Data Kit (ODK)
+title: ODK
 ---
 
-## Open Data Kit (ODK) Collect
-
-To bypass ODK Aggregate and submit forms directly to OpenFn make the following
-changes in your ODK Collect app.
-
-1. Select `General Settings`.
-2. Select `Server Settings`.
-3. Under `Type`, select `Other`.
-4. Under `URL`, enter `https://www.openfn.org
-5. Under `Submission path`, enter `/inbox/your-unique-inbox-url` (you can copy
-   this from your OpenFn Inbox).
-6. Optional: If you have enabled auth methods on your inbox, enter your
-   `username` and `password` on this same screen.
-
-Note that you cannot load forms from OpenFn. Forms must be loaded directly via
-[ODK's direct method](https://docs.opendatakit.org/collect-forms/#loading-forms-directly),
-which allows you to send forms as files via email/Whatsapp. Users can then
-choose to download the files and save them in the `odk/ forms` folder on their
-mobile.
-
-Note that if you want to reverse this setup and configure ODK Collect to
-re-connect to your Aggregate instance again:`
-
-1. Go back to `General Settings`.
-2. Select `Server Settings`.
-3. Under `Type`, select `ODK Aggregate`.
-4. Under `URL`, enter `Your Aggregate URL`
-5. Under `Submission path`, enter `/submissions`.
-6. Enter your ODK Aggregate `username` and `password` on this same screen.
-
-## Open Data Kit (ODK) Aggregate
-
-1. To new submissions from ODK in real-time, click the "Form Management" tab at
-   the top of your Aggregate interface.
-2. Click "Publish" next to the form you'd like to publish to OpenFn.
-3. A dialogue box will open.
-4. In the "Publish To:" picklist, select `Z-ALPHA JSON Server`.
-5. Choose which data to publish in the "Data to Publish:" picklist. You may:
-   **"Upload Existing Data ONLY"** (ideal for migrations of finished data sets),
-   **"Stream New Submission Data ONLY"** (ideal for new projects), or **"BOTH
-   Upload Existing & Stream New Submission Data"** (ideal for connecting ongoing
-   projects which are already running).
-6. In the "URL to publish to:" text box, enter your OpenFn Inbox UUID. (e.g.,
-   `https://www.openfn.org/inbox/8ad63a29-mUCh-sEcRET-cODes-wOW`)
-7. Leave "Authorization token:" blank.
-8. Leave "Include Media as:" set to "Links(URLs) to Media".
-9. Click "Publish" and enter your email address in the dialogue box.
-10. Click the "Published Data" tab under "Form Management" and select your form
-    to view the status of your publisher. You can also now check your OpenFn
-    inbox to see ODK submissions arrive.
+# App Overview
+
+[ODK](https://getodk.org) is a data collection platform used by researchers,
+field teams, and other professionals to collect they data they need wherever it
+is.
+
+# Integration Options
+
+In order to fetch data from an ODK Central, you must run a scheduled job with a
+cron trigger using the `odk` adaptor.
+
+Here's an example of a job that gets submission data.
+
+```js
+getSubmissions($.projectId, $.xmlFormId);
+```
+
+Every time this job runs it will get of all submissions and write them to
+`state.data`, leaving your state object looking like this:
+
+```json
+{
+  "data": [
+    {
+      "__id": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
+      "age": 25,
+      "meta": {
+        "instanceID": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44"
+      },
+      "name": "Bob"
+    },
+    {
+      "__id": "uuid:297000fd-8eb2-4232-8863-d25f82521b87",
+      "age": 30,
+      "meta": {
+        "instanceID": "uuid:297000fd-8eb2-4232-8863-d25f82521b87"
+      },
+      "name": "Alice"
+    }
+  ],
+  "response": {
+    /* ODK response headers, code and context*/
+  }
+}
+```

docs/build/workflows.md

@@ -3,16 +3,16 @@ title: Workflows
 sidebar_label: Workflows
 ---
 
-`Workflows` are automated processes or sets of instructions that accomplish a
+**Workflows** are automated processes or sets of instructions that accomplish a
 task. In OpenFn configuration, a Workflow consists of a Trigger, Steps, and
 Paths that define automation logic. Read on to learn how to configure Workflows.
 
-## Create a new Workflow
+## Create Workflows
 
 To create a new Workflow in your Project:
 
-1. Go to the `Workflows` page.
-2. Click `Create new workflow` button.
+1. Go to the **Workflows** page.
+2. Click the **Create new workflow** button.
 3. Give your Workflow a descriptive `Name` (e.g., `Register patients`,
    `Refer cases`, `Monthly payroll`).
 4. Choose your [Trigger](../build/triggers.md)
@@ -40,5 +40,53 @@ To "turn off" or disable a Workflow:
 
 1. Open the Workflow
 2. Click on the Trigger
-3. Select the `Disable this trigger` checkbox
-4. Select `Save` to save your changes
+3. Select the **Disable this trigger** checkbox
+4. Select **Save** to save your changes
+
+## Limit Concurrency
+
+Workflow **concurrency** is the number pf runs will be allowed for a given
+workflow **_at the same time_**. In OpenFn, project administrators and editors
+are able to limit the maximum number of the runs that can be executed at the
+same time for a workflow. You might do this to ensure "one at a time" serial
+processing or to keep a fast OpenFn workflow from overwhelming the API rate
+limit of some other connected system.
+
+:::info
+
+Note that this setting allows administrators to _limit_ the maximum concurrency
+for a workflow, but the **global maximum** (i.e., the highest concurrency that
+can be reached if a workflow is _not_ limited by a project administrator) will
+be controlled by your OpenFn instance superuser. This global maximum will be
+determined by the computing power and throughput made available to your
+installation.
+
+:::
+
+### What happens when concurrency limit is set on a workflow?
+
+When concurrency limit is configured for a workflow, the maximum number of runs
+that are executed concurrently will not exceed the number that has been set for
+the workflow. For example:
+
+- **Concurrency not set (or = 0)**: There's no artificial limit applied, and
+  this workflow will only be limited by the total computing power available
+  across your OpenFn installation.
+- **Concurrency = 1**: Runs for this workflow will only take place 1-at-a-time.
+  Each run must _finish_ before the next run can start.
+- **Concurrency = 2**: No more than 2 runs for this workflow can be executed at
+  a time and other runs will have stay `enqueued`. If runs "A", "B", and "C" are
+  all enqueued, "A" and "B" will start executing. Once "A" finishes, "C" will
+  start. (No more than 2-at-a-time.)
+
+### Setting Concurrency for a workflow
+
+Concurrency limits can be set via the workflow settings modal on the workflow
+canvas.
+
+1. Click on the settings icon beside the save button on your workflow to open
+   the workflow settings
+2. In the modal, enter the maximum concurrency limit
+3. Click save.
+
+![Configuring Concurrency](/img/configuring-concurrency.png)