AppDB Custom Sync Schedule

This article explains how to sync an AppDB collection to its Domo DataSet on a custom schedule, using a scheduled Workflow and a Code Engine function to force a sync on demand instead of on AppDB’s fixed 15-minute cadence.

---

When sync is enabled, a collection syncs every 15 minutes — Domo doesn’t expose a configurable interval — and each sync consumes credits. To sync less often, schedule a Workflow that runs a Code Engine function which turns the collection’s sync on, forces one export, then turns it back off.

For how AppDB collections map to DataSets, see the App DB API overview.

Prerequisites

This guide assumes you’re comfortable with Workflows and Code Engine, and that you can create both.

You’ll also need the target collection’s ID — a UUID. Find it in the AppDB Admin User Interface, in your app’s manifest.json under collectionsMapping[].id, or with a List Collections call. This is the Product API’s collection ID, not the collection name used by the App Framework proxy.

Sync a collection on a schedule

Begin in Domo Workflows.

1. Create a Workflow with a scheduled (timer) trigger set to the time you want the collection to sync — for example, once a day.
2. Add the collection’s ID as a Workflow variable so the same function works for any collection.
3. Create a custom Code Engine package containing a function like the one below. It uses codeengine.sendRequest to call the App DB API — reading the collection to find its datastore, enabling sync, forcing an export, then disabling sync. It always disables sync at the end (even if the export fails) and returns { success, message } so the Workflow can branch on the outcome:

const codeengine = require("codeengine");

// Seconds to wait between retries when the collection is locked.
const RETRY_DELAY_SECONDS = 10;
// A collection is locked while a sync is in progress. If it's still locked
// after this many attempts, treat it as a permanent lock.
const MAX_SYNC_ATTEMPTS = 5;

const wait = (seconds) =>
  new Promise((resolve) => setTimeout(resolve, seconds * 1000));

// A 423 response means the collection is locked (a sync is already running).
// Check the common places an HTTP status can appear on the thrown error.
function isCollectionLocked(error) {
  if (!error) return false;
  const status =
    error.status ||
    (error.response && error.response.status) ||
    error.statusCode;
  const message = error.message || "";
  return status === 423 || /\b423\b/.test(message);
}

// Turn a collection's sync on or off. The collection is identified by the URL
// path, so the body only needs the fields being changed.
function setSyncEnabled(collectionId, enabled) {
  return codeengine.sendRequest(
    "put",
    `/api/datastores/v1/collections/${collectionId}`,
    { syncEnabled: enabled },
  );
}

// Returns { success, message } so the Workflow can branch on the result.
// Sync is always turned back off at the end — even when the export fails —
// so the collection never keeps syncing on the background 15-minute cadence.
async function syncCollection(collectionId) {
  let collection;
  try {
    collection = await codeengine.sendRequest(
      "get",
      `/api/datastores/v1/collections/${collectionId}`,
    );
  } catch (error) {
    console.error(`Could not read collection ${collectionId}:`, error);
    return {
      success: false,
      message: `Could not read collection ${collectionId}.`,
    };
  }

  // Enable sync, then force a single sync. Capture the outcome instead of
  // throwing so the cleanup step below always runs.
  let synced = false;
  let message = "";
  try {
    await setSyncEnabled(collectionId, true);
    await forceSyncWithRetry(collection.datastoreId);
    synced = true;
    message = `Collection ${collectionId} synced.`;
  } catch (error) {
    console.error(`Sync failed for collection ${collectionId}:`, error);
    message = error.message;
  }

  // Always turn sync back off, whether or not the export succeeded.
  try {
    await setSyncEnabled(collectionId, false);
  } catch (error) {
    console.error(`Could not disable sync for ${collectionId}:`, error);
    return {
      success: false,
      message:
        `Sync ${synced ? "succeeded" : "failed"}, but sync could not be turned ` +
        `back off for collection ${collectionId}. It may keep syncing every ` +
        `15 minutes — disable it manually.`,
    };
  }

  return { success: synced, message };
}

// A newly enabled collection can be locked if a sync is already running.
// Retry the export until it succeeds or the lock proves permanent.
async function forceSyncWithRetry(datastoreId) {
  for (let attempt = 1; attempt <= MAX_SYNC_ATTEMPTS; attempt++) {
    try {
      // Code Engine requires a body on POST requests, so send an empty object.
      await codeengine.sendRequest(
        "post",
        `/api/datastores/v1/export/${datastoreId}`,
        {},
      );
      return;
    } catch (error) {
      if (!isCollectionLocked(error)) throw error;

      if (attempt === MAX_SYNC_ATTEMPTS) {
        throw new Error(
          `Collection is still locked after ${MAX_SYNC_ATTEMPTS} attempts. ` +
            `This is likely a permanent lock — please open a Domo support ticket.`,
        );
      }

      console.log(
        `Collection locked (423). Attempt ${attempt} of ${MAX_SYNC_ATTEMPTS} failed; ` +
          `retrying in ${RETRY_DELAY_SECONDS}s...`,
      );
      await wait(RETRY_DELAY_SECONDS);
    }
  }
}

Note: A collection returns 423 Locked while a sync is already running, so the function retries the export every RETRY_DELAY_SECONDS (10 seconds by default), up to MAX_SYNC_ATTEMPTS (5) times. If it’s still locked after the final attempt, the lock is likely permanent — contact your Domo account team to open a support ticket. Keep RETRY_DELAY_SECONDS × MAX_SYNC_ATTEMPTS comfortably under Code Engine’s 5-minute runtime limit.

4. Call the function from the Workflow, mapping your collection-ID variable to the function’s collectionId parameter. The function returns success (Boolean) and message (Text): branch on success to react to a failed sync — for example, send a notification — and surface message for the reason. Because sync is turned back off even on failure, a failed run won’t leave the collection syncing on the 15-minute cadence, unless message reports that sync itself couldn’t be disabled, which needs manual follow-up.