OX Cloud hands-on provisioning

Simple guide to OX Cloud provisioning with API examples.

General

The API reference for the examples below can be found here: https://documentation.open-xchange.com/components/cloud-api/latest/

The examples are mainly using the tool httpie

Context

How do I provision a new context? (Reference)

When you provision a new context, this will implicitely create a context admin for the new context and it's required to configure a maximum amount of shared filestore quota. This quota will be used for attachments of calendar appointments and contacts, e.g. and will not affect the user's unified quota. If you want to learn more about data managed in this storage, please check Data managed in file storage.

Required parameters

## Context name

$ctxname = "<context_name>" e.g. context1.com

## Quota

$quota = <quota_MB> (-1 = unlimited)

API example

http --auth mybrand:secret POST https://eu.appsuite.cloud/cloudapi/v2/contexts name=$ctxname maxQuota=$quota

How do I allow users in a context to change their password?

This is usually not enabled for users because OX is considering password management to be handled by the partner's provisioning or IDM system. Especially flows like 'forgot password' cannot be covered within the OX Cloud solution yet. The password change offered here is technically only feasible in non-SSO setups and w/o very specific password policies. If the application internal solution turns out not to be sufficient this option must not be given to the users.

Required parameters

## Context object

$context = How do I get a context object for my context?

## Admin credentials

How do I set up admin credentials?

Code snippet

http --auth mybrand:secret PUT https://eu.appsuite.cloud/cloudapi/v2/users/{login} name=$context

{
  "userPermissions": {
    "editPassword": true
  }
}

How do I delete a context?

Required parameters

## Context name

$ctxname = "<context_name>" e.g. testbrand.staging.xion.oxcs.net_context1.com or just context1.com

## Admin credentials

How do I set up admin credentials?

Code snippet

http --auth mybrand:secret DELETE https://eu.appsuite.cloud/cloudapi/v2/contexts/{$ctxname}

How do I provision settings for a context?

Settings can be provisioned when you provision a context or afterwards by calling the change method for a context as described here. On OX Cloud there is only a limited amount of settings available that you can set for your context. You can find a detailed example on how to configure theming here: OX Cloud hands-on theming.

Required parameters

## Context object

$context = How do I get a context object for my context?

## Admin credentials

How do I set up admin credentials?

http --auth mybrand:secret PUT https://eu.appsuite.cloud/cloudapi/v2/contexts/$context

{
  "theme": {
    "mainColor": "#283f73",
    "linkColor": "#283f73",
    "toolbarColor": "#283f73",
    "logoUrlLight": "http://example.com/light.png",
    "logoUrlDark": "http://example.com/dark.png",
    "logoWidth": "60",
    "logoHeight": "auto",
    "topbarBackground": "#283f73",
    "topbarHover": "rgba(0, 0, 0, 0.3)",
    "topbarColor": "#ddd",
    "topbarSelected": "#eee",
    "listSelected": "#aaa",
    "listHover": "#f7f7f7",
    "listSelectedFocus": "#283f73",
    "folderBackground": "#f5f5f5",
    "folderSelected": "rgba(0, 0, 0, 0.1)",
    "folderHover": "rgba(0, 0, 0, 0.05)",
    "folderSelectedFocus": "#283f73",
    "mailDetailCSS": "body { color: #000 !important } h1 { color: red}",
    "serverContact": "My Example Org | <a href=contactPath target=\"_blank\">Contact</a>"
  }
}

How do I get a context object for my context?

While there is an internal context id for every context this ID is not guaranteed to be stable. The SOAP API used in the past sometimes required the context id for certain operations but the new CloudAPI works completely via context names only which stay stable for the whole lifetime. Therefore the API does not expose the ID anymore but most of the time still accepts those IDs if they were used before and are the only known identifiers.

ATTENTION: The IDs might change but we will inform affected customers if that is expected to happen.

User

How do I provision a new user?

Required parameters

## Admin credentials

How do I set up admin credentials?

## Context object

$context = How do I get a context object for my context?

## User object

The JSON snippet below shows all possible properties for the user. The best practice is that the name and mail attributes are identical. Please note that name is what the user has to use for login and that this needs to be unique over the whole enduser base.

The following attributes are mandatory:

name
password
givenName
surName
mail

Some will fall back to a certain default which may not fit your expectations:

classOfService
timezone
quota values (unifiedQuota, mailQuota, fileQuota)

# Mod access definition

$modaccess = cloud_pim | cloud_productivity | cloud_security | cloud_productivity_security

## Class of service

$serviceclass as outlined here: OX Cloud Service classes

Or as adviced to you by OX.

Code snippet

http --auth mybrand:secret POST https://eu.appsuite.cloud/cloudapi/v2/users name=$context

