Search

Page tree
Skip to end of metadata
Go to start of metadata

Table of Contents



Introduction


Overview

interworks.cloud Platform provides a unified system to automate day-to-day management and enablement of cloud services addressing all critical operational challenges for provisioning, monitoring, metering, self-management, authentication and further integration into other applications in the provider’s systems. Integration of interworks.cloud Platform with any provisioning platform gives Service Providers the ability not only to setup and manage the services offered to their customers but to develop a unified system for product definition, billing customer subscriptions and accept payments. Service Management API enables integration of new services via implementation of a fixed set of API endpoints that support subscription and access management performed by the central platform. Any integration of the interworks.cloud Platform with provisioning platform follows certain principles and provides certain attributes.

Requirements

The following requirements should be met for the integration process of an application with interworks.cloud Platform:

  • interworks.cloud Platform Business edition account or On-Premise installation
  • Support Software as a service (Saas) licensing and delivery model
  • Development of a RESTful API, coded in the language of your choice, implementing the required functionality that is necessary for translating interworks.cloud action to provisioning actions for the new application.
  • Optional support for OpenID authentication

Technical Features

interworks.cloud Service Management API features a RESTful architecture, allowing you to code in the language of your choice.

Integration service is a RESTful API that should deliver a fixed set of methods supporting

  • Service configuration,
  • Access management,
  • Subscription management
  • Users management
  • User Services management

In general, the following details and options are available for the integration service:

  • JSON format is user for data on all requests and responses.
  • All requests encoded using the UTF-8 character set.
  • Access over HTTPS is optional, but important to prevent security vulnerabilities.
  • Integration service’s authorization is handled via API keys, while SSL certificates are necessary for secure communication between interworks.cloud and Service Provider.
  • Authentication process is optional and should be managed by integration service cooperating Service Management API methods that manage authentication info.
  • There are no limitations regarding hosting of integration service.
  • Billing operations are automatically performed by interworks.cloud Platform without any further integration.
  • Cloud BSS API can be used in order to support the information necessary for the integration of new services. 

Getting Started


Integrating your application with interworks.cloud Platform, include the following steps:

  • Get familiar with Provisioning engine
  • Register new Application
  • Getting API Key
  • Develop and host a RestFul API validating Application ID / API Key info
  • For each Endpoint:
    • Implement method in RestFul API
    • Provide URL
    • Make test request
  • Configure Settings (Authentication Info)
  • Get Service Definition
  • Create Products

Provisioning Engine


interworks.cloud Platform manages activation/deactivation of services and resources by orchestrating simple configuration for administration of services and customers info provided through BSS and Storefront modules.

Provisioning of services is triggered automatically by interworks.cloud Platform when one of the following actions is performed:

  • Subscription Creation
  • Subscription Activation
  • Subscription Deactivation
  • Subscription Cancellation
  • Subscription Deletion
  • Add-on Creation
  • Add-on Update
  • Add-on Cancellation

Provisioning engine is also responsible for provisioning of customers/users when one of the following actions is performed:

  • Account Synchronization
  • Account Deletion

Moreover, interworks.cloud Platform Storefront provides a powerful feature in "My Workspace" page that enables management of the Users and the Services assigned to them.

In order to successfully apply the above actions, provisioning engine should be configured with administrative info in order to properly call each external application for delivering a service to an end customer. In general this info provides the answers to the following questions:

  • What urls should be called for each action?
  • What authentication info is required by the external application?
  • What kind of services supported?
  • What quotas are supported for each service?
  • What information is required for synchronizing an account?

Applications Setup

Activation of an application is available through Cloud BSS > Setup > Administration > System Options > Applications Setup

The list of supported external systems is available as displayed in the following screen and configuration of each system is available by choosing ‘Settings’ button for the preferable provisioning system.

At this point, provisioning engine asked integration service of the external application about the fields that should be displayed in order to collect authentication details. In the following screen, integration service answered that except ‘System Name’ that is common for all applications; authentication required also API Url, ‘Username’, ‘Password’ and 'External Site ID' fields. 

The above form is completed by the administrator user of BSS Organization and saved as configuration info for the new instance of the external application. These info will be available latter for all calls necessary to external application’s integration service.

Get Services Definition

