Release/next

articles/2021-05-24-commcare-events.md

@@ -23,7 +23,7 @@ to Salesforce integration on your own.
 First, most people make use of CommCare's "Data Forwarding" feature to send form
 submissions and changes in cases (creation, update, closure, etc.) to OpenFn in
 real-time. You can read about that
-[here](/adaptors/commcare#webhook-forward-cases-andor-forms-from-commcare-to-openfn-using-rest-service)
+[here](/adaptors/commcare#webhook-or-data-forwarding-setup-commcare-to-openfn)
 but the key consideration at this planning stage is _when_ you'll be performing
 operations—`create(...)`, `update(...)`, `upsert(...)`, `query(...)`,
 `(bulk(...)`, etc.—in Salesforce and what data you'll have access to.
@@ -369,8 +369,7 @@ this all up on your own are:
 1. this site (docs.openfn.org), and
 2. the [forum](https://community.openfn.org) (community.openfn.org)
 
-Read through the
-["What is an integration"](/documentation/tutorials/tutorial),
+Read through the ["What is an integration"](/documentation/tutorials/tutorial),
 ["OpenFn Concepts"](/documentation/get-started/terminology), and
 ["Build"](/documentation/build/workflows) sections if you're a thorough,
 background-first kind of learner. If you crave snippets and sample job code,

docs/build-for-developers/cli-collections.md

@@ -22,7 +22,7 @@ You can use the CLI to:
 - Experiment with query syntax to get the keys you need
 - Update mapping objects and lookup tables from local (or source-controlled)
   files
-- Manually remove unneeded data
+- Manually remove data
 
 :::tip
 
@@ -59,10 +59,11 @@ We do this using Personal Access Tokens. See
 more details.
 
 One you have a PAT, you need to pass it in to the CLI. The easiest way to do
-this is to set your `OPENFN_PAT` env var, which the CLI will use automatically.
+this is to set an env var `OPENFN_API_KEY`, or use a `.env` file. The CLI will
+automatically use this value for all requests.
 
-If you're using multiple access tokens, you can pass `--token` to the CLI to
-override the default.
+You can also pass `--token` to the CLI to override the value loaded from your
+environment.
 
 ```bash
 openfn collections get my-collection \* --token $MY_OPENFN_PAT
@@ -78,16 +79,15 @@ all examples will work.
 
 ## Setting a server
 
-By default, the CLI will point to our primary platform at
-https://app.openfn.org.
+By default, the CLI will point to our cloud app at https://app.openfn.org.
 
 If you're running from open source or using a different deployment, you'll also
 need to tell the CLI which Collections server to use.
 
-You can do this by passing `--lightning` directly:
+You can do this by passing `--endpoint` directly:
 
 ```bash
-openfn collections get my-collection \* --lightning http://localhost:4000
+openfn collections get my-collection \* --endpoint http://localhost:4000
 ```
 
 Or by setting the `OPENFN_ENDPOINT` environment variable.
@@ -103,6 +103,25 @@ openfn collections get my-collection \* --log debug
 
 :::
 
+## Project Name Uniqueness
+
+In Lightning releases prior to 2.17.0, collection names were globally unique.
+
+Since 2.17.0, collection names are scoped to a project, which means an OpenFn
+instance can have multiple collections with the same name.
+
+Any requests to the collections API will attempt to resolve a collection name to
+a single collection. But if there are conflicts, the server will return a 409
+error code.
+
+To resolve this, pass a project id
+
+```bash
+openfn collections get <collection-name> <key> --project_id 1d28c76c-e4ef-4e58-ac1e-464dc479946c
+```
+
+You can also set the project ID through an env var, or use the `-p` shortcut.
+
 ## Fetching items
 
 You can fetch items from a Collection by passing a collection name and a key, or
@@ -262,3 +281,25 @@ running the delete:
 ```bash
 openfn collections remove my-collection 2024* --dry-run
 ```
+
+## Troubleshooting
+
+### Error 409: multiple collection names matched
+
+This means that you've requested a collection by name, but the server has
+multiple collections with that name.
+
+You must scope your request to the correct project by including the project id
+in your request.
+
+You can either pass this directly:
+
+```
+openfn collections get my-collection \* --project-id 1d28c76c-e4ef-4e58-ac1e-464dc479946c
+```
+
+Or set an env var (`.env` files are supported):
+
+```
+OPENFN_PROJECT_ID=1d28c76c-e4ef-4e58-ac1e-464dc479946c
+```

docs/build-for-developers/cli-walkthrough.md

@@ -482,7 +482,7 @@ fn(state => {
 
 As you can see from our logs that helper function `dataValue` has a TypeError,
 to troubleshoot this you can go to the documentation for **dataValue ->
-[docs.openfn.org/adaptors/packages/common-docs/#datavaluepath--operation](/adaptors/packages/common-docs/#datavaluepath--operation)
+[docs.openfn.org/adaptors/packages/common-docs/#datavalue](/adaptors/packages/common-docs/#datavalue)
 **
 
 According to the docs, dataValue takes a path as input, which is of the string
@@ -557,9 +557,9 @@ each('posts[*]', state => {
 </details>
 
 Notice how this code uses the `each` function, a helper function defined in
-[language-common](/adaptors/packages/common-docs/#eachdatasource-operation--operation)
-but accessed from this job that is using `language-http`. Most adaptors import
-many functions from `language-common`.
+[language-common](/adaptors/packages/common-docs/#each) but accessed from this
+job that is using `language-http`. Most adaptors import many functions from
+`language-common`.
 
 Run **openfn getPosts.js -a http -s tmp/state.json -o tmp/output.json**
 

docs/deploy/options.md

@@ -46,11 +46,11 @@ local/government-managed servers, you might:
    preparations**:
    1. Assess the **value of the solution** itself—is it solving the problems you
       thought it would?
-   2. Asses your **data residency requirements**—do you need to run this
+   2. Assess your **data residency requirements**—do you need to run this
       solution in country?
    3. Assess your team’s technical **DevOps capacity**—how are other local
       deployments of DPGs going?
-   4. Assess your countries computing, storage, and networking
+   4. Assess your country's computing, storage, and networking
       infrastructure—what options\* are available for servers and network
       connectivity?
    5. Determine if a **"zero-persistence"** cloud solution or a **locally