Automation with app2dat

Introduction

Recurring administrative work — exporting lists, generating certificates, transferring data between groups, sending notifications — never has to be done by hand in app2dat. The automation system runs small JavaScript programs (scripts) that access your club data through the documented a2d interface: members, data fields, sessions, attendance, chats, documents and more.

This manual is structured like a textbook: chapters 2–4 introduce the scripting world with simple examples. Chapters 5–9 form the complete reference of the a2d API. They are followed by a chapter on event triggers, three in-depth practical examples from real clubs — and, to conclude, working with the AI automation assistant that writes the scripts for you on request.

Where automations live: the four levels

Automations exist on four levels (scopes) — each with its own automation manager and its own magic-wand menu :

The scope determines which context a script knows automatically (chapter 3) and how far saved variables reach (chapter 9). Most examples in this manual are group scripts — they run inside the group whose data they work on.

Safety: sandbox and permissions

• Server-side sandbox. Scripts run isolated on the server (Jint engine) — separate from the base software, with hard limits: 50 MB memory, 100,000 statements, limited recursion depth. A faulty script cannot damage the app.
• Your permissions, never more. Every a2d method checks the permissions of the executing user: reading requires at least member, writing at least manager/admin. A script only sees and changes what you could see and change in the app yourself.
• Everything is logged. Every run produces an execution report with log, result and error messages.

Your first script

The best way in is a script that changes nothing — it only greets you. Along the way you learn the complete working cycle: create, write, run, read the report.

Opening the automation manager

1. Open a group in which you are an admin and switch to Administration.
2. Open the Automation manager via the Automation menu item. On the left you see the tree view (scripts and folders), on the right the code editor.
3. Create a script with New script and give it a meaningful name, e.g. Greeting.

Hello app2dat

Type (or paste) this code into the editor and save:

// My first script: greets the executing user with their profile name.
log("Script started");

const profile = await a2d.profile.get(a2d.context.profileId);
await a2d.ui.showMessage("Hello", "Great to see you, " + profile.firstName + "!");

result.set("message", "Greeting shown for " + profile.firstName);

Run the script with the Execute button in the editor. Three things happen that you will find in every script:

• log(…) writes a line into the execution log — your most important debugging tool.
• await a2d.… calls the scripting API. Almost all a2d methods are asynchronous — the await in front is mandatory (chapter 3).
• result.set("message", …) hands over the result of the run — it appears in the execution report.

The execution report

After every run the editor shows the execution report with three areas: Log (all log lines), Result (what result handed over) and Error (JavaScript error message including line number, if something went wrong). The server keeps the last five runs per level — the history icon brings them back at any time, including scripts that ran in the background via event triggers.

Script fundamentals

Scripts are plain, modern JavaScript. If you have programmed before you will feel at home immediately — but the scripting environment has a few peculiarities you should know. This chapter is the foundation for everything that follows.

The execution context: a2d.context

Every script knows where it runs. The (read-only) object a2d.context provides:

A group script almost always starts with this safeguard:

const groupId = a2d.context.groupId;
if (!groupId) { result.set("message", "Please run this script inside a group."); return; }

await — always, but one at a time

Almost all a2d methods are asynchronous and need an await. Only a2d.vars.set/get/getAll, a2d.member.getSelected() and a2d.date.* are synchronous.

// WRONG — parallel a2d calls are not allowed in the sandbox:
// const [a, b] = await Promise.all([a2d.group.get(1), a2d.group.get(2)]);

// RIGHT — run the calls one after the other:
const a = await a2d.group.get(1);
const b = await a2d.group.get(2);

The sandbox works with a single engine instance: Promise.all/race over a2d calls cause runtime errors — the static check step of the AI assistant reports this pattern as an error.

Log, result, parameters

// ALWAYS output structured results via setJson:
result.setJson(JSON.stringify({ count: 3, names: ["Anna", "Ben", "Cem"] }, null, 2));