When the application has been activated, Cloud Platform calls integration service for external system in order to get the definition for the supported services. This is achieved by executing the action “Get Services Definition” found in activation page. These definitions are kept as product types in interworks.cloud Platform and are available at BSS > Setup > Billing > Products > Product Types

Except from product types, this call provide also the measurable characteristics of each service and the flavors supported for each service. This info is kept as product type variation in interworks.cloud Platform.

Product Definitions

The selection of product’s product type is the info that instructs provisioning engine witch service to provision and from witch external system should the services set available to customer.

Product variations (along with order variations) define the resources for service provisioning (e.g. for VMs the number of CPU Cores)

Provisioning of services is performed only for products with ‘Recurring charge – prepaid’ or ‘Recurring charge – Pay-per-use (PPU)’ when a new subscription is created.

Account Synchronization

When a new account is created in Cloud BSS, it can be synced with one or more external systems by setting his Synchronization Options.

By executing the action “Save & Synchronize”, provisioning engine calls external application for create of a customer/user and keeps the response ids for use in next steps.

Service Provisioning

The main object describing a service for a user/customer is Subscription. Subscription has all the info regarding the type of service available to user/customer and the configuration selected during product administration or user configuration.

Whenever a subscription created or changes, integration service of the corresponding external application is called in order to provision the changes of resources made through interworks.cloud Platform BSS.

Users and User Services Management

Whenever a customer buys a subscription, a set of resources become available to him and management of these resources is required in order to be set available for end users of his organization. 

interworks.cloud Platform keeps no info regarding end users of a service. But, interworks.cloud Platform Storefront provides "My Workspace" page were a customer can manage the available resources and distribute them to the end users of his organization.

Creation of new user, update of an existing user and status updates are available through a powerful UI. Moreover, distribution of services across the end users of an organization is available by the same UI simplifying the administration tasks necessary for delivering a service to an end user.

Register new Application


In order to start with integration of a new external provisioning system via Service Management API, a new application should be registered in order to be listed with the rest application in list. The action ‘Register new Application’ is available at Cloud BSS > Setup > Administration > System Options > Applications Setup

Application’s Name and a description are the only information required in order to create a new application.

By selecting ‘Save’, a new application is created and listed with other available applications, as shown below.

By selecting  button, the new application can be managed and configured.

Getting Application ID/ API Key


Application Id/ API Key values provide the necessary info that can be used to authorize the calls made to integration service.

Application Id / API Key provided as headers to every request and are unique for each application.

Validation of these values by integration service should be implemented in order to prevent calls made by unknown sources.

The combination Application Id / API Key is automatically generated when application is registered. The generated keys are available in as shown below.

Important

Please keep the API key "private" and do not distribute or use the API key for creating multiple services.

Generation of new API Key can made using the action.

 

RestFul API Development


Service Management API requires development of a RestFul API that will act as integration service and will be called in order to apply several provisioning actions to the external application.

There are no requirements or limitations regarding the language, the technology or the hosting environment of the RestFul API, as long as the required methods are functioning properly.

Cloud BSS API is also available for support of end points development providing any extra info required in order to complete the scope of each end point for the external system.

HTTP Standards

All actions taken through the API are done via HTTP using standard HTTP methods: GET (to retrieve an object), POST (to create), PUT (to modify), and DELETE. Standard HTTP Response codes are used to indicate success and error conditions.

Authorization

The integration service should validate all calls received using the Application Id / API Key combination provided by interworks.cloud when registered the application. This reguirement is crucial for the security of the external application and the protection against possible vulnerabilities.

Application Id / API Key info are passed to each request made to integration service using the following headers:

  • X-CloudPlatform-ApplicationId
  • X-CloudPlatform-APIKey

Security

Security of the service is based on Authorization and HTTPS access. Eventhough HTTPS access is not required, this should not be the case for Production environment.

Error Handling

Proper error handling is crusial for the success of the application. Integration service is responsible for properly handle errors and provides accurate description regarding the causes a call has failed.

Logging

We strongly recommend that you design your integration such that it is capable of logging API requests and responses. Having access to the raw requests and responses (including detailed error codes and error messages) when API issues emerge will streamline troubleshooting and accelerate time to resolution.

The following examples show the type of information that your application should log for API requests and responses.

End Points

The actions that should covered by integration service’s end points are separated in 4 categories:

  • Setup Configuration
  • Accounts Management
  • Subscriptions Management
  • Addons Management

