Guides for using iMothership at work

Script API reference

Use these JavaScript helpers inside Work API files and code integrations to query collections, connect to external MongoDB databases, and work with imported files.

These are calls on the injected api object. For HTTP endpoints, authentication, request bodies, and responses, see the public HTTP API documentation.

Calling the API

Your script receives body as its input. Use await for database operations and return for the result; no Express req or res is needed. Call toArray() to execute a find or aggregation cursor.

const accounts = api.collection('accounts');
return await accounts.find({ active: true })
    .sort({ name: 1 }).limit(50).toArray();

Connect to external MongoDB

Use api.mongoDb.connect(uri, dbName) with a mongodb:// or mongodb+srv:// URI. If you omit the database name, the MongoDB driver uses the database from the URI, or its default database. The connection is separate from Mothership’s own collections.

The example uses project tags for the URI and database name. Each tag must resolve to a valid JavaScript string expression. Keep credentials in your project configuration, and do not return them from the script.

const external = await api.mongoDb.connect(
    {{ mongodb_uri }},
    {{ db_name }}
);
try {
    const accounts = external.collection('accounts');
    const pipeline = [
        { $match: { AccountType: body.type } },
        { $lookup: {
            from: 'countries',
            localField: 'Address3',
            foreignField: '_id',
            as: 'Address3'
        } },
        { $unwind: { path: '$Address3', preserveNullAndEmptyArrays: true } }
    ];
    return await accounts.aggregate(pipeline, { allowDiskUse: true }).toArray();
} finally {
    await external.close();
}

The lookup above assumes matching field types. If your IDs use different types, retain your existing $lookup pipeline with $convert. You can keep an existing pipeline and change only the connection and collection calls.

external.db.collection(name) is an alias for external.collection(name). Use try/finally to close the connection. Automatic cleanup also runs after success or failure. Connections and handles are valid only for the current execution.

In secure mode, MongoDB operations run through the server while your script remains in its sandbox. The database must accept connections from the server network. Host-file TLS options and host-identity authentication are unavailable; use credentials supplied in the URI. The older mongoExternal.connect helper remains non-secure only.

Read-only report execution also supports api.mongoDb.connect for reads. Write methods and write aggregation stages remain unavailable in reports.

Mailbox counts

Use await api.mail.count(options) to count messages in an authorised Microsoft mailbox. Available in secure and non-secure execution for task integrations and Work API scripts with an organisation and project context.

const count = await api.mail.count({
    email: 'mailbox@example.com',
    folder: 'Inbox/Orders'
});

return { count }; // e.g. { count: 42 }

Returns a number, including 0 for an empty folder. Counts both read and unread messages directly in that folder; messages in child folders are excluded. This call does not download message bodies, mark messages as read, move messages, or create folders.

Missing folders, unauthorised mailboxes, expired or revoked permissions, and provider failures throw an error rather than returning zero. Existing saved Microsoft authorisation is reused and refreshed on the server; tokens are not returned to your code. Gmail and access to other shared mailboxes through a delegate's account are not supported by this helper.

Collection operations

Use these methods on api.collection(name) or external.collection(name). Unless shown with a cursor, call them with await. Mothership collections remain subject to their approved collection rules; external collections use the permissions of the supplied database account.

For find cursors, sort(spec), limit(count), skip(count), and project(fields) configure the query. Secure-mode cursors expose this documented subset of the MongoDB driver; they do not expose a raw MongoClient.

Imported files — secure mode

These helpers are available in secure execution when the job supplies imported file paths in gcsFilePaths. Reads are restricted to those files; uploads must stay alongside an imported file. Size and row limits apply.

const rows = await api.files.parseImportedCsv(gcsFilePaths[0], {
    separator: '|',
    maxRows: 500000,
    maxBytes: 25 * 1024 * 1024,
    encoding: 'win1252' // Optional; defaults to 'utf8'
});
return { count: rows.length, rows };

For CSV files, the optional encoding selects how the original file bytes are decoded before parsing, including column headers. Supported values are utf8 / utf-8 (default), win1252 / windows-1252 / cp1252, and latin1 / iso-8859-1. Names are case-insensitive. Unsupported values throw an error.

Choose the encoding used by the source file; it is not detected automatically. Windows-1252 and Latin-1 differ for characters such as the euro symbol and curly quotes. Existing calls without encoding continue to use UTF-8.