Training Guides

Service Connector

Tags: API, Marketplace Services

Service Connector

Why do this..

The provisioning type is selected when setting up a new service. The provisioning type defines the action when a customer subscribes to a service. Currently, there are two options, email or Service Connector. The email option sends an email to a nominated email address containing the provisioning information. The service connector allows for your REST API call to be made to transfer the same service information to your 3rd party system.

This document walks you through the Service Connector option and the available API calls. The user should be able to access or create middle ware that takes the provisioning data from Cloudmore, provisions the service and returns the result back to Cloudmore.

 

Important

Cloudmore only provides detailed information about how to setup the Service Connector and the description of the API calls. It’s the user’s responsibility to provide and manage the REST API to receive the API calls. Cloudmore has created a solution, built on standard, available technologies, and a workflow that integrates with the services setup procedure. Cloudmore cannot incorporate bespoke or special configuration or changes.

Test application

Cloudmore provides a test application that can be used as a reference point for implementation. The test application is a REST API built in .NET that will receive calls from Cloudmore and store them temporarily. The test client cannot be used for live implementations, but can be used during development to show the data sent in API requests.

Cloudmore provides both the source code and test client as is with no warranties or guarantees.

Security

Cloudmore has built the Service Connector security on OAuth2 standard grant type called “client credentials.” OAuth 2.0 is the industry-standard protocol for authorization and enables a secure authentication between Cloudmore and your 3rd party system.

Your 3rd party system needs to be able to handle the authentication request from Cloudmore and issue an access token in JSON format (a JSON Web Token or JWT).