// NOT: result.set("x", object)            → appears as "[object Object]"
// NOT: result.set("x", JSON.stringify(…)) → double-escaped and hard to read

Types & formats — the three golden rules

1. Data-field IDs are strings. Even when they look numeric ("1", "17"): fields are always addressed via their string ID. a2d.memberData.getFieldId(groupId, "Field name") resolves the ID from the name.
2. Dates are ISO. The canonical format is yyyy-MM-dd. Dialog inputs may arrive in local format — normalise with a2d.date.toIso(value) before saving or passing on; use a2d.date.format(value) for display.
3. Dialog and parameter values are strings. showInput returns strings even for number and bool fields — convert yourself: parseInt(res.x, 10), res.flag === "1". The same applies to everything from params.get(…).

Handling errors

If an a2d method throws an error (e.g. missing permission), the script aborts and the execution report shows the message including the line number. Where a single failure must not stop the run — for example in a loop over many members — use try/catch:

for (const pid of members) {
    try {
        await a2d.memberData.set(groupId, pid, fieldId, "OK");
    } catch (e) {
        log("Skipped (profile " + pid + "): " + e.message);
    }
}

Be careful with result objects coming from the backend (e.g. from attendance.profilesAttendances): they behave like .NET dictionaries — accessing a key that does not exist can throw. Access defensively (try/catch or existence check).

Executing in the editor

The Execute button in the editor runs the script for real — with real data and real writes; there is no separate dry run. The only special case: if the script uses a2d.member.getSelected(), the editor asks for the member selection in a dialog beforehand — when started from the member list, its current selection is used instead. So approach new scripts step by step: build them read-only first (list/get + result), check the execution report — and only then add writes, using a small member selection for the first real run.

Members, data & dialogs

Time to get practical: the three most common ingredients of almost every club script are the member list, the group’s data fields and dialogs for input and output. We assemble them step by step.

Reading and filtering members

a2d.member.list(groupId) returns all members of the group — each with profileId, status, the embedded profile object (first name, last name, …) and the data fields in data. The following script lists all inactive members (status not equal to "ACT") in a readable form:

// Lists members of the current group filtered by status.
const groupId = a2d.context.groupId;
if (!groupId) { result.set("message", "Please run this script inside a group."); return; }

const members = await a2d.member.list(groupId);

const inactive = (members || [])
    .filter(m => (m.status || "") !== "ACT")
    .map(m => {
        const fn = m.profile ? (m.profile.firstName || "") : "";
        const sn = m.profile ? (m.profile.secondName || "") : "";
        return {
            profileId: m.profileId,
            name: (fn + " " + sn).trim() || ("Profile " + m.profileId),
            status: m.status
        };
    });

log("Inactive members: " + inactive.length);
result.setJson(JSON.stringify({ count: inactive.length, members: inactive }, null, 2));

Using the member-list selection

Many scripts should not affect all members but the ones the user has selected in the member list. That is exactly what a2d.member.getSelected() returns — synchronously, as an array of profile IDs:

const selected = a2d.member.getSelected() || [];
if (selected.length === 0) {
    await a2d.ui.showMessage("Note", "Please select members in the list first.");
    return;
}
for (const pid of selected) {
    // pid is a number (profile ID), not an object
}

Reading and writing data fields

The custom columns of a group (see Administration Manual, chapter 8) are accessed via a2d.memberData. Fields are addressed via their string ID; you resolve the ID once from the field name:

const noteId = await a2d.memberData.getFieldId(groupId, "Note");
if (!noteId) { result.set("message", "Data field 'Note' not found."); return; }

// Read: all field values of one member as { fieldId: value }
const data = (await a2d.memberData.get(groupId, pid)) || {};
log("Current note: " + (data[noteId] || "—"));

// Write: set a single field (manager role or higher)
await a2d.memberData.set(groupId, pid, noteId, "Fee 2026 paid");

After writing changes it pays to end the script with await a2d.ui.refresh(); — the visible member list updates immediately, without the user reloading the view.

