DatumForms.
Join the panel Sign in Create a survey

DATUMFORMS DOCUMENTATION

Repeat survey collections with stable group references

Clone the published source, load the next period and switch one stable reference.

For developers

Updated 15 November 2026

On this page

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

  1. Read groups.list to obtain the source group’s current published_version_id.
  2. Call monthly.create with source_group_id, expected_source_version_id and the new month name. Retain the returned new group_id.
  3. Review and publish the new draft through surveys.review and surveys.publish.
  4. Load the complete period’s data through the supplementary uploader. Reconcile imported identities, rows and metadata before activation.
  5. Read aliases.get and switch aliases.set with the returned revision. For a new alias, use revision 0.
  6. Read responses.list with alias=current-items to 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

Download monthly.sh

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.

Need help with this task? Contact DatumForms. Include the article URL and the step you reached.

Tracking preferences

Essential functions stay on. Choose whether to allow optional tracking on this website. You can change your choices in the footer at any time.

Read our privacy policy