Before you start
Use an ordinary survey or reference-list project. The key needs groups:read, groups:write, surveys:write, surveys:read, surveys:publish and assignments:write. Add import permissions for the uploader. Download a client and set DATUMFORMS_SOURCE_GROUP_ID, DATUMFORMS_ALIAS (for example current-items), DATUMFORMS_MONTH_NAME and a durable run ID.
Prepare and activate a month
- Read
groups.listto obtain the source group’s currentpublished_version_id. - Call
monthly.createwithsource_group_id,expected_source_version_idand the new month name. Retain the returned newgroup_id. - Review and publish the new draft through
surveys.reviewandsurveys.publish. - Load the complete period’s data through the supplementary uploader. Reconcile imported identities, rows and metadata before activation.
- Read
aliases.getand switchaliases.setwith the returned revision. For a new alias, use revision 0. - Read
responses.listwithalias=current-itemsto confirm the new collection is active.
Code example
cURL
#!/bin/bash
set -euo pipefail
: "${DATUMFORMS_API_KEY:?Set key}"
: "${DATUMFORMS_RUN_ID:?Set persisted run identity}"
: "${DATUMFORMS_SOURCE_GROUP_ID:?Set source group}"
: "${DATUMFORMS_ALIAS:?Set stable alias}"
: "${DATUMFORMS_MONTH_NAME:?Set new month name}"
API="${DATUMFORMS_API_URL:-https://app.datumforms.com/api/developer-api}"
get() { curl --fail-with-body -sS --get "$API" -H "Authorization: Bearer $DATUMFORMS_API_KEY" "$@"; }
post() { curl --fail-with-body -sS "$API" -H "Authorization: Bearer $DATUMFORMS_API_KEY" -H 'Content-Type: application/json' --data "$1"; }
after=0
while :; do
page=$(get --data-urlencode operation=groups.list --data-urlencode "after_id=$after")
version=$(printf '%s' "$page" | jq -r --argjson id "$DATUMFORMS_SOURCE_GROUP_ID" '.groups[]|select(.id==$id)|.published_version_id')
[ -z "$version" ] || break
after=$(printf '%s' "$page" | jq -r .next_cursor)
[ "$after" != null ] || { echo 'Published source not found' >&2; exit 1; }
done
[ "$version" != null ] || { echo 'Publish the source first' >&2; exit 1; }
month=$(post "$(jq -nc --arg run "$DATUMFORMS_RUN_ID" --argjson source "$DATUMFORMS_SOURCE_GROUP_ID" --argjson version "$version" --arg name "$DATUMFORMS_MONTH_NAME" '{operation:"monthly.create",idempotency_key:($run+":month"),data:{source_group_id:$source,expected_source_version_id:$version,name:$name}}')")
group=$(printf '%s' "$month" | jq -er .group_id)
review=$(get --data-urlencode operation=surveys.review --data-urlencode "group_id=$group")
printf '%s\n' "$review" | jq .
if [ "${DATUMFORMS_PUBLISH:-no}" = yes ]; then
token=$(printf '%s' "$review" | jq -er .review_token)
post "$(jq -nc --arg run "$DATUMFORMS_RUN_ID" --argjson group "$group" --arg token "$token" '{operation:"surveys.publish",group_id:$group,idempotency_key:($run+":publish"),data:{review_token:$token}}')"
fi
# Activate only after the complete month's import is reviewed and applied.
if [ "${DATUMFORMS_ACTIVATE:-no}" = yes ]; then
status=$(curl -sS --get "$API" -H "Authorization: Bearer $DATUMFORMS_API_KEY" --data-urlencode operation=aliases.get --data-urlencode "alias=$DATUMFORMS_ALIAS" --write-out '\n%{http_code}')
code=$(printf '%s\n' "$status" | tail -1)
body=$(printf '%s\n' "$status" | sed '$d')
if [ "$code" = 404 ]; then revision=0
elif [ "$code" = 200 ]; then revision=$(printf '%s' "$body" | jq -er .revision)
else echo "Alias read failed: $code" >&2; exit 1; fi
post "$(jq -nc --arg run "$DATUMFORMS_RUN_ID" --argjson group "$group" --arg alias "$DATUMFORMS_ALIAS" --argjson revision "$revision" '{operation:"aliases.set",group_id:$group,idempotency_key:($run+":activate"),data:{alias:$alias,expected_revision:$revision}}')"
fi
Run the complete monthly cURL script, or use the individual examples for monthly.create, surveys.review, surveys.publish, aliases.get and aliases.set in that sequence. Feed each returned ID into the next request and preserve a separate retry identity for each write.
JavaScript
import {get,post} from './client.mjs';
const sourceId=Number(process.env.DATUMFORMS_SOURCE_GROUP_ID);
const alias=process.env.DATUMFORMS_ALIAS;
const name=process.env.DATUMFORMS_MONTH_NAME;
if (!sourceId || !alias || !name) throw Error('Set source group, alias and month name');
let source,after=0;
do {const page=await get('groups.list',{after_id:after});source=page.groups.find(g=>Number(g.id)===sourceId);after=page.next_cursor;} while(!source && after!==null);
if (!source?.published_version_id) throw Error('Source must be published');
const month=await post('month','monthly.create',{source_group_id:sourceId,expected_source_version_id:source.published_version_id,name});
const review=await get('surveys.review',{group_id:month.group_id});
console.log(JSON.stringify({group_id:month.group_id,review},null,2));
if (process.env.DATUMFORMS_PUBLISH==='yes') await post('publish','surveys.publish',{review_token:review.review_token},{group_id:month.group_id});
if (process.env.DATUMFORMS_ACTIVATE==='yes') {
// Set only after the new month's complete import has been reviewed and applied.
let revision=0;
try {revision=(await get('aliases.get',{alias})).revision;} catch(e) {if (!String(e.message).startsWith('404:')) throw e;}
console.log(await post('activate','aliases.set',{alias,expected_revision:revision},{group_id:month.group_id}));
}
Python
import os, json
from client import get, post
source_id=int(os.environ['DATUMFORMS_SOURCE_GROUP_ID'])
alias=os.environ['DATUMFORMS_ALIAS']
name=os.environ['DATUMFORMS_MONTH_NAME']
after=0
source=None
while True:
page=get('groups.list',after_id=after)
source=next((g for g in page['groups'] if int(g['id'])==source_id),None)
after=page['next_cursor']
if source is not None or after is None: break
if not source or not source.get('published_version_id'): raise RuntimeError('Publish the source first')
month=post('month','monthly.create',dict(source_group_id=source_id,expected_source_version_id=source['published_version_id'],name=name))
review=get('surveys.review',group_id=month['group_id'])
print(json.dumps(dict(group_id=month['group_id'],review=review),indent=2))
if os.environ.get('DATUMFORMS_PUBLISH')=='yes':
post('publish','surveys.publish',dict(review_token=review['review_token']),group_id=month['group_id'])
if os.environ.get('DATUMFORMS_ACTIVATE')=='yes':
# Activate only after the complete month's import has been reviewed and applied.
revision=0
try: revision=get('aliases.get',alias=alias)['revision']
except RuntimeError as error:
if not str(error).startswith('404:'): raise
print(post('activate','aliases.set',dict(alias=alias,expected_revision=revision),group_id=month['group_id']))
Check the result
Cloning retains published question references, logic and translations without copying old responses. The alias points to the newly published group, while historical answers remain in their original collections. If lookup keys restrict group IDs, update their allowlist using keys.lookup_groups and keys.update_lookup_groups before switching the alias.
Troubleshooting
A changed source version, alias revision or key allowlist produces a conflict instead of overwriting a colleague’s update. Reload and reassess. Never activate an incomplete list. Maintain a reference list or run an offline survey.