Dialogs: ask instead of hard-coding

Through a2d.ui your script talks to the user. The following example combines an input dialog with a member search — note the pattern: one dialog, whose result is read via res[id], and a null check for “cancel”:

// Searches members via an input dialog (first or last name).
const res = await a2d.ui.showInput("Search members", [
    { id: "q", name: "First or last name", type: "string", required: false }
]);
if (!res) return; // Cancelled by the user

const term = ((res && res.q) || "").toString().trim().toLowerCase();

const members = await a2d.member.list(a2d.context.groupId);
const matches = (members || []).filter(m => {
    const fn = (m.profile && m.profile.firstName ? m.profile.firstName : "").toLowerCase();
    const sn = (m.profile && m.profile.secondName ? m.profile.secondName : "").toLowerCase();
    return term === "" || fn.includes(term) || sn.includes(term);
});

log("Matches: " + matches.length);
result.setJson(JSON.stringify({ term: term, count: matches.length }, null, 2));

Besides showInput there are showMessage (OK message), confirm (yes/no), showSelect (choice list) and pickFile (choose a file — returns the file’s content). All details and field types are in chapter 9.

Reference: profiles, groups & members

From here on the manual becomes a reference. Conventions: all methods are asynchronous (await!) unless explicitly marked “synchronous”. Reading requires at least the member role, writing at least manager/admin — methods that go beyond this are marked. Optional parameters carry a ?.

a2d.profile — profiles

a2d.group — groups

a2d.event — event folders

Event folders group event groups at profile level (see Administration Manual, chapter 6). The groups themselves are created with group.create({ …, eventId }).

a2d.member — members

Important status codes: ACT active · RNAC registered member (counts as active) · INV invited · REQ join requested · RACT reactivation requested · NAC signed off/inactive · DEL removed.

a2d.memberData — data fields

Field types for createField: string, number (integer), decimal, date, time, list, bool, pay (payment), doc (document), grmmb (member link). Common aliases like text, int, select, checkbox, payment, file, members are translated automatically.

Visibility codes (access) — what members see of the field: "-" invisible (managers only) · "MR" visible but not editable · "MW" editable by the member.

Reference: sessions & attendance

a2d.session — sessions

a2d.attendance — attendance

Reference: communication & tasks

a2d.topic — topics/chats

a2d.workTask — tasks

a2d.chat — messages

a2d.notification — push notifications

Reference: PDF, export & import

a2d.document — documents & folders

a2d.pdf — PDF generation

PDFs are always built in the same order: prepare() → addPage() → addText()/addImage() → close…(). All measurements are millimetres; an A4 sheet is 210 × 297.

a2d.export — exports & downloads

options for membersCSV: separator (default ";"), includeHeader (default true), onlyActive, profileIds (only these, in output order), headers ({ fieldId: "heading" }) and attendance for event groups: from/to (required, ISO), count (“present/total” column), sessions (one column per session), responsibility (transposed responsibility matrix), allDates.

layout for label sheets (mm; defaults = Avery-Zweckform 3652, 3 × 7 labels of 70 × 42.3 on A4): pageWidth, pageHeight, width, height, cols, rows, marginLeft, marginTop, gapHorizontal, gapVertical, skip (skip labels already used).

a2d.import — CSV import

Reference: dialogs, variables & tools

a2d.ui — dialogs & interface

Field objects for showInput: id (required, except for type:"label"), name (caption), type, required (default false), description. Types (always lowercase): string · number · decimal · date · time · bool · label (plain hint text); unknown types fall back to string. All returned values are strings (chapter 3).

a2d.vars — variables

Reach (scope): without = current level · "group" this group · "event" this event folder · "profile" all groups of the same profile · "user" all profiles of the user. Saving and loading must use the same scope; to pass data between groups of different profiles, use "user".

a2d.date — dates (synchronous)

a2d.automation — calling scripts from scripts

