Multi Signoff Workflow

Goals

  • Create some records

  • Request review

  • Preview changes in the browser

  • Approve/Decline the changes

Prerequisites

This guide assumes you have already installed and set up the following:

  • cURL

  • jq (optional)

  • a local instance with multi signoff enabled or access/contact with two users that have permissions on STAGE/PROD

We’ll refer the running instance as $SERVER (eg. http://localhost:8888/v1 or https://remote-settings.allizom.org/v1 via the VPN).

Note

If you need to give additional users access to your collection on STAGE/PROD you must edit the collection manifest.

Introduction

Multi signoff basically consists in 3 steps:

  1. Editors create/update/delete records on the main-workspace bucket

  2. Editors request review. The changes are automatically published in the main-preview bucket.

  3. Reviewers can configure their browser to preview the changes, and will approve (or decline) the review request. If approved, the changes are published in the main bucket.

See also

If you’re interested by workflows in the Admin UI, check out the screencasts instead!

Create some users

If you’re not using STAGE or PROD, we’ll need to create some reviewer and editor accounts on the server. We’ll reuse the admin superuser seen in previous tutorials.

curl -X PUT ${SERVER}/accounts/editor \
     -d '{"data": {"password": "3d1t0r"}}' \
     -H 'Content-Type:application/json'

curl -X PUT ${SERVER}/accounts/reviewer \
     -d '{"data": {"password": "r3v13w3r"}}' \
     -H 'Content-Type:application/json'

Note

In STAGE or PROD, humans authenticate via LDAP/OpenID Connect. But scripted/scheduled tasks can also have their dedicated account like above. Ask us!

Create a collection

The main-workspace bucket is where every edit happens.

We first have to create a new collection (eg. password-recipes). We’ll use the editor account:

curl -X PUT ${SERVER}/buckets/main-workspace/collections/password-recipes \
     -H 'Content-Type:application/json' \
     -u editor:3d1t0r

Note

In PROD, only administrators are allowed to create collections, and the request is made via Bugzilla.

Now that we created this collection, two groups should have been created automatically. Check their presence and content with:

curl -s ${SERVER}/buckets/main-workspace/groups/password-recipes-editors | jq
curl -s ${SERVER}/buckets/main-workspace/groups/password-recipes-reviewers | jq

Manage reviewers

Only the members of the password-recipes-editors group are allowed to request reviews for the records changes.

Only the members of the password-recipes-reviewers group are allowed to approve/decline them.

We will add our reviewer user above to the password-recipes-reviewers group with this JSON PATCH request:

curl -X PATCH $SERVER/buckets/main-workspace/groups/password-recipes-reviewers \
     -H 'Content-Type:application/json-patch+json' \
     -d '[{ "op": "add", "path": "/data/members/0", "value": "account:reviewer" }]' \
     -u editor:3d1t0r

Note

When using internal accounts the, user IDs are prefixed with account:. In STAGE/PROD, most user IDs look like this: ldap:jdoe@mozilla.com.

Change records and request review

See also

Check out the dedicated screencast for the equivalent with the Admin UI!

Create (or update or delete) some records:

for i in `seq 1 10`; do
    curl -X POST ${SERVER}/buckets/main-workspace/collections/password-recipes/records \
         -H 'Content-Type:application/json' \
         -d "{\"data\": {\"property\": $i}}" \
         -u editor:3d1t0r
done

And request review:

curl -X PATCH ${SERVER}/buckets/main-workspace/collections/password-recipes \
        -H 'Content-Type:application/json' \
        -d '{"data": {"status": "to-review"}}' \
        -u editor:3d1t0r

At this point the changes were published to the main-preview bucket, which is publicly readable:

curl -s ${SERVER}/buckets/main-preview/collections/password-recipes/records | jq

The collection metadata now contain some signature information:

curl -s ${SERVER}/buckets/main-preview/collections/password-recipes | jq .data.signature

The monitor/changes endpoint mentions the new collection password-recipes:

curl -s ${SERVER}/buckets/monitor/collections/changes/records | jq

Preview changes in the browser

Important

It is recommended to use the Remote Settings DevTools instead of changing preferences manually.

The following preferences must be changed to the following values in about:config:

  • services.settings.server : http://localhost:8888/v1

  • services.settings.default_bucket : main-preview

From your code, or the browser console, register the new collection by listening to the sync event and trigger synchronization:

const { RemoteSettings } = ChromeUtils.importESModule("resource://services-settings/remote-settings.sys.mjs")

RemoteSettings("password-recipes").on("sync", ({ data }) => {
  data.current.forEach(r => dump(`${r.property}\n`));
});

Then force a synchronization manually with:

RemoteSettings.pollChanges();

Approve/Decline changes

See also

Check out the dedicated screencast for the equivalent with the Admin UI!

Using the reviewer authentication, change the collection status to either to-sign (approve) or work-in-progress (decline).

curl -X PATCH ${SERVER}/buckets/main-workspace/collections/password-recipes \
     -H 'Content-Type:application/json' \
     -d '{"data": {"status": "to-sign"}}' \
     -u reviewer:r3v13w3r

At this point the changes were published to the main bucket, which is publicly readable:

curl -s ${SERVER}/buckets/main/collections/password-recipes/records | jq

The main collection metadata now contain some signature information:

curl -s ${SERVER}/buckets/main/collections/password-recipes | jq .data.signature

In the browser, the following preferences must be reset to their default value:

  • services.settings.default_bucket : main