Optionally, in case a service provider wants to deliver users administration functionality, the following 2 categories should also be covered:

  • Users Management
  • User Services Management

A brief description of the end points of each category and their scope are available in the following table.

Setup Configuration

Get Setup FieldsCalled to retrieve the settings that should be configured in order to communicate with the external system
Validate Setup Fields Called to check and validate the settings configured for the external system
Get Service DefinitionCalled to retrieve the details for the services that supported by the external system and their characteristics.

Accounts Management

Account Get Synchronization OptionsCalled to retrieve the info that should be collected in order to provision a user/customer to the external system
Account SynchronizeCalled in order to create/update a user/customer to the external system
Account Is ResellerCalled in order to check if a user/customer is a reseller for the external system
Account DeleteCalled in order to delete a user/customer from the external system
Account Exists

Called in order to check whether a Cloud BSS Account matches an existing user/customer from the external system.

Subscriptions Management

Subscription CreateCalled in order to create a subscription to the external system
Subscription UpdateCalled in order to update a subscription to the external system
Subscription ActivateCalled in order to activate a subscription to the external system
Subscription SuspendCalled in order to suspend a subscription to the external system
Subscription CancelCalled in order to cancel a subscription to the external system 

Addons Management

Addon CreateCalled in order to create an addon for a subscription to the external system
Addon UpdateCalled in order to update an addon of a subscription to the external system
Addon Cancel

Called in order to cancel an addon of a subscription to the external system

Users Management
Get CustomerCalled in order to get details for a specific customer in the external system
Get UsersCalled in order to get the users available for a specific user/customer in the external system
Get UserCalled in order to get details of a specific user from the external system
User CreateCalled in order to create a new user to the external system
User UpdateCalled in order to update the info of a user to the external system
User DeleteCalled in order to delete a user to the external system
User DisableCalled in order to disable a user to the external system
User ActivateCalled in order to activate a user to the external system
User DeprovisionCalled in order to deprovision a user to the external system
User ProvisionCalled in order to provision a user to the external system
User Reset PasswordCalled in order to reset the password of user to the external system
User Services Management
Get User ServicesCalled in order to get the services available for a specific user and their status to the external system
Add User ServiceCalled in order to assign a service to a specific user to the external system
Remove User ServiceCalled in order to deassign a service from a specific user to the external system

 

Code Samples

Service Management API end points can be developed in any language. The following samples are currently available to demonstrate or initialize the development of a service manager.

.NET Framework

Service Management API

Configure APIKey validation in web.config's AppSetting 'X-CloudPlatform-ApiKey'.

PHP

Service Management API

Configure $applicationId and $apikey validation in ServiceProvider.API.Authorization.class.php file.

Configure End Points


Definition of end points for an application is required in order to successfully provision services. End points can be defined at Cloud BSS > Setup > Administration > System Options > Applications Setup > Edit Integration.

Each end point matches a provisioning action triggered by interworks.cloud Platform.

Users Management and User Service Management end points are only available when "Enable Users Management" flag is checked. 

The flag "Enable Users Management" is used to define if the integrated application supports management of users and the user services assigned to them. These end points are utilised through "My Workspace" page of interworks.cloud Platform Storefront when a subscription of current application is acquired by a customer and a set of resources becomes available to him.

Test EndPoints


By selecting  action next to each point, can be used to trigger a call to the endpoint by simulating a provisioning action for a finctional configuration. This action can be used during development in order to test integration service's methods.

The objects submitted from 'Run test' action of an end point, are flagged with IsTest='true' attribute.

By selecting 'Run test' action next to an end point, triggers a request to the defined URL. The produced HTTP request and the HTTP response returned by end point are displayed as shown below.

Send email notification to customer

By synchronizing an account with the external system (see Account Synchronization), the Account Synchronize end point is called in order to create a new user/customer for access to the services provided by the external system.

In case external system has a notification engine, an email will be submitted to the email address of the new end user/customer containing instructions for access and configuration of the new services. But, a notification engine may not be available for the external system or may not be sufficient for the submission of the neccessary info. In that case, Cloud BSS can handle this submission using the 'Send email notification to customer' flag available below 'Account Syncrhonize URL' field.

By enabling tha flag 'Send email notification to customer' a notification is automatically created for current application and Cloud BSS Notification Engine will submit an email to end customer whenever an acount is synchronized. The notification is available in Cloud BSS > Setup > Administration > Notifications > Customer Notifications for Accounts module. 