// Caller: start a sub-script, pass parameters, use the result
const r = await a2d.automation.executeScript("Calculate fee", {
    base: "42.50",
    factor: "1.2"
});
log("Amount: " + r.amount + " " + r.currency);

// Sub-script "Calculate fee":
// const base   = parseFloat(params.get("base"));
// const factor = parseFloat(params.get("factor"));
// if (isNaN(base) || isNaN(factor)) { result.set("message", "Invalid parameters"); return; }
// result.setJson(JSON.stringify({ amount: (base * factor).toFixed(2), currency: "EUR" }));

This is how you split larger automations into reusable building blocks — for example a central fee calculation used by several scripts.

Event triggers

So far you have started scripts by hand. Event triggers turn this around: the script runs automatically as soon as something changes in the group — with no interaction at all. Event triggers are configured on group scripts — in the editor via the script’s Triggers dialog (chapter 14). In addition, the server evaluates profile-wide event scripts (profile scope), which fire for all groups of the profile.

The three event types

A script can subscribe to several event types at once and branch on event.type. Important: event scripts run on behalf of the user who triggered the change — not as “system”. They can do exactly what the triggering user could do.

The event.* parameters

The script receives the event data via params.get(…) — all values as strings, lists comma-separated:

Example: one watchdog script for all three events

This script (from the built-in example library) subscribes to all three event types and sends a designated person a private message with the details:

// Reacts to ALL three event-trigger types and sends a private message with the relevant data.
// Set up as an event trigger and tick all three event types (group scope).
// event.actorProfileId = the acting profile (self-action: the changed profile; admin action: the admin's profile).

const NOTIFY_PROFILE_ID = 1;   // recipient of the notification (change this)

const type = params.get("event.type");
if (!type) { result.set("message", "This script is meant for an event trigger (no event.type present)."); return; }

const groupId = params.get("event.groupId");
const sender  = parseInt(params.get("event.actorProfileId") || "0", 10); // 0 = resolve sender automatically

log("Event received: " + type + " (group " + groupId + ")");

// comma-separated list -> array (empty entries removed)
function asList(csv) {
    return (csv || "").split(",").map(s => s.trim()).filter(s => s.length > 0);
}

let text;

if (type === "MemberStatusChanged") {
    // status of one/more members changed (join, unregister, set status ...)
    const ids = asList(params.get("event.profileIds"));
    const parts = ids.map(id => "profile " + id + " -> " + (params.get("event.status." + id) || "?"));
    text = "Status change in group " + groupId + ": " + parts.join(", ");

} else if (type === "MemberDataChanged") {
    // member data changed
    const profileId = params.get("event.profileId");
    const fields = asList(params.get("event.changedFields"));
    const parts = fields.map(f => f + " = " + (params.get("event.field." + f) || ""));
    text = "Data change for profile " + profileId + " in group " + groupId
         + (parts.length ? ": " + parts.join(", ") : "");

} else if (type === "MemberAttendanceChanged") {
    // attendance changed (memberId -1 = whole session cancelled)
    const date      = params.get("event.date");
    const sessionId = params.get("event.sessionId");
    const ids       = asList(params.get("event.memberIds"));
    if (ids.length === 1 && ids[0] === "-1") {
        text = "Session " + sessionId + " on " + date + " (group " + groupId + ") was cancelled.";
    } else {
        text = "Attendance change in group " + groupId + ", session " + sessionId
             + " on " + date + ": profile(s) " + ids.join(", ");
    }

} else {
    text = "Unknown event: " + type;
}

// send: sender = the trigger's acting profile, recipient = NOTIFY_PROFILE_ID
try {
    await a2d.chat.sendPrivateMessage(NOTIFY_PROFILE_ID, text, sender);
    result.set("message", "Sent to profile " + NOTIFY_PROFILE_ID + ": " + text);
} catch (e) {
    result.set("message", "Send failed: " + e.message + " | " + text);
}

Practice: evaluating attendance across several groups

