@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:

npx @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:

npx @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:

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

Example: Deleting Resources

npx @open-xchange/soap-client delete context --id 123
npx @open-xchange/soap-client delete user --context-id 123 --id 456
npx @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]' })

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.