The notification template can be changed in order to met the UI and the infos that are neccessary for current application.

Selection of link, quickly redirects to edit notification template page.

An example of email produced by the notification template is given below.

Deactivate Application

Deactivation of an application disables all actions related to provisioning of services supported by current application. 

By selecting 'Deactivate' action, a message is shown in order to warn the user for the result of deactivation action.

By confirm the action, by selecting 'OK', the application is deactivated and the application is appeared with red light in Cloud Apps list page.

Reactivation of the application can be performed by selecting 'Activate' action, that provides similar operation with deactivation process.

 

Unregister Application

Unregistering an application, removes all configuration details related with current application including product types, variations, end point urls, images, etc.

By selecting 'Unregister application' action, a message is shown in order to warn the user for the result of unregister action.

By confirm the action, by selecting 'OK', the application is removed by the system and all product types and variations are deleted.

The action can not be completed in case product definitions are present in the system and the following modal is shown referencing all products using product types of current application.

In order to continue with the 'Unregister Application' action, all product definitions should be removed. In order to remove a product, Cloud BSS should not contain subscriptions or orders that use it. So, 'Unregister Application' action can be performed effectivelly only on early steps of an application, before any actual usage is made.

Configure Settings 


Configuration of an application instances can be made through action.

The values defined in this form are stored in interworks.cloud Platform and passed to all calls to integration service in order to be used as authentication info.

The values included in each call as http headers with pattern 'X-CloudPlatform-Setting-*'. For example, the value for 'username' field is passed to http header with name 'X-CloudPlatform-username'.

Get Service Definition 

Once 'Setttings' is configured for an application, the system is ready for getting the definitions for the services supported by the external system.

The action should executed in order to retrieve the service definitions.

By selectiong 'OK' the system gets the service definitions and creates product types the services described.

Product types can be found at Cloud BSS > Setup > Billing > Products > Product Types.

Create Products 


The final step in order to complete adminsitration tasks of the integration process is to create the products that will be used for services purchase by the end customers.

The selection of product’s product type is the info that instructs provisioning engine witch service to provision and from witch external system should the services set available to customer.

Product variations (along with order variations) define the resources for service provisioning (e.g. for VMs the number of CPU Cores)

Provisioning of services is performed only for products with ‘Recurring charge – prepaid’ or ‘Recurring charge – Pay-per-use (PPU)’ when a new subscription is created or an order is executed.

 

End Point Details

Setup Configuration

Get Setup Fields

Returns definitions for the extra fields that will be available on 'Settings' of the application.

Request

Http Verb: GET

Basic type

Response
{
    "Fields": [
        {
            "ID": "username",
            "Definition": {
                "ID": "username",
                "SortOrder": 0,
                "Name": "User Name",
                "Kind": "Text",
                "MaxLength": 20,
                "IsRequired": true
            }
        },
        {
            "ID": "password",
            "Definition": {
                "ID": "password",
                "SortOrder": 0,
                "Name": "Password",
                "Kind": "PasswordText",
                "MaxLength": 20,
                "IsRequired": true
            }
        },
        {
            "ID": "StorageLocation",
            "Definition": {
                "ID": "StorageLocation",
                "SortOrder": 0,
                "Name": "Storage Location",
                "Kind": "PredefinedChooseOne",
                "MaxLength": 0,
                "IsRequired": true,
                "PredefinedValues": {
                    "1": "Data Center 1",
                    "2": "Data Center 2"
                }
            }
        }
    ]
}

 

Validate Setup Fields

Validates values provided for 'Settings' of the application and return errors accordingly.

Request

Http Verb: POST

Request

{

 "Fields": [
{
"ID": "username",
"Value": "test"
},
{
"ID": "password",
"Value": "123456"
}
]
};

Response

[
"Invalid username",
"Password could not be empty"
]
 


Get Service Definitions

 Get definitions for the services supported by application. 

 

Request

Http Verb: GET

Response