{
  "name": "john@example.com",
  "password": "string",
  "givenName": "John",
  "surName": "Surname",
  "mail": "john@example.com",
  "displayName": "John Doe",
  "classOfService": [
    "cloud_pim"
  ],
  "language": "de_DE",
  "aliases": [
    "alias1@example.com",
    "alias2@example.com"
  ],
  "timezone": "Europe/Berlin",
  "spamLevel": "string",
  "unifiedQuota": 1000,
  "mailQuota": 1000,
  "fileQuota": 1000,
  "userImage": {
    "image": "SGVsbG8gV29ybGQ=",
    "type": "jpeg"
  },
  "userPermissions": {
    "send": true,
    "receive": false,
    "maillogin": true,
    "weblogin": false,
    "editPassword": true
  },
  "userAdminEnabled": true,
  "emailBackupEnabled": true
}

How do I change user permissions?

Required parameters

## Admin credentials

How do I set up admin credentials?

## Context

$context = How do I find my context?

Code snippet

http --auth mybrand:secret PUT https://eu.appsuite.cloud/cloudapi/v2/users/{login}/permissions name=$context{
    "send": true,
    "receive": false,
    "maillogin": true,
    "weblogin": false,
    "editPassword": true
}

How do I delete a user?

Before permanently deleting a user you may want to consider to just disable some or all of his permissions. This would not delete the user's data and so the user could be reactivated without data loss afterwards.

Required parameters

## Context object

$context = How do I get a context object for my context?

## User

$user = Object containing the user's login (<user_login>)

## Admin credentials

How do I set up admin credentials?

Code snippet

http --auth mybrand:secret DELETE https://eu.appsuite.cloud/cloudapi/v2/users/{login}

Own Brand configuration

Retrieve own brand configuration

The following example shows how to retrieve the current data.

http --auth mybrand:secret GET https://eu.appsuite.cloud/cloudapi/v2/brand/theme

{
  "mainColor": "#283f73",
  "linkColor": "#283f73",
  "toolbarColor": "#283f73",
  "logoUrlLight": "http://example.com/light.png",
  "logoUrlDark": "http://example.com/dark.png",
  "logoWidth": "60",
  "logoHeight": "auto",
  "topbarBackground": "#283f73",
  "topbarHover": "rgba(0, 0, 0, 0.3)",
  "topbarColor": "#ddd",
  "topbarSelected": "#eee",
  "listSelected": "#aaa",
  "listHover": "#f7f7f7",
  "listSelectedFocus": "#283f73",
  "folderBackground": "#f5f5f5",
  "folderSelected": "rgba(0, 0, 0, 0.1)",
  "folderHover": "rgba(0, 0, 0, 0.05)",
  "folderSelectedFocus": "#283f73",
  "mailDetailCSS": "body { color: #000 !important } h1 { color: red}",
  "serverContact": "My Example Org | <a href=contactPath target=\"_blank\">Contact</a>"
}

Change own brand configuration

See the example below on how to change settings from your own brand:

http --auth mybrand:secret POST https://eu.appsuite.cloud/cloudapi/v2/brand/theme

{
  "mainColor": "#283f73",
  "linkColor": "#283f73",
  "toolbarColor": "#283f73",
  "logoUrlLight": "http://example.com/light.png",
  "logoUrlDark": "http://example.com/dark.png",
  "logoWidth": "60",
  "logoHeight": "auto",
  "topbarBackground": "#283f73",
  "topbarHover": "rgba(0, 0, 0, 0.3)",
  "topbarColor": "#ddd",
  "topbarSelected": "#eee",
  "listSelected": "#aaa",
  "listHover": "#f7f7f7",
  "listSelectedFocus": "#283f73",
  "folderBackground": "#f5f5f5",
  "folderSelected": "rgba(0, 0, 0, 0.1)",
  "folderHover": "rgba(0, 0, 0, 0.05)",
  "folderSelectedFocus": "#283f73",
  "mailDetailCSS": "body { color: #000 !important } h1 { color: red}",
  "serverContact": "My Example Org | <a href=contactPath target=\"_blank\">Contact</a>"
}

Page tree

OX Cloud hands-on provisioning

General

Context

How do I provision a new context? (Reference)

Required parameters

API example

How do I allow users in a context to change their password?

Required parameters

Code snippet

How do I delete a context?

Required parameters

Code snippet

How do I provision settings for a context?

Required parameters

How do I get a context object for my context?

User

How do I provision a new user?

Required parameters

Code snippet

How do I change user permissions?

Required parameters

Code snippet

How do I delete a user?

Required parameters

Code snippet

Own Brand configuration

Retrieve own brand configuration

Change own brand configuration