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.

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]);
return { count: rows.length, rows };