{
"ProductTypes": [
{
"ID": "myservice",
"Name": "Example Service",
"Description": "The definition of an example service",
"AllowMultipleSubscriptions": true,
"AutoExecuteAddonCancelRequest": false,
"AutoExecuteSubscriptionCancelRequest": false,
"AutoExecuteSubscriptionDowngradeRequest": false,
"QuantityLimit": 0,
"QuantityLimitLocked": false,
"Scope": "Both",
"Restrictions": null,
"ExtraParameters": null,
"AttributeList": [
{
"Usage": "ProductCharacteristic",
"Kind": "Numeric",
"ID": "valueNumeric",
"SortOrder": 1,
"Name": "Numeric value",
"Description": "Type a numeric value to define service attribute",
"UsageSpecified": true,
"KindSpecified": true,
"IsRequired": true,
"IsSyncLocked": 0,
"LinkedToQuantity": false,
"AllowUnlimited": false,
"PredefinedValues": [],
"ExtraParameters": null,
"SliderMin": 0,
"SliderMax": 0,
"SliderStep": 0
},
{
"Usage": "OrderCharacteristic",
"Kind": "PredefinedChooseOne",
"ID": "valueList",
"SortOrder": 2,
"Name": "List value",
"Description": "Select a value from the list to define service attribute",
"UsageSpecified": true,
"KindSpecified": true,
"IsRequired": true,
"IsSyncLocked": 0,
"LinkedToQuantity": false,
"AllowUnlimited": false,
"PredefinedValues": [
{
"ID": "1",
"Code": "1",
"Name": "Value 1",
"IsDefault": false,
"ResourceId": 0
},
{
"ID": "2",
"Code": "2",
"Name": "Value 2",
"IsDefault": false,
"ResourceId": 0
},
{
"ID": "3",
"Code": "3",
"Name": "Value 3",
"IsDefault": false,
"ResourceId": 0
},
{
"ID": "4",
"Code": "4",
"Name": "Value 4",
"IsDefault": false,
"ResourceId": 0
}
],
"ExtraParameters": null,
"SliderMin": 0,
"SliderMax": 0,
"SliderStep": 0
},
{
"Usage": "ProductCharacteristic",
"Kind": "Boolean",
"ID": "valueCheckbox",
"SortOrder": 3,
"Name": "Bool value",
"Description": "Check to define service attribute",
"UsageSpecified": true,
"KindSpecified": true,
"IsRequired": true,
"IsSyncLocked": 0,
"LinkedToQuantity": false,
"AllowUnlimited": false,
"PredefinedValues": [],
"ExtraParameters": null,
"SliderMin": 0,
"SliderMax": 0,
"SliderStep": 0
},
{
"Usage": "ProductCharacteristic",
"Kind": "PredefinedChooseMany",
"ID": "valueCheckboxes",
"SortOrder": 4,
"Name": "Multiple checkboxes value",
"Description": "Select multiple values from the list to define service attribute",
"UsageSpecified": true,
"KindSpecified": true,
"IsRequired": true,
"IsSyncLocked": 0,
"LinkedToQuantity": false,
"AllowUnlimited": false,
"PredefinedValues": [
{
"ID": "1",
"Code": "1",
"Name": "Value 1",
"IsDefault": false,
"ResourceId": 0
},
{
"ID": "2",
"Code": "2",
"Name": "Value 2",
"IsDefault": false,
"ResourceId": 0
},
{
"ID": "3",
"Code": "3",
"Name": "Value 3",
"IsDefault": false,
"ResourceId": 0
},
{
"ID": "4",
"Code": "4",
"Name": "Value 4",
"IsDefault": false,
"ResourceId": 0
}
],
"ExtraParameters": null,
"SliderMin": 0,
"SliderMax": 0,
"SliderStep": 0
}
]
}
]
}

 

Accounts Management

Account Get Sync Options

Get definition of fields that should be collected for synchronizing an account.

Request

Http Verb: GET

Response