The first large practical example comes — like the two that follow — from the curated example library that the automation assistant also draws on. The task: a club trains in several groups. For the selected members, count how often each of them was present anywhere in the queried period — and write count and percentage back into data fields of the current group.

Prerequisites

• The current group has the data fields “Anzahl” (count) and “Prozent %” (percent).
• The executing user manages the training groups involved (the attendance matrix is an admin function).
• Members are selected in the list before starting.

The script

// Calculate training attendances
// For each selected member, counts the attendances across several training groups within the
// requested period and writes Present ("Anzahl") and percent ("Prozent %") into the
// current group. The percent basis (max. number of trainings) is requested in the dialog.

const groupId = a2d.context.groupId;
if (!groupId) { await a2d.ui.showMessage("Error", "Please run this script inside a group."); return; }

const selectedMembers = a2d.member.getSelected() || [];
if (selectedMembers.length === 0) {
    await a2d.ui.showMessage("Error", "No members selected");
    return;
}

const anwesendId = await a2d.memberData.getFieldId(groupId, "Anzahl");
const prozentId = await a2d.memberData.getFieldId(groupId, "Prozent %");
if (!anwesendId || !prozentId) {
    await a2d.ui.showMessage("Error", "Data fields 'Anzahl' and/or 'Prozent %' not found.");
    return;
}

// Pre-fill from persistent variables
a2d.vars.set("datFrom", await a2d.vars.load("datFrom") || new Date().toLocaleDateString("de-DE"));
a2d.vars.set("datTo", await a2d.vars.load("datTo") || new Date().toLocaleDateString("de-DE"));
a2d.vars.set("maxTrainings", await a2d.vars.load("maxTrainings") || "");

const inputFields = [
    { type: "label", name: "All fields must be filled in" },
    { type: "date", id: "datFrom", name: "Date from*", description: "" },
    { type: "date", id: "datTo", name: "Date to*", description: "" },
    { type: "number", id: "maxTrainings", name: "Max. number of trainings*",
      description: "Enter here the maximum number of possible trainings for the % calculation." }
];
const result = await a2d.ui.showInput("Evaluate attendances", inputFields);
if (!result) return; // Cancelled by user

const mt = parseInt(result["maxTrainings"], 10);
if (isNaN(mt) || mt <= 0) {
    await a2d.ui.showMessage("Error", "Please enter a valid max. number of trainings (greater than 0).");
    return;
}

await a2d.vars.save("datFrom", result["datFrom"]);
await a2d.vars.save("datTo", result["datTo"]);
await a2d.vars.save("maxTrainings", result["maxTrainings"]);

// Training groups to sum over (enter the IDs of your own groups)
const groupIds = [111, 222, 333];
const counts = {};

for (const gid of groupIds) {
    const pa = await a2d.attendance.profilesAttendances(selectedMembers, gid, result["datFrom"], result["datTo"], null);
    if (!pa) continue;

    for (const pid of selectedMembers) {
        // pa is a .NET dictionary; accessing a key that does NOT exist can
        // throw an exception → guard defensively (skip member without attendance).
        let dates;
        try { dates = pa[pid]; } catch (e) { dates = null; }
        if (!dates) continue;

        if (!counts[pid]) counts[pid] = 0;
        for (const dat of Object.keys(dates)) {
            if (dates[dat] === "1") counts[pid]++;
        }
    }
}

let written = 0;
for (const pid of Object.keys(counts)) {
    const count = counts[pid];
    await a2d.memberData.set(groupId, pid, anwesendId, count.toString());
    await a2d.memberData.set(groupId, pid, prozentId, (count / mt * 100).toFixed(1));
    written++;
}

// Refresh the visible member list so the new values appear immediately
await a2d.ui.refresh();

await a2d.ui.showMessage("app2dat", written + " members updated.");

What you learn here