Cloudmore has developed the Service Connector using IdentiyServer4 (http://docs.identityserver.io), an OpenID and OAuth 2.0 framework for ASP.NET Core. This is one example of how the OAuth2 framework can be used.

To further ensure the security, all data is encrypted in transmission, all requests must be performed over HTTPS. 

The client grant type requires three key pieces of information:

  1. Client ID – The client ID is generated by the 3rd party system as an ID for the Cloudmore platform.
  2. Client Secret – The client secret is similar to a password used for the client ID. It is also generated by the 3rd party system. The client secret is maintained within Cloudmore in encrypted form and decrypted only when a request is sent. The client secret cannot exceed 20 characters in length.
  3. Authorization URL (or endpoint) – This is the address (URL) that Cloudmore will use to request and obtain an access token. Example: https://3rdpartydomain.com/authentication/token/

Service connector Setup  in Cloudmore

To setup the security properties, login to Cloudmore and go to Services on seller level or Custom Services on reseller level. Then, add a new service and select “Service Connector” under Provisioning Type. You will then get a form that looks like this:

Screen Shot 2017-08-23 at 15.56.21.png

  1. Client id – Enter the client Id generated by the 3rd party system.
  2. Client Secret – Enter the client secret generated by the 3rd party system.
  3. Authorization URL – Enter the URL to the 3rd party OAuth2 server.
  4. Custom Service URL – Enter the URL where to send provisioning request to. Example: https://3rdpartydomain.com/api/customservice/
  5. User Subscription URL (Only visible if you have selected “User assigned service”) – Enter the URL where provisioning of users should be sent. Example: https://3rdpartydomain.com/api/usersubscription/

Create the Service and add products. Click on the “Manage products” (book) icon next to the service. Complete the form. When you get to “provisioning management” section, fill in the “REST API Subscription URL.” This is the URL specific to this product. Example: https://3rdpartydomain.com/api/subscriptions/

Note: The Service Connector supports custom properties. You can add custom properties to a product to send additional data to the API. Custom properties can be visible or hidden to the user.

Provisioning Events

An API call should be triggered by certain events in Cloudmore. Below is a list of events and the API call that is triggered.

Note: All the Service Connector calls will fail if a valid authorization access token is not sent with each call. In all such cases, the response code would be 401 – Unauthorized.

Cloudmore will expect the 3rd party system to respond with a response code to indicate the outcome of the API call. Also, for some calls, the 3rd party system might need to send a data response.

Cloudmore Event

HTTP Command

Data Provided

Expected REST API Response Codes

Expected Data Returned

Organization adds Service

POST

Record data – provided in body of the request – details below

Success – 201 (Created)

Failure – 400 (Bad Request)

Newly created record URI or address on the 3rd party REST API system

Organization removes Service

DELETE

URI of record to delete

Success – 204 (No content)

None

Organization subscribes to Service

POST

Record data – provided in body of the request – details below

Success – 201 (Created)

Failure – 400 (Bad Request)

Newly created record URI or address on the 3rd party REST API system

Organization updates a subscription

PUT

Record data – provided in body of the request – details below

Success – 204 (No content)

None

Organization removes a subscription

DELETE

URI of record to delete

Success – 204 (No content)

None

User subscribes to a user assigned Service

POST

Record data – provided in body of the request – details below

Success – 201 (Created)

Failure – 400 (Bad Request)

Newly created record URI or address on the 3rd party REST API system

User updates a subscription to user assigned Service

PUT

URI of record to update and record data – provided in body of the request – details below

Success – 204 (No content)

None

User removes subscription to a user assigned Service

DELETE

URI of record to delete

Success – 204 (No content)

None

 

 

Default data provided in Service Connector Request Body by Procedure

Cloudmore will include the following data in JSON format in the body of the HTTP request in the following events:

Organization adds a service  

Property Name Data Type Description
recordId N/A This is generated by the 3rd party system and provided to Cloudmore. Needs to be a unique identifier and can be setup as a GUID, INT or text. The record ID are used for validation and data access purposes.
serviceName Text The name of the service setup by the service provider in Cloudmore.
serviceId Guid The Cloudmore GUID of the service, generated by Cloudmore. Used as a unique identifier of the service and will never change.
organizationName Text The name of the organization that is adding the service as it is setup in Cloudmore.
customerNumber Text The customer number set on the organization in Cloudmore.
registrationNumber Text The registration number set on the organization in Cloudmore.
contactName Text The name of the contact person set on the organization in Cloudmore.
contactPhone Text The phone number of the contact person set on the organization in Cloudmore.
contactCellPhone Text The cell phone number of the contact person set on the organization in Cloudmore.
contactEmail Text The email address of the contact person set on the organization in Cloudmore.
jobTitle Text The job title of the contact person set on the organization in Cloudmore.
notificationEmail Text The notification email address set on the organization in Cloudmore.
street Text The street address set on the organization in Cloudmore.
city Text The city set on the organization in Cloudmore.
state Text The state/province/region set on the organization in Cloudmore. Note! Not all countries have states and if so this value will be empty.
postalCode Text The postal code set on the organization in Cloudmore.
country Text The country full name as text set on the organization in Cloudmore. For instance "Sweden".
organizationApprovalProcess True/False Returns the current setting for Approval Process set on the organization as a Boolean value.
organizationVAT Text The VAT number set on the organization in Cloudmore.
     
     

Organization creates or updates a subscription  

Property Name Data Type  
recordId N/A This is generated by the 3rd party system and provided to Cloudmore. Needs to be a unique identifier and can be setup as a GUID, INT or text. The record ID are used for validation and data access purposes.
serviceName Text The name of the service that the subscription is created for. The name of the service is setup by the service provider in Cloudmore.
name Text The name of the subscription set by the organization.
productName Text The name of the selected product for the subscription. The name of the product is set by the service provider in Cloudmore.
productId Guid The Cloudmore GUID of the product generated by Cloudmore. Used as a unique identifier of the product and will never change.
subscriptionPeriod Text The selected subscription period set by the organization on the subscription. Value is return as number of months. Zero "0" means pay-as-you-go subscription.
billingInterval Text The billing interval set by the organization on the subscription. Value is returned as number of months. "1" means monthly billing interval. "0" means no recurring billing and should be treated as a one-time payment item. 
productItemCode Text The item code of the select product for the subscription. The item code is set by the service provider in Cloudmore.
quantity Number The quantity selected for the subscription by the organization.
poNumber Text The PO Number entered for the subscription. PO Number is optional in Cloudmore.
trial Text – “true” or “false” The trial setting of the subscription selected by the organization. Will be returned as TRUE or FALSE.
trialLengthDays Number The number of days of the trial if trial is enabled for the organization.
Custom Properties (if defined)   Custom properties for the subscription. Only included if custom properties has been setup for the service by the service provider, otherwise empty.
customPropertyX (where X is replaced with a sequential number starting with 1).  Various The custom property identifier, generated by Cloudmore as a sequential number starting with 1.
Addons (if defined)   The add-ons for the subscription if add-ons are present for the product.
For each addon, 4 data elements are provided as outlined below Array  
addonId Number The ID for the add-on setup by the service provider in Cloudmore.
addonName Text The name of the add-on setup by the service provider in Cloudmore.
addonItemCode Text The item code of the add-on setup by the service provider in Cloudmore.
addonQuantity Number The add-on quantity selected by the organization for the subscription.
     
     

User is assigned or removed from a service

Property Name Data Type Description
recordId N/A This is generated by the 3rd party system and provided to Cloudmore. Needs to be a unique identifier and can be setup as a GUID, INT or text. The record ID are used for validation and data access purposes.
customServiceName Text The name of the service that the user is assigned to. The name of the service is setup by the service provider in Cloudmore.
customServiceId GUID The Cloudmore GUID of the service, generated by Cloudmore. Used as a unique identifier of the service and will never change.
subscriptionName Text The name of the subscription the user is assigned to set by the organization.
subscriptionId GUID The Cloudmore GUID of the subscription, generated by Cloudmore. Used as a unique identifier of the subscription and will never change.
username Text The username of the user that is assigned to the subscription.
firstName Text The first name property of the user that is assigned to the subscription.
lastName Text The last name property of the user that is assigned to the subscription.
title Text The job title property of the user that is assigned to the subscription.
displayName Text The display name property of the user that is assigned to the subscription.
company Text The company name property of the user that is assigned to the subscription.
department Text The department name property of the user that is assigned to the subscription.
office Text The office name property of the user that is assigned to the subscription.
email Text The email address property of the user that is assigned to the subscription.
phoneHome Text The home phone number property of the user that is assigned to the subscription.
phoneCell Text The cell phone number property of the user that is assigned to the subscription.
addressStreet Text The street address property of the user that is assigned to the subscription.
addressCity Text The city property of the user that is assigned to the subscription.
addressState Text The state/province/region property of the user that is assigned to the subscription. Note! Not all countries have states and if so this value will be empty.
addressPostalCode Text The postal code property of the user that is assigned to the subscription.
addressCountry Text The country property of the user that is assigned to the subscription.
role Text The role property of the user that is assigned to the subscription.
Custom Properties (if defined)   Custom properties for the subscription. Only included if custom properties has been setup for the service by the service provider, otherwise empty.
customPropertyX (where X is replaced with a sequential number starting with 1). Various The custom property identifier, generated by Cloudmore as a sequential number starting with 1.

 

END

Comments or suggestions?