{
"Fields": [
{
"ID": "username",
"Definition": {
"ID": "username",
"SortOrder": 0,
"Name": "Username",
"Description": "",
"Kind": "SimpleValue",
"DataType": "Text",
"IsRequired": true,
"PredefinedValues": []
}
}
]

 


Account Synchronize

Create customer/user for external application.

Request

Http Verb: POST

Request

{
	 "ID": "13",
	 "ExternalID": "",
	 "ResellerID": null,
	 "ResellerExternalID": null,
	 "Name": "My Reseller",
	 "Code": "ress",
	 "Phone": "",
	 "Fax": "",
	 "WebSite": "",
	 "Email": "my@r.com",
	 "Description": "",
	 "ExtraDetails": {},
	 "SyncOptions": {
		 "username": "test"
	 },
	 "ContactDetails": {
		 "ID": "16",
		 "FirstName": "Stelios",
		 "LastName": "Reseller",
		 "Phone": "",
		 "Fax": "",
		 "Email": "my@r.com"
	 }
}

Response

{
"ErrorCode": 0,
"ErrorMessage": "",
"Result": ""
}


Account Is Reseller

Check if the account info provided matching an reseller customer. 

Request

Http Verb: POST

Request

{
	 "ID": "13",
	 "ExternalID": "",
	 "ResellerID": null,
	 "ResellerExternalID": null,
	 "Name": "My Reseller",
	 "Code": "ress",
	 "Phone": "",
	 "Fax": "",
	 "WebSite": "",
	 "Email": "my@r.com",
	 "Description": "",
	 "ExtraDetails": {},
	 "SyncOptions": {
		 "username": "test"
	 },
	 "ContactDetails": {
		 "ID": "16",
		 "FirstName": "Stelios",
		 "LastName": "Reseller",
		 "Phone": "",
		 "Fax": "",
		 "Email": "my@r.com"
	 }
}

Response

{
"ErrorCode": 0,
"ErrorMessage": "",
"Result": ""
}


Account Delete

Delete a user/customer from the external system.

Request

Http Verb: POST

Request

{
	 "ID": "13",
	 "ExternalID": "",
	 "ResellerID": null,
	 "ResellerExternalID": null,
	 "Name": "My Reseller",
	 "Code": "ress",
	 "Phone": "",
	 "Fax": "",
	 "WebSite": "",
	 "Email": "my@r.com",
	 "Description": "",
	 "ExtraDetails": {},
	 "SyncOptions": {
		 "username": "test"
	 },
	 "ContactDetails": {
		 "ID": "16",
		 "FirstName": "Stelios",
		 "LastName": "Reseller",
		 "Phone": "",
		 "Fax": "",
		 "Email": "my@r.com"
	 }
}

Response

{
"ErrorCode": 0,
"ErrorMessage": "",
"Result": ""
}


Account Exists

Check if the account info provided matching an existing customer. 

Request

Http Verb: POST

Request

{
	 "ID": "13",
	 "ExternalID": "",
	 "ResellerID": null,
	 "ResellerExternalID": null,
	 "Name": "My Reseller",
	 "Code": "ress",
	 "Phone": "",
	 "Fax": "",
	 "WebSite": "",
	 "Email": "my@r.com",
	 "Description": "",
	 "ExtraDetails": {},
	 "SyncOptions": {
		 "username": "test"
	 },
	 "ContactDetails": {
		 "ID": "16",
		 "FirstName": "Stelios",
		 "LastName": "Reseller",
		 "Phone": "",
		 "Fax": "",
		 "Email": "my@r.com"
	 }
}

Response

{
"ErrorCode": 0,
"ErrorMessage": "",
"Result": ""
}

Subscriptions Management

Subscription Create

Create a new subscription / provision a service.

Request

Http Verb: POST

Request

{

	 "ID": "",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": []
}

Response

{
"AccountExtraInfo": null,
"Code": 0,
"Message": "",
"Result": "2103213618"
}


Subscription Update

Update an existing subscription / increase-decrease resources for a service.

Request

Http Verb: POST

Request

{

	 "ID": "2AD88E58-9EBB-41DA-BF74-AFAFFD7E4011",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": []
}

Response

{
"AccountExtraInfo": null,
"Code": 0,
"Message": "",
"Result": "2103213618"
}


Subscription Delete

Delete a subscription / deprovision service

Request

Http Verb: POST

Request

 

{
"ID": "2AD88E58-9EBB-41DA-BF74-AFAFFD7E4011",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": []
}

Response

{
"AccountExtraInfo": null,
"Code": 0,
"Message": "",
"Result": "2103213618"
}


Subscription Activate

Activate subscription / enable services

Request

Http Verb: POST

Request

 

{
"ID": "2AD88E58-9EBB-41DA-BF74-AFAFFD7E4011",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": []
}

Response

{
"AccountExtraInfo": null,
"Code": 0,
"Message": "",
"Result": "2103213618"
}


Subscription Suspend

Suspend subscription / suspend service

Request

Http Verb: POST

Request

 

{
"ID": "2AD88E58-9EBB-41DA-BF74-AFAFFD7E4011",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": []
}

Response

{
"AccountExtraInfo": null,
"Code": 0,
"Message": "",
"Result": "2103213618"
}

Addons Management

Addon Create

Create a new addon for a specific subscription / modify resources for service

Request

Http Verb: POST

Request

 

{
"ID": "2AD88E58-9EBB-41DA-BF74-AFAFFD7E4011",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": [
{
"ID": "",
"Name": null,
"ProductID": "2D3D5B37-84C1-4848-8731-059875E01DBB",
"ActionType": "Provision",
"Quantity": 1,
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "0",
"Code": ""
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2; Value 3",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "0.000000",
"Code": ""
}
}
}
]

}