1. A dialog with memory. The pattern a2d.vars.set(id, await a2d.vars.load(id) || default) before showInput pre-fills the fields with the values of the previous run — after the dialog they are remembered again with vars.save. The user types period and maximum only once.
2. Validate inputs. showInput returns strings — parseInt + an isNaN check prevent division by zero or nonsense in the percentages.
3. The attendance matrix. profilesAttendances returns a session→status dictionary per profile (keys "yyyy-MM-dd HH:mm"); every entry with value "1" is counted. The loop over several groupIds sums across groups — and the try/catch protects against the .NET dictionary behaviour on missing keys.
4. Write back + refresh. Two memberData.set calls per member, then ui.refresh() — the new column values appear in the list immediately.

Practice: certificates as PDF per member

After the belt exam, every successful member should receive their certificate — as a PDF, automatically stored with the member. This example generates one separate PDF per selected member and links it to the member’s document data field “Urkunde” (certificate). It demonstrates the complete a2d.pdf craft: prepare, add a page, place texts with millimetre precision, insert a stamp image, link.

Prerequisites

• Data fields “Urkunde” (type document) and “Kyu” (grade) in the current group.
• A stamp/signature image stored as a file of the group — you enter its complete file link in the script (placeholder in the example).
• Select members in the list, then run.

The script

// Create certificates (for selected members)
// Generates ONE PDF per member and links it to the member's data field "Urkunde".

const groupId = a2d.context.groupId;
const profileId = a2d.context.profileId;
if (!groupId) { await a2d.ui.showMessage("Error", "Please run this script inside a group."); return; }

const selectedMembers = a2d.member.getSelected() || [];
if (selectedMembers.length === 0) {
    await a2d.ui.showMessage("Error", "No members selected");
    return;
}

// === Exam data (pre-filled from persistent variables) ===
a2d.vars.set("pruefer", await a2d.vars.load("pruefer") || "Max Mustermann");
a2d.vars.set("ort", await a2d.vars.load("ort") || "Musterstadt");
a2d.vars.set("dat", await a2d.vars.load("dat") || new Date().toLocaleDateString("de-DE"));

const inputFields = [
    { type: "label", name: "Fields marked with * are mandatory" },
    { type: "label", name: "Important! Set the scaling to 100% when printing!" },
    { type: "string", id: "pruefer", name: "Examiner*", description: "Enter only the chairman of the examination board here" },
    { type: "string", id: "ort", name: "Place*", description: "" },
    { type: "date", id: "dat", name: "Date*", description: "" }
];
const result = await a2d.ui.showInput("Enter exam data", inputFields);
if (!result) return; // Cancelled by user

await a2d.vars.save("pruefer", result["pruefer"]);
await a2d.vars.save("ort", result["ort"]);
await a2d.vars.save("dat", result["dat"]);

const datFormatted = new Date(result["dat"])
    .toLocaleDateString("de-DE", { day: "numeric", month: "long", year: "numeric" })
    .replace(/(\d+)\s/, "$1. ")
    .replace(",", "");
// "6 März, 2026" → "6. März 2026"

const urkId = await a2d.memberData.getFieldId(groupId, "Urkunde");
const kyuId = await a2d.memberData.getFieldId(groupId, "Kyu");
if (!urkId || !kyuId) { await a2d.ui.showMessage("Error", "Data field 'Urkunde' and/or 'Kyu' not found."); return; }

