@open-xchange/soap-client

This project provides an API facade for the OX App Suite Middleware SOAP API, making it easy to interact with provisioning endpoints such as contexts, users, secondary accounts, and more.

Features

• API Facade: Programmatically access and manage OX App Suite resources via a simple JavaScript API.
• Provisioning Script: Easily create, update, and delete contexts, users, and secondary accounts from the command line.
• Configurable: Uses .env files for environment-specific configuration.

Usage

CLI Provisioning

You can use the built-in provisioning script to automate resource creation. Simply run:

pnpm dlx @open-xchange/soap-client

If you already have installed the package in your project, you can run the script directly:

pnpm provision.js

This will execute the provisioning tool, which reads configuration from a JSON file (default: ./provisioning.json). You can specify a different file with the -f option:

pnpm dlx @open-xchange/soap-client -f example-provisioning.json

The JSON file should contain the resources to provision. For example:

{
  "contexts": [
    {
      "data": {
        "name": "test",
        "capabilities": "foo,bar",
        "config": {
          "entries": [{
            "key": "config",
            "value": {
              "entries": [
                { "key": "io.ox/core//foobar", "value": "false" }
              ]
            }
          }]
        }
      },
      "users": [
        {
          "name": "testuser",
          "primaryEmail": "[email protected]",
          "display_name": "Test User",
          "imapLogin": "testuser-123",
          "imapServer": "main-dovecot",
          "smtpServer": "main-postfix",
          "email1": "[email protected]",
          "password": "supersecret",
          "sur_name": "User",
          "given_name": "Test"
        }
      ],
      "secondaryAccount":
        {
          "name": "info",
          "login": "[email protected]",
          "primaryAddress": "[email protected]",
          "mailEndpointSource": "primary",
          "transportEndpointSource": "primary",
          "personal": "Info"
        }
    }
  ]
}

Example: Creating Resources

The CLI supports creating contexts, users, and secondary accounts:

pnpm dlx @open-xchange/soap-client create context --name my-context
pnpm dlx @open-xchange/soap-client create user --context-id 123 --email [email protected] --name myuser
pnpm dlx @open-xchange/soap-client create account --context-id 123 --name info --email [email protected] --users 1,2,3

Example: Deleting Resources

pnpm dlx @open-xchange/soap-client delete context --id 123
pnpm dlx @open-xchange/soap-client delete user --context-id 123 --id 456
pnpm dlx @open-xchange/soap-client delete account --context-id 123 --email [email protected] --users 1,2,3

API Usage

You can also use the API programmatically in your Node.js projects and choose between either the common or the reseller API when doing so by importing the respective service:

import { contextService, userService } from '@open-xchange/soap-client/common'

const context = await contextService.create({ name: 'my-context' })
const user = await userService.create(context, { name: 'myuser', email1: '[email protected]' })

Embedding: one client per endpoint

The module exports above bind to PROVISIONING_URL/E2E_ADMIN_USER/E2E_ADMIN_PW on first use — right for the CLI and test runs, wrong for a long-running process that talks to many middlewares. For that, build clients explicitly:

import { createProvisioningClient } from '@open-xchange/soap-client/client'

const client = createProvisioningClient({
  url: 'http://core-mw-admin.appsuite-main.svc',
  auth: { login: 'oxadminmaster', password: secret },
  mxDomain: 'box.ox.io' // optional, for generated context-admin addresses
})
await client.contextService.list('defaultcontext')

Factory clients install no process-global handlers and each carries its own endpoint, credentials and retry/fault handling. They read the environment in exactly two places: MX_DOMAIN as the fallback when mxDomain is omitted, and DEBUG_SOAP for timing output. Pass mxDomain explicitly if an ambient MX_DOMAIN must not leak into generated context-admin addresses.

Configuration

Set up your .env file with the required environment variables. See .env.default for an example.

For more details, see the bin/provision.js script and the services directory.