Response

{
"Code": 0,
"Message": "",
"Result": "2103213618"
}


Addon Update

Update an addon // modify resources for service

Request

Http Verb: POST

Request

 

{
"ID": "2AD88E58-9EBB-41DA-BF74-AFAFFD7E4011",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": [
{
"ID": "3F7093F5-260D-4E11-B977-01580CC5FAB6",
"Name": null,
"ProductID": "2D3D5B37-84C1-4848-8731-059875E01DBB",
"ActionType": "Provision",
"Quantity": 1,
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "0",
"Code": ""
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2; Value 3",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "0.000000",
"Code": ""
}
}
}
]

}

Response

{
"Code": 0,
"Message": "",
"Result": "2103213618"
}


Addon Delete

Delete an addon // modify resources for service

Request

Http Verb: POST

Request

 

{
"ID": "2AD88E58-9EBB-41DA-BF74-AFAFFD7E4011",
"ServiceType": "MyService",
"ProductID": "C4A37F95-ABF7-4681-BFB0-39EEF4E8517D",
"ActionType": "Provision",
"Quantity": 1,
"Account": {
"ID": "13",
"ExternalID": "2103213618",
"ResellerID": null,
"ResellerExternalID": null,
"Name": "My Reseller",
"Code": "ress",
"Phone": "",
"Fax": "",
"WebSite": "",
"Email": "my@r.com",
"Description": "",
"ExtraDetails": {},
"SyncOptions": {
"username": "test"
},
"ContactDetails": {
"ID": "16",
"FirstName": "Stelios",
"LastName": "Reseller",
"Phone": "",
"Fax": "",
"Email": "my@r.com"
}
},
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "1",
"Code": ""
},
"valueList": {
"ID": "valueList",
"Name": "List value",
"Value": "Value 2",
"Code": "2"
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "1.000000",
"Code": ""
}
},
"Addons": [
{
"ID": "3F7093F5-260D-4E11-B977-01580CC5FAB6",
"Name": null,
"ProductID": "2D3D5B37-84C1-4848-8731-059875E01DBB",
"ActionType": "Delete",
"Quantity": 1,
"AttributeList": {
"valueCheckbox": {
"ID": "valueCheckbox",
"Name": "Bool value",
"Value": "0",
"Code": ""
},
"valueCheckboxes": {
"ID": "valueCheckboxes",
"Name": "Multiple checkboxes value",
"Value": "Value 1; Value 2; Value 3",
"Code": ""
},
"valueNumeric": {
"ID": "valueNumeric",
"Name": "Numeric value",
"Value": "0.000000",
"Code": ""
}
}
}
]

}

Response

{
"Code": 0,
"Message": "",
"Result": "2103213618"
}

 

Users Management

Get Customer

Get details for a customer

Request

Http Verb: POST

Request

{
"ID": "customer_1"
}

Response

{
"ID": "customer_1",
"Name": "Customer A",
"PrimaryDomain": "customerA.com",
"Status": "Provisioned",
"TotalUsers": 5
}

Get Users

Get list of Users for a specific Customer

Request

Http Verb: POST

Request

{
"CustomerID": "customer_1",
"SearchText": "Customer",
"PageID": 1,
"PageSize": 25
}

Response