for (const pid of selectedMembers) {
    const memberprofile = await a2d.profile.get(pid);
    if (!memberprofile) continue;
    const data = (await a2d.memberData.get(groupId, pid)) || {};

    await a2d.pdf.prepare(profileId, groupId, "Kyu-Urkunde", "Kyu-Prüfung", 210, 297, "", pid);
    await a2d.pdf.addPage();

    const fullName = (memberprofile.firstName || "") + " " + (memberprofile.secondName || "").toUpperCase();
    await a2d.pdf.addText("big7", fullName, "Arial", 7, true, false, [], 105, 135, true);

    const kyu = data[kyuId] || "?";
    await a2d.pdf.addText("big9", kyu + ". Kyu", "Arial", 9, true, false, [], 105, 172, true);

    await a2d.pdf.addText("smallitalic", result["pruefer"], "Arial", 2.7, true, false, [], 40, 277, true);
    await a2d.pdf.addText("smallbold", result["ort"], "Arial", 2.7, true, false, [], 105, 277, true);
    await a2d.pdf.addText("smallbold", datFormatted, "Arial", 2.7, true, false, [], 105, 281, true);

    // Insert the complete app2dat file link of the stamp image (e.g. copied from a document data field)
    await a2d.pdf.addImage(60, 247, 0.2, "https://api.app2dat.com|0/0/0/2/groups/GROUP_ID/stamp.png¦Stamp_Signature.png");
    await a2d.pdf.CloseAndLinkToMember(urkId);
}

// Refresh the visible member list (linked certificates appear immediately)
await a2d.ui.refresh();

await a2d.ui.showMessage("app2dat", selectedMembers.length.toString() + " certificates created");

What you learn here

1. One PDF per member. The decisive trick is in pdf.prepare(…, pid): the last parameter links the PDF to exactly this member — which is why the whole prepare-→-close cycle sits inside the loop. CloseAndLinkToMember(urkId) stores the finished certificate directly in the member’s document field.
2. Millimetres instead of pixels. All positions are mm on the A4 sheet (210 × 297): addText(…, 105, 135, true) centres the name horizontally at x = 105 mm — the middle of the page. That way the layout fits pre-printed certificate sheets.
3. Embedding field values. The Kyu grade comes from the member’s data field via data[kyuId]; profile data (name) from profile.get. Examiner, place and date are asked in the dialog — again with the vars memory from chapter 11.
4. Images via file links. addImage requires the complete app2dat file link including the display name (after the ¦ character). You get such a link e.g. from a document data field — the sandbox does not accept free-form paths (chapter 8).

Practice: importing new members from CSV

When switching to app2dat, the member list usually already exists — as an Excel or CSV file. This example creates new managed members from it: it opens the native file dialog for the CSV and a mapping file (.map), creates profiles including address and categories, joins the group and fills the data fields — duplicates are skipped.

The map file: assigning columns

The .map file is a simple text file following the pattern TargetField=CSV column, one line per assignment:

Profile.FirstName=FirstName
Profile.SecondName=LastName
Profile.Gender[list:M|male:W|female:D|diverse]=Gender
Profile.DateOfBirth[date]=DOB
Profile.Location.City=City
Profile.Categories=martialarts|karate
Data.Graduierung=Grade

The script

// Import members from CSV (create new profiles)
// Selects a CSV and a MAP file via the native file dialog and creates new members from them —
// like the GUI import "Import CSV". Run this in the members group (main group).

const groupId = a2d.context.groupId;
if (!groupId) { await a2d.ui.showMessage("Import", "Please run this script in the members group."); return; }

// Select CSV file (the file content is returned as text)
const csv = await a2d.ui.pickFile("Select CSV file", ".csv");
if (!csv) return; // Cancelled

// Select MAP file
const map = await a2d.ui.pickFile("Select MAP file", ".map");
if (!map) return; // Cancelled

// Import: creates new members; existing ones (first + last name) are skipped.
const res = await a2d.import.membersFromCSVMap(groupId, csv, map, { separator: ";" });

let msg = res.imported + " new members created";
if (res.skipped > 0) msg += ", " + res.skipped + " skipped (already exist)";
if (res.errors && res.errors.length > 0) msg += ", " + res.errors.length + " errors";

// Refresh the visible member list so the new members appear immediately
await a2d.ui.refresh();

await a2d.ui.showMessage("CSV import", msg);
result.set("message", msg);

What you learn here

1. pickFile returns content, not a path. The return value is the text of the chosen file — it goes straight into membersFromCSVMap. Check for null twice: the user can cancel either dialog.
2. One method, the whole import. membersFromCSVMap handles profile creation, address, categories, group join and data fields in one go — and deduplicates by first + last name. The result object (imported/skipped/errors) becomes the success message.
3. Report the result twice. showMessage informs the user immediately; result.set("message", …) keeps the same summary in the execution report.

