Simple guide to OX Cloud provisioning with code snippets (first Perl, Java can be added later).
For all examples on this page the provisioning needs admin credentials to be set up.
## Admin name (Sub admin)
$oxaasadmname = "<brand>.<environment>.xion.oxcs.net" e.g: testbrand.staging.xion.oxcs.net
## Admin password
$oxaasadmpw = <sub_admin_password_plain>
my $oxaascreds = SOAP::Data->type("Credentials")->value( \SOAP::Data->value( SOAP::Data->name( "login" => "$oxaasadmname" ), SOAP::Data->name( "password" => "$oxaasadmpw" ) ) ); |
To be able to use the webservices, you may need to set up the service definitions.
my $OXResellerContextService = SOAP::Lite->ns("http://soap.reseller.admin.openexchange.com") ->proxy( "https://$oxaashost" . "/webservices/OXResellerContextService", ssl_opts => [ SSL_verify_mode => 1 ] ); my $OXResellerUserService = SOAP::Lite->ns("http://soap.reseller.admin.openexchange.com") ->proxy( "https://$oxaashost" . "/webservices/OXResellerUserService", ssl_opts => [ SSL_verify_mode => 1 ] ); my $OXaaSService = SOAP::Lite->ns("http://soap.oxaas.admin.openexchange.com/") ->proxy( "https://$oxaashost" . "/webservices/OXaaSService", ssl_opts => [ SSL_verify_mode => 1 ] ); |
When you provision a new context, you will always have to specify a context admin for the new context as well as a maximum amount of quota that will be shared among the users of your context. 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.
## Context name
$ctxname = "<context_name>" e.g. testbrand.staging.xion.oxcs.net_context1.com
## Admin credentials
How do I set up admin credentials?
## Quota
$quota = <quota_MB> (-1 = unlimited)
## Admin user
User object with at least the following properties:
my $context = SOAP::Data->type("Context")->value( \SOAP::Data->value( SOAP::Data->name( "name" => $ctxname ), SOAP::Data->name( "maxQuota" => $quota ), SOAP::Data->name( "userAttributes" => \SOAP::Data->value( SOAP::Data->name( "entries" => @uattrs ) ) ) ) ); my $result = $OXResellerContextService->create( $context, SOAP::Data->value("User")->value( \SOAP::Data->value( SOAP::Data->name( "name" => "<admname>" ), SOAP::Data->name( "password" => "<admpass>" ), SOAP::Data->name( "display_name" => "<adm_display_name>" ), SOAP::Data->name( "sur_name" => "<adm_sur_name>"), SOAP::Data->name( "given_name" => "<adm_given_name>" ), SOAP::Data->name( "primaryEmail" => "<adm_primaryEmail>" ), SOAP::Data->name( "email1" => "<adm_email>" ) ) ), $oxaascreds ); |
## Context object
$context = How do I get a context object for my context?
## Mod access definition
$modaccess = cloud_pim | cloud_productivity | cloud_security | cloud_productivity_security
## Admin credentials
How do I set up admin credentials?
## This part is necessary if you are switching to or from a Module Access Combination ## that offers security features (cloud_security and cloud_productivity_security) my $security_features = SOAP::Data->name( "entries" => \SOAP::Data->value( SOAP::Data->name( "key" => "com.openexchange.capability.guard-mail" ), SOAP::Data->name( "value" => "true" ) ), "entries" => \SOAP::Data->value( SOAP::Data->name( "key" => "com.openexchange.capability.guard-drive" ), SOAP::Data->name( "value" => "false" ) ) ); my $context = SOAP::Data->type("Context")->value( \SOAP::Data->value( SOAP::Data->name("id" => $cid), ## Add this if you are switching to or from a Module Access Combination that offers security features SOAP::Data->name("userAttributes" => \SOAP::Data->value( SOAP::Data->name( "entries" => \SOAP::Data->value( SOAP::Data->name( "key" => "config" ), SOAP::Data->name( "value" => \SOAP::Data->value($security_features)) ) ) ) ) ) ); my $result = $OXResellerContextService->changeModuleAccessByName( $context, $modaccess, $oxaascreds ); if ( $result->fault() ) { print STDERR "Error: ".$result->faultstring()."\n"; next; } ## You will have to execute this call only if you're switching to or from a Module Access Combination that offers security features my $result = $OXResellerContextService->change( $context, $oxaascreds ); if ( $result->fault() ) { print STDERR "Error: ".$result->faultstring()."\n"; next; } |
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. 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.
## Context object
$context = How do I get a context object for my context?
## Admin credentials
How do I set up admin credentials?
## Retrieve current module access for the context my $modaccess = $OXResellerContextService->getModuleAccess( $context, $oxaascreds ); my $modaccessperms = $modaccess->paramsall; ## Change editPassword permission $modaccessperms->{'editPassword'} = "true | false"; ## Create soap structure my @newModuleAccess; foreach my $key (keys %$modaccessperms) { push @newModuleAccess, SOAP::Data->name( $key => $modaccessperms->{$key} )->type('boolean'); } ## Provision new module access for the context my $result = $OXResellerContextService->changeModuleAccess( $context, SOAP::Data->type("UserModuleAccess")->value( \SOAP::Data->value(@newModuleAccess) ), $oxaascreds ); |
## Context name
$ctxname = "<context_name>" e.g. testbrand.staging.xion.oxcs.net_context1.com
## Admin credentials
How do I set up admin credentials?
my $context = SOAP::Data->type("Context")->value( \SOAP::Data->value( SOAP::Data->name( "name" => $ctxname ), ) ); my $result = $OXResellerContextService->delete( $context, $oxaascreds ); |
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.
## Context object
$context = How do I get a context object for my context?
## Admin credentials
How do I set up admin credentials?
my %config = ( <settings_name> => <settings_value> ); my @attrs; push @attrs, \SOAP::Data->value( SOAP::Data->name("key" => "config"), SOAP::Data->name("value" => \SOAP::Data->value( map { SOAP::Data->name("entries" => \SOAP::Data->value( SOAP::Data->name("key" => $_), SOAP::Data->name("value" => $config{$_}) )) } keys %config )) ); my $context = SOAP::Data->type("Context")->value( \SOAP::Data->value( SOAP::Data->name("id" => $cid), SOAP::Data->name( "userAttributes" => \SOAP::Data->value( SOAP::Data->name( "entries" => @attrs ) ) ) ) ); my $result = $OXResellerContextService->change($context, $oxaascreds); |
## Context name
$ctxname = "<context_name>" e.g. testbrand.staging.xion.oxcs.net_context1.com
## Admin credentials
How do I set up admin credentials?
# get context id my $context = $OXResellerContextService->list( $ctxname, $oxaascreds ); if ( $result->fault() ) { print STDERR "Error geting context id with name $ctxname: ".$context->faultstring()."\n"; next; } my @context = $context->paramsall; my $cid = $context[0]->{'id'}; |
For most provisioning calls you will need a context object for the request.
## Context ID
$cid = How do I find my context id?
my $context = SOAP::Data->type("Context")->value( \SOAP::Data->value( SOAP::Data->name( "id" => $cid ) ) ); |
## Admin credentials
How do I set up admin credentials?
## Context object
$context = How do I get a context object for my context?
## User object
User object with at least the following properties. Those are mandatory but not in every case reported as such if missing. Please be careful.
# Mod access definition
$modaccess = cloud_pim | cloud_productivity | cloud_security | cloud_productivity_security
## Service Class
$serviceclass = Has to match $modaccess unless adviced differently
my @soapdata; push @soapdata, SOAP::Data->name( "name" => <username> )->type('string'); push @soapdata, SOAP::Data->name( "password" => <password> ); push @soapdata, SOAP::Data->name( "display_name" => <displayname> )->type('string'); push @soapdata, SOAP::Data->name( "sur_name" => <surname> )->type('string'); push @soapdata, SOAP::Data->name( "given_name" => <givenname> )->type('string'); push @soapdata, SOAP::Data->name( "primaryEmail" => <email> ); push @soapdata, SOAP::Data->name( "email1" => <email> ); push @soapdata, SOAP::Data->name( "language" => <language> ); push @soapdata, SOAP::Data->name( "timezone" => <timezone> ); push @soapdata, SOAP::Data->name( "maxQuota" => <maxquota> ); my $qunified = SOAP::Data->name( "entries" => \SOAP::Data->value( SOAP::Data->name( "key" => "com.openexchange.unifiedquota.enabled" ), SOAP::Data->name( "value" => "true" ) ) ); my @classofservice; push @classofservice, \SOAP::Data->value( SOAP::Data->name("key" => "cloud"), SOAP::Data->name("value" => \SOAP::Data->value( SOAP::Data->name("entries" => \SOAP::Data->value( SOAP::Data->name("key" => "service"), SOAP::Data->name("value" => $serviceclass) )) )) ); push @soapdata, SOAP::Data->name( "userAttributes" => \SOAP::Data->value( SOAP::Data->name( "entries" => \SOAP::Data->value( SOAP::Data->name( "key" => "config" ), SOAP::Data->name( "value" => \SOAP::Data->value($qunified)) ), @classofservice ) ) ); my $user = SOAP::Data->value("User")->value( \SOAP::Data->value(@soapdata) ); my $result = $OXResellerUserService->createByModuleAccessName( $context, $user, $modaccess, $oxaascreds ); if( $result->fault() ) { print $cid; print $result->faultstring()."\n"; exit(1); } my @results = $result->paramsall; # set email quota for the new user or, if unified quota is enabled, activate # unified quota valid for mail and filestorage $result = $OXaaSService->setMailQuota( SOAP::Data->name( "ctxid" => $cid ), SOAP::Data->name( "usrid" => $results[0]->{'id'} ), SOAP::Data->name( "quota" => $maxQuota ), $oxaascreds ); |
## Admin credentials
How do I set up admin credentials?
## Context object
$context = How do I get a context object for my context?
## Mod access definition
$modaccess = cloud_pim | cloud_productivity | cloud_security | cloud_productivity_security
## Service Class
$serviceclass = Has to match $modaccess
## User
$user = Object containing the user's login (<user_login>)
my @soapdata; push @soapdata, SOAP::Data->name( "name" => <user_login> )->type('string'); my @classofservice; push @classofservice, \SOAP::Data->value( SOAP::Data->name("key" => "cloud"), SOAP::Data->name("value" => \SOAP::Data->value( SOAP::Data->name("entries" => \SOAP::Data->value( SOAP::Data->name("key" => "service"), SOAP::Data->name("value" => $serviceclass) )) )) ); push @soapdata, SOAP::Data->name( "userAttributes" => \SOAP::Data->value( SOAP::Data->name( "entries" => @classofservice ) ) ); my $user = SOAP::Data->value("User")->value( \SOAP::Data->value( SOAP::Data->value(@soapdata) ) ); my $result = $OXResellerUserService->changeByModuleAccessName( $context, $user, $modaccess, $oxaascreds ); if ( $result->fault() ) { print STDERR "Error: ".$result->faultstring()."\n"; next; } ## You will have to execute this call only if you're switching to or from a Module Access Combination that offers security features my $result = $OXResellerUserService->change( $context, $user, $oxaascreds ); if ( $result->fault() ) { print STDERR "Error: ".$result->faultstring()."\n"; next; } |
## Admin credentials
How do I set up admin credentials?
## Context id
$cid = How do I find my context id?
## User id
$uid = How do I get my user id?
## Permissions to enable
@disablePerms = array of permissions that should be enabled
my @enablePerms; push(@enablePerms, SOAP::Data->name( perms => "SEND" )); push(@enablePerms, SOAP::Data->name( perms => "RECEIVE" )); push(@enablePerms, SOAP::Data->name( perms => "MAILLOGIN" )); push(@enablePerms, SOAP::Data->name( perms => "WEBLOGIN" )); my $result = $OXaaSService->enablePermissions( SOAP::Data->name( "ctxid" => $cid ), SOAP::Data->name( "usrid" => $uid ), SOAP::Data->name( "perms" => @enablePerms ), $oxaascreds ); |
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 it could be reactivated without data loss afterwards.
## Admin credentials
How do I set up admin credentials?
## Context id
$cid = How do I find my context id?
## User id
$uid = How do I get my user id?
## Permissions to disable
@disablePerms = array of permissions that should be disabled
my @disablePerms; push(@disablePerms, SOAP::Data->name( perms => "SEND" )); push(@disablePerms, SOAP::Data->name( perms => "RECEIVE" )); push(@disablePerms, SOAP::Data->name( perms => "MAILLOGIN" )); push(@disablePerms, SOAP::Data->name( perms => "WEBLOGIN" )); my $result = $OXaaSService->disablePermissions( SOAP::Data->name( "ctxid" => $cid ), SOAP::Data->name( "usrid" => $uid ), SOAP::Data->name( "perms" => @disablePerms ), $oxaascreds ); |
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.
## 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?
my $user = SOAP::Data->value("User")->value( \SOAP::Data->value( SOAP::Data->name( "name" => <user_login> ) ) ); my $result = $OXResellerUserService->delete( $context, $user, $oxaascreds ); |
## 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?
my %config = ( <settings_name> => <settings_value> ); my @attrs; push @attrs, \SOAP::Data->value( SOAP::Data->name("key" => "config"), SOAP::Data->name("value" => \SOAP::Data->value( map { SOAP::Data->name("entries" => \SOAP::Data->value( SOAP::Data->name("key" => $_), SOAP::Data->name("value" => $config{$_}) )) } keys %config )) ); my $user = SOAP::Data->value("User")->value( \SOAP::Data->value( SOAP::Data->name("name" => <user_login>), SOAP::Data->name( "userAttributes" => \SOAP::Data->value( SOAP::Data->name( "entries" => @attrs ) ) ) ) ); my $result = $OXResellerUserService->change( $context, $user, $oxaascreds ); |
## Context object
$context = How do I get a context object for my context?
## User
$user = Object containing the user's login (<user_login>) and the new password (<user_password>)
## Admin credentials
How do I set up admin credentials?
my $user = SOAP::Data->value("User")->value( \SOAP::Data->value( SOAP::Data->name( "name" => <user_login> ); SOAP::Data->name( "password" => <user_password> ) ) ); my $result = $OXResellerUserService->change( $context, $user, $oxaascreds ); |
## 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?
my $user = $OXResellerUserService->getData( $context, SOAP::Data->value("User")->value( \SOAP::Data->value( SOAP::Data->name( "name" => <user_login> ) ) ), $oxaascreds ); my @user = $user->paramsall; my $uid = $user[0]->{'id'}; |
Beginning with version 7.10.5, it is possible to define some settings that used to be applied to every context before also into the own brand. You can now define all so called Configuration Cascade settings or userAttributes
globally in your own brand entry.
The following example shows how to retrieve that data using the new SOAP API call getSelfData
:
#!/usr/bin/perl -w BEGIN { $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0 } use strict; use SOAP::Lite; use Data::Dumper; my $soap = SOAP::Lite->ns("http://soap.reseller.admin.openexchange.com")->proxy("https://$oxaashost/webservices/OXResellerService", ssl_opts => [ SSL_verify_mode => 0 ]); my $oxaasadmname = "example.com"; my $oxaasadmpw = "secret"; my $creds = SOAP::Data->type("Credentials")->value( \SOAP::Data->value( SOAP::Data->name("login" => $oxaasadmname), SOAP::Data->name("password" => $oxaasadmpw))); my $ret = $soap->getSelfData($adminName, $adminId, $creds); if( $ret->fault() ) { print $ret->faultstring()."\n"; } else { print Dumper($ret->paramsall); } |
See the example below on how to add or remove settings from your own brand using the new SOAP API method changeSelf
:
There's currently one caveat, that you have to know the Id of your own brand, but that cannot yet programmatically retrieved, so you have to ask us for it. |
#!/usr/bin/perl -w BEGIN { $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0 } use strict; use SOAP::Lite; use Data::Dumper; my $soap = SOAP::Lite->ns("http://soap.reseller.admin.openexchange.com")->proxy("https://$oxaashost/webservices/OXResellerService", ssl_opts => [ SSL_verify_mode => 0 ]); my $oxaasadmname = "example.com"; my $oxaasadmpw = "secret"; my $oxaasadmid = "83"; my $configName = "com.openexchange.appsuite.servercontact"; my $configValue = "This server is operated by me"; my $add = 1; my $creds = SOAP::Data->type("Credentials")->value( \SOAP::Data->value( SOAP::Data->name("login" => $oxaasadmname), SOAP::Data->name("password" => $oxaasadmpw))); my $config = SOAP::Data->name("entries" => \SOAP::Data->value( SOAP::Data->name( "key" => $configName ), SOAP::Data->name( "value" => $configValue))); my $resellerAdm; if ($add) { $resellerAdm = SOAP::Data->type("ResellerAdmin")->value( \SOAP::Data->value( SOAP::Data->name("name" => $oxaasadmname), SOAP::Data->name("id" => $oxaasadmid), SOAP::Data->name("configurationToAdd" => \SOAP::Data->value($config)) )); } else { $resellerAdm = SOAP::Data->type("ResellerAdmin")->value( \SOAP::Data->value( SOAP::Data->name("name" => $oxaasadmname), SOAP::Data->name("id" => $oxaasadmid), SOAP::Data->name("configurationToRemove" => $configName) )); } my $ret = $soap->changeSelf($resellerAdm, $creds); if( $ret->fault() ) { print $ret->faultstring()."\n"; } else { print Dumper($ret->paramsall); } |