{
"Users": [{
"ID": "user_1",
"Customer": {
"ID": "customer_1",
"Name": "Customer A"
},
"FirstName": "Test",
"LastName": "User A",
"DisplayName": "Test User A",
"Username": "test@userA.com",
"Email": "test@userA.com",
"Status": "Provisioned",
"Role": "User",
"TotalServices": 1
}, {
"ID": "user_2",
"Customer": {
"ID": "customer_1",
"Name": "Customer A"
},
"FirstName": "Test",
"LastName": "User B",
"DisplayName": "Test User B",
"Username": "test@userB.com",
"Email": "test@userB.com",
"Status": "Disabled",
"Role": "Administrator",
"TotalServices": 1
}],
"TotalUsers": 2,
"AvailableServices": [{
"ID": "storage_basic",
"Name": "Cloud Storage Basic"
}, {
"ID": "backup_premium",
"Name": "Cloud Storage Backup Premium"
}, {
"ID": "sync_enterprise",
"Name": "Sync Cloud Services Enterprise"
}]
}

Get User

Get details of a User

Request

Http Verb: POST

Request

{
"ID": "user_1",
"Customer": {
"ID": "1"
}
}

Response

{
"ID": "user_1",
"FirstName": "Test",
"LastName": "User C",
"DisplayName": "Test User C",
"Username": "test@userC.com",
"Email": "test@userC.com",
"Status": "Disabled",
"Role": "Administrator",
"TotalServices": 3
}
User Create

Create a new User

Request

Http Verb: POST

Request

{
"Customer": {
"ID": "customer_1"
},
"FirstName": "Test",
"LastName": "User",
"DisplayName": "Test User",
"Username": "user@test.com",
"Email": "user@test.com",
"Password": "{Password}"
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Update

Update an existing User

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
},
"FirstName": "Test",
"LastName": "User",
"Email": "user@test.com",
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Delete

Delete a User

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Disable

Disable a User

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Activate

Activate a User

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Deprovision

Deprovision a User

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Provision

Provision a User

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Reset Password

Reset password for a User

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

User Services Management

Get User Services

Get services available for a User and their status

Request

Http Verb: POST

Request

{
 "ID": "user_1565",
	 "Customer": {
"ID": "customer_1"
}
}

Response

[
{
"ID": "storage_basic",
"Name": "Cloud Storage Basic",
"Enabled": false
},
{
"ID": "backup_premium",
"Name": "Cloud Storage Backup Premium",
"Enabled": false
},
{
"ID": "sync_enterprise",
"Name": "Sync Cloud Services Enterprise",
"Enabled": true
}
]

Add User Service

Assign a new service for a selected User

Request

Http Verb: POST

Request

{
"ServiceID": "basic",
"User": {
"ID": "user_1565",
"Customer": {
"ID": "customer_1"
}
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

Remove User Service

Remove a service from a selected User

Request

Http Verb: POST

Request

{
"ServiceID": "basic",
"User": {
"ID": "user_1565",
"Customer": {
"ID": "customer_1"
}
}
}

Response

{
"Code": 0,
"Message": "",
"Result": "user_1565"
}

Object Types

The following object types are included in Code Samples or can be downloaded independently for the following languages

Object: FieldDefinition

{
        "ID": "StorageLocation",
        "SortOrder": 0,
        "Name": "Storage Location",
        "Description": "Define the location of the storage",
        "Kind": "PredefinedChooseOne",
        "MaxLength": 0,
        "IsRequired": true,
        "PredefinedValues": {
          "1": "Data Center 1",
          "2": "Data Center 2"
        }
}
IDExternal system identifier
SortOrderThe position of the field in settings
NameThe display name
DescriptionDescription for the field
Kind

Text - text input

PasswordText - password text input

Url - url input

Integer - numeric input

PredefinedChooseOne - dropdown input

PredefinedChooseMany - multiple select checkboxes input

MaxLengthThe maximum number of characters a user can enter for this field
IsRequired

true, in case the value of this field is required,

false, otherwise

PredefinedValuesAn array of values to be display in case Kind is PredefinedChooseOne or PredefinedChooseMany

1 Comment

  1. Unknown User (f.ebeoglou)

    Most of the Service Management API Responses are of type ResultDefinition or Extensions of  ResultDefinition [AccountResultDefinition, ServiceResultDefinition].

    ResultDefinition {

    Code:integer ($int32)
    Message:string
    Result:string

    }

    The member Code is the signed Integer value, returned inside the BSS to provide Error Code.

    • If Code is a negative number (i.e. -1) then we return error text inside the Message of the Object.
    • If Code is 0 then it means no exception/error during external API call but Result empty value returned.
    • If Code is a positive number (i.e. 1) then successfully completed the API Call and Result value is filled.