The automation assistant

You now know the whole API — but you do not have to memorise it. The automation assistant is an app2dat expert that writes, modifies and explains scripts for you. This chapter shows how to work with it — and the toolkit around it: scopes, folder structure, triggers and version management in the editor.

How the assistant works

You open the assistant in the automation manager via the AI icon — it appears as a chat panel next to the editor. Describe in plain language what should happen:

1. It looks around. The assistant knows your context (level, group, selected members) and inspects things on its own: existing scripts and folders, your groups, their data fields and members — exactly as far as you could, because it works with your permissions.
2. It builds on proven patterns. For typical club tasks it searches the curated example library (the source of the practical examples in chapters 11–13) and adapts the gold template to your field names and groups instead of starting from scratch.
3. It writes and checks. It creates new scripts and modifies existing ones precisely. Before handing over, it checks the code for syntax errors and correct API usage and explains the flow to you. On open questions it asks instead of guessing — you watch its steps live in the panel and can pause it at any time.
4. You stay in control. The assistant never executes scripts itself. Its output appears in the editor as a proposal version (see below) — nothing runs until you decide to.

Scopes: where scripts live

Every script belongs to exactly one of the four levels from chapter 1 — and the assistant, too, always works within the level in which you opened the manager:

The scope decides what a2d.context delivers, where the magic-wand menu offers the script, and how far vars.save reaches. Group scripts are the standard case; profile scripts suit jobs spanning several groups (e.g. creating whole club structures), and event scripts work at folder level — for instance to generate an event’s groups automatically.

Folder structure: order in the script tree

• Folders & subfolders. The tree view on the left organises scripts in folders (one subfolder level). You create new items via the toolbar buttons Folder and Script — or via a folder’s context menu.
• Rename, move, sort. Each entry’s context menu offers rename, delete, move to another folder, and up/down for the order — which also determines the order in the magic-wand menu.
• References: one script, many places. Via Copy reference and Paste reference, an entry in another scope points live at the original — the code is read fresh from the source on every execution and is read-only in the editor (marked “Reference”). This lets you maintain a script centrally and use it in many groups; group templates also roll out their automations as references. Create copy turns the reference into an independent script when needed (the %GPIN% placeholder is replaced with the current template PIN in the process).

Triggers: how scripts are started

In the editor, Triggers opens the script’s trigger settings:

Release settings widen the circle of executors beyond the managers for the menu trigger: Also executable by responsibles (trainers start the script from the attendance list), Also executable by organisation participants (managers of registered clubs in federation groups) and Also executable in shared groups. For shared groups: if the share does not include the edit right, the script runs there read-only — writing a2d calls are rejected.

Versions: adopting changes safely

The editor keeps a version history for every open script. Every state — loaded from the server, edited by you, or proposed by the assistant — becomes its own version:

1. Browse and compare. With more than one version, arrows appear in the toolbar (“2/3”) for stepping back and forth. The diff view highlights lines that changed compared to the previous version — you see at a glance what the assistant touched.
2. Review the proposal. After an assistant run its output appears as a new version — not yet saved. Read the explanation in the chat, check the diff and run it via Execute — this is a real run with real data (if the script uses the member selection, the editor asks for it in a dialog beforehand).
3. Adopt or discard. Save (Ctrl+S) makes the displayed version the valid state — Save all stores several changed scripts at once. To discard, simply step back to the desired version and save that one; closing with unsaved changes prompts you.

Putting it together: your complete toolbox

This closes the circle of the manual: you describe the task to the assistant, it builds on the gold examples and delivers a proposal version that you review in the diff, test and save. Via triggers you make the script available to the right people — from the magic-wand menu through the support assistant to the fully automatic event trigger. And with references and templates you roll the finished automation out to any number of groups, maintained centrally.