Algorithm management

Algorithms build the transaction for server-managed merge and unmerge. Start with a built-in algorithm, or create a JavaScript script for your policy.

Built-in algorithms

Select an algorithm with merge-algorithm or unmerge-algorithm in the request. These are separate catalogs: the same ID can exist in both.

MDMBOX_BUILT_IN_ALGORITHMS controls which built-ins are available. Unset enables all; an empty value disables all; simple,strict enables only those two. Unknown IDs prevent startup. Changing this setting requires a restart and does not restrict custom algorithms.

When disabling a default (simple or restore), select an available algorithm explicitly. An unavailable selection returns HTTP 400.

Create or edit a script

1. Open Algorithms → Merge or Algorithms → Unmerge in the Admin UI.
2. Select an existing algorithm and choose Duplicate, or choose New Algorithm.
3. Give the script a unique ID and edit its JavaScript.
4. Save. MDMbox validates the entry point; the saved script is available to subsequent requests without a restart.

Use function merge(input, mdm) or function unmerge(input, mdm) and return {plan: bundle} with an optional OperationOutcome. See the JavaScript algorithm API for inputs, helpers, examples, limits, and allowed changes. Use operation preview to inspect a script's proposed changes before executing them.

Database scripts are editable and can be deleted. Built-in and Git scripts are read-only; duplicate them to create an editable database copy. The editor shows the storage type and, for Git, the source, path, and published commit.

Only trusted administrators should manage scripts and Git sources. Algorithm code can read and propose changes to the resources allowed by its operation.

Git algorithm storage

Store self-contained JavaScript files in a small repository:

merge/
  identifier-union.js    # function merge(input, mdm)
unmerge/
  custom-restore.js      # function unmerge(input, mdm)

The filename without .js is the algorithm ID. IDs are 1–64 characters, start with a letter or digit, and contain only letters, digits, ., _, or -.

Only regular .js files directly inside these directories are supported. Nested files, symlinks, and submodules there are rejected; other repository paths are ignored. A repository must contain 1–100 algorithm files, with at most 1 MiB per file and 16 MiB of source in total. Imports and build steps are not supported.

Add and synchronize a source

1. Open Algorithms → Configuration and choose Add Git source.
2. Enter a unique source ID, repository URL, and ref. Use HEAD, a full branch ref such as refs/heads/main, a full tag ref, or a 40-character commit SHA that the remote allows fetching.
3. For private repositories, configure access as described below. Choose Save source.
4. Choose Sync to fetch and publish scripts.

Sync fetches and validates all scripts, then publishes both catalogs together. A failed sync keeps the last successful catalog and commit. Operations use the published scripts even when Git is unavailable. A sync does not change an operation already in progress.

After changing scripts in Git, choose Sync again. Branches and tags are resolved on each sync; a commit SHA stays pinned. Fetch and validation must finish within 60 seconds, so keep the repository and its history small.

Private repository access

For HTTPS, mount a read-only token file accessible to the container's app user. Enter its absolute path and the Git username in the source form. Use a mounted PEM CA file for a private certificate authority.

For SSH, use a URL such as ssh://git@git.example/team/mdm-algorithms.git. Provide a read-only deploy key and verified known_hosts under the runtime user's .ssh directory, or use an SSH agent. Interactive passwords and host-key prompts are not supported. The Docker image includes Git and OpenSSH; other deployments must install them.

Required credential and CA files must be available on every instance that can perform Sync. Stored token contents and credential-file paths are not returned to the browser.

Edit or remove a source

Edit changes source configuration; published scripts stay unchanged until a successful Sync. Blank credential fields keep existing values; use the clear checkboxes to remove them. Reload the form if another administrator has changed it.

Remove deletes the source and its published Git scripts. It keeps the remote repository, database-authored scripts, and past operation Tasks. Running operations keep the script they already selected.

Sources and published scripts survive restarts. Up to 20 sources are allowed, including the environment source. Up to two syncs can run per instance, and one sync per source can run across instances. After an interrupted sync, wait 90 seconds before retrying.

Configure a source through the environment

You can also configure the reserved environment source at deployment time:

MDMBOX_ALGORITHM_GIT_URL: https://git.example/team/mdm-algorithms.git
MDMBOX_ALGORITHM_GIT_REF: refs/tags/release-1
MDMBOX_ALGORITHM_GIT_USERNAME: deploy-user
MDMBOX_ALGORITHM_GIT_TOKEN_FILE: /run/secrets/algorithm-git-token

This source appears in Algorithms → Configuration with an Environment badge. You can Sync it there, but editing or removing its configuration requires changing the environment and restarting. It refreshes at startup; an invalid configuration or failed refresh prevents startup.

Removing MDMBOX_ALGORITHM_GIT_URL removes only this source. Other runtime sources remain available. Keep environment settings consistent across instances sharing the database. See Configuration reference for all variables.

Which script runs?

For a given operation and ID, MDMbox chooses an enabled built-in first, then Git, then database storage. Disabling a built-in allows a custom script with the same ID to be selected. The database merge ID simple is reserved.

Two Git sources cannot publish the same operation and algorithm ID. A conflicting sync fails without changing published scripts. Removing a Git source can expose a database script with the same ID.

Each executed operation records the selected algorithm and script SHA-256 in its Task. Git algorithms also record the source ID, exact commit, and path. Repository URLs and credentials are not copied to Tasks.

Catalog views, script and source changes, and manual sync are audited.

Troubleshooting algorithm failures

An algorithm exception or invalid plan returns HTTP 500 with Merge algorithm failed or Unmerge algorithm failed. Check the application log for the algorithm ID and error details.

When reporting a failure, include the MDMbox version, algorithm ID, preview setting, and the error log with its timestamp.