Interface Specification SaaS applications

Version 5.0

1
1. Interfacing Concept
ComProvis is Hrvatski Telekom’s ICT cloud infrastructure system. It has multiple purposes:

 It serves as Single Sign On (SSO) entry point for end-users into the cloud system, thus
enabling cloud users to access multiple services with a single account;
 It serves as a virtual marketplace, where company admin (cloud power user with role assigned
by his company) manages Cloud service contract and has the possibility to order and/or delete
various services for her end-users. Company admin is also the person who enters (and
removes) associated end-users into the system, providing them with access to various services
and / or applications;
 It acts as a provisioning server by building up required service, or terminating it, within the
virtualization infrastructure.

ComProvis manages "Software as a service" (SaaS) end-user accounts for consuming cloud services
and serves as a provisioning mediator between cloud services marketplace and cloud infrastructure.

Any new application being published for servicing end-user from cloud infrastructure must be
registered within ComProvis first. After being registered, ComProvis shall require opening of a new
user account within the SaaS application for each ComProvis user that has been assigned individual
application. After this procedure is completed, new end-user’s login into published SaaS application is
enabled.

Since ComProvis maintains user records for all platforms and services within the cloud, it is assumed
that SaaS application shall not keep track of any deleted users, i.e. such users shall not be put it into
any kind of ‘inactive’ state, and cannot be reactivated, but only created anew. Only temporarily
suspended user accounts will remain in the SaaS application until re-activated.

2. Web service methods

Web service methods are divided in to two parts. Methods implemented by the SaaS application that
enable the propagation of data to the SaaS application. They are referred as the SaaS applications web
service methods. Methods implemented by the system to enable propagation of data from the SaaS
applications to the system. They are referred as the Generic SaaS interface.

2.1.SaaS applications web service methods

All web service methods described here should be implemented by SaaS applications, to be consumed
by ComProvis, i.e. Hrvatski Telekom’s cloud infrastructure and single-sign-on system.

Assumption is that SaaS application is available for communication with portal in near-time. Every
request is supposed to be processed within agreed timeout frame (i.e. 3 min). Otherwise, User Admin
request will be cancelled at the portal, if communication with SaaS application is not successfully
completed.

2
SaaS application is expected to behave idempotently, to be able to match any new request with
previous ones and not process it if a duplicate one arrived.

2.1.1.Get Roles

GetRoles method is used to return list of all pre-defined roles within the SaaS application for specified
reseller. It is assumed this method shall return at least one role. Resellers are HT and other possible
vendors who may offer your application to its users via HT’s cloud infrastructure. HT as initial reseller
has to be entered manually into the SaaS application system, as well as roles/licenses aligned to HT’s
back-end systems.

After SaaS application is registered within ComProvis portal, this method is called for the first and
only time to obtain all available roles for application. If new roles need to be introduced for already
registered SaaS application SaaS application vendor together with HT must introduce a new SaaS
application (new version) within ComProvis.

Any new version of application that need to replace existing one at already exploited URL, must have
backward compatibility of roles.

If roles backward compatibility cannot be fully supported, then a new version of application must be
registered at the portal. Also, all parties must perform migration of users to new application and its
roles.

INPUT PARAMETERS

Parameter Type Description

Unique number for identification of reseller. For

resellerID string
HT use 1.

timestamp datetime Timestamp of the request

OUTPUT PARAMETERS

Parameter Type Description

tblSaaS_Role list An object with the list of all defined roles

roleID int Role unique ID within an SaaS application

roleName string Role name

3
 excluded bit Excluded role

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

Excluded parameter indicates to ComProvis to disable parallel assigning of excluded and any other
role to a single user. For an example: admin is excluded role, because it includes every other role like
“sales” or “service”. Sales and Service can be added to one user at the same time.

4
 2.1.2.GetSaaSApiVersion

GetSaaSApiVersion method is used for defining the version of the interfaces implemented by the SaaS
application. The value of the returned number should be defined in the provided SaaSApi class. If the
value is not provided then the version of the Interface Specification for SaaS applications document
can be used.

When a request for registering a new SaaS application is created within ComProvis portal.
GetSaaSApiVersion method will be called for the first and only time. Based on the value of the
returned version additional methods will or will not be called.

INPUT PARAMETERS

There are no input parameters.

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message and timestamp

Number indicating the SaaS api version implemented

Version int
by the application.
status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.3.InitializeApplication

InitializeApplication is a method for passing the necessary parameters need to interact with the system
to the SaaS application. The return value indicates if the application reviced the nessesery parameters.

The method is called for the first and only time when the application is registered within ComProvis
portal.

INPUT PARAMETERS

Parameter Type Description

URL of the web service used to interact with the

comProvisApiURL string
system.

ID of the application used by the system. Required in

applicationID int
requests passed to the web service.

OUTPUT PARAMETERS

5
 Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.4.AddUpdateUser

AddUpdateUser method is used for:

 Creating a new user account within the SaaS application;

 Editing of existing user data;
 Updating additional user data.

SaaS application returns indicator of successful execution of AddUpdateUser method. In case

ComProvis is receives a FALSE response, no new user account should be created within SaaS
application and/or no change in existing privileges (roles) should occur. In such cases, ComProvis will
raise an incident towards HT admin and/or Help Desk.

AddUpdateUser implements companyName argument. Company must be created within SaaS

application implicitly if it doesn’t exist (on creation of first user) and deleted if last user assigned to
that company is removed from SaaS application.

AddUpdateUser is used to update data associated to the user. If the application requires additional data
regarding the user then that data will be sent in the object additionalParameters. If the expected data is
not sent then the data stored on the application should be deleted. The values passed in
additionalParameters include four values. Values are sent if the values exist. Unique identifier of the
license is passed if the changed license is associated with a role that has HasUniqueIdentifier flag set
to true. Additional parameters and application product are sent if they exist. The number of licenses
added is sent if the role associated with the license modified has the IsRedistirbutable set to true.

INPUT PARAMETERS

Parameter Type Description

Internal User ID (SAML: 'guid') – unique ID both

ssoID string
within SaaS application and within ComProvis portal

name string User first name

surname string User family name

Username for logging into cloud (accessing SaaS

username string
application via ComProvis SSO portal)

6
 Unique identifier of company registers within
companyID int
ComProvis system

Unique name of company registered in ComProvis

companyName string
system.

resellerID int Unique reseller identifier. For HT use 1.

saasRoles list List of unique role ID within SaaS application

saasRoleID int Role unique ID within SaaS application

Object containing additional parameters relevant to

additionalParameters object the application. Can contain additional parameter
values, service product value and licenses ID-s.
timestamp datetime Timestamp of the request

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.5.DeleteUser

DeleteUser method is used for permanent deletion of user account that has been created previously
using AddUpdateUser method. Both regular (active) and suspended accounts can be deleted.

INPUT PARAMETERS

Parameter Type Description

ssoID string Internal User ID (SAML: 'guid')

timestamp datetime Timestamp of the request

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

7
 message string Execution message

timestamp datetime Timestamp of the response

2.1.6.ChangeUserStatus

ChangeUserStatus method is used for temporary disabling and enabling of user account for any new
login. Account should not be deleted, and no roles assignment change should occur upon calling of
this method.

Returned FALSE value should mean that no user account exists, because either invalid ssoID is sent or
the account has been deleted in the meantime.

INPUT PARAMETERS

Parameter Type Description

ssoID string Internal User ID (SAML: 'guid')

Sets user status (possibility to login to SaaS

userStatus int
application): 0 – suspended, 1 - active

timestamp datetime Timestamp of the request

8
OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.7.RemoveUserRoles

RemoveUserRole method is used for removing previously granted role(s) to the user account. If no
such assignment was made, thus no deletion was done, SaaS application returns FALSE.

INPUT PARAMETERS

Parameter Type Description

ssoID string Internal User ID (SAML: 'guid')

An object with the list of all defined roles. If NULL,

saasRoleID int? all roles associated to the user should be removed
from SaaS application.

timestamp datetime Timestamp of the request

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.8.AddService

AddService method is used for activating the service that the application offers to a customer. The
customer ID along with other customer information is passed in the input parameters. AddService
implements companyName argument. CompanyName argument is described in detail in section
AddUpdateUser.

9
The method is called when a service is sold to a customer through the system API. When a request is
received by the application the application should start offering the users of the customer the service in
the amount defined by the parameter serviceProduct.

Return status FALSE should mean that a service is already being offered to the customer so a new
service could not be added.

INPUT PARAMETERS

Parameter Type Description

companyID int ID of the company used by the system.

companyName string Name of the company.

companyOIB string National identification number of the company.

companyAddress string Address of the company.
Postal code of the city in which the company in
companyAddressPostalCode int
located.
companyAddressCity string City in which the company is located.
Name and last name of the contact person for the
companyContactPerson string
company.
companyContatctNumber string Contact number of the company.
Value of the service product offered to the
serviceProduct int company.

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.9.UpdateService

Method update service is used to update the value of the service offered to the customer by the
application. The ID of the customer is sent along with the new value of the service product.

The method is called when the value of the service product is changed.

Returned status FALSE should mean that the service doesn’t exist or it has been deleted in the
meantime.
10
INPUT PARAMETERS

Parameter Type Description

companyID int ID of the company used by the system.

Value of the service product offered to the

serviceProduct int company.

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.10. RemoveService

Method remove service is used to remove the service offered to the customer by the application. When
the application receives such a request it should stop offering the service to all users of the customer
and it should delete their licenses.

Returned status FALSE should indicate that the service doesn’t exist or it has been deleted in the
meantime.

INPUT PARAMETERS

Parameter Type Description

companyID int ID of the company used by the system.

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

11
 2.1.11. UpdateCompany

UpdateCompany is used to update the value of customer parameters. New values of customer
parameters will be set in the request.

The method will be called when one or more customer parameters change. The methods of all
applications that the changed customer bought will be called.

Retuned status FALSE should indicate that the company doesn’t exist or it has been removed in the
meantime.

INPUT PARAMETERS

Parameter Type Description

companyID int ID of the company used by the system.

companyName string Name of the company.

companyOIB string National identification number of the company.

companyAddress string Address of the company.
Postal code of the city in which the company in
companyAddressPostalCode int
located.
companyAddressCity string City in which the company is located.
Name and last name of the contact person for the
companyContactPerson string
company.
companyContatctNumber string Contact number of the company.

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.1.12. UpdateAdditionalParameter

UpdateAdditionalParameter method is used for updating the additional parameters of the user or of the
application. If no user GUID is defined in the request then the method was called to update the
additional parameters of the application. Old additional parameters should be removed and new values
should be saved.

Returned status FALSE should indicate that the user doesn’t exists or it has been deleted in the
meantime.

12
INPUT PARAMETERS

Parameter Type Description

userGUID string Identifier of the user.

A list of new additional parameters to be

additionalParameter List<AdditionalParameter>
saved instead of the old ones.

OUTPUT PARAMETERS

Parameter Type Description

result object Object containing Status and Message

status bool TRUE/FALSE execution indicator

message string Execution message

timestamp datetime Timestamp of the response

2.2.Using the SaaS Web Service Methods

2.2.1.Creating User Accounts

ComProvis is entitled to create user account calling AddUpdateUser method. Method saves or
updates the user records within the SaaS application.

Note that at least one role is always assigned to user (ssoID) at the moment of creating user record
within SaaS application.

2.2.2.Modifying User Data and Role Assignments

For update user data ComProvis portal calls AddUpdateUser method.

AddUpdateUser method called with NULL additional parameters will delete all additional
parameters associated to the user.

AddUpdateUser method called without the expected additional parameter value specified will delete
the expected additional parameter associated with the user.

UpdateUserRoles method called with NULL as a list of roles will delete every role on SaaS
application.

2.2.3.Deleting User Account

ComProvis is entitled to delete user account calling DeleteUser method.

13
Both regular (active) user account and suspended user account may be deleted.

2.2.4.Suspending/Reactivating the Service

Suspending the usage of SaaS application for particular user is done via suspending user account
within the SaaS application. Note that some other services even by the same SaaS application vendor
within the cloud may remain active.

For suspending application login for individual user, as well as for reactivation of such users,
ComProvis calls ChangeUserStatus method.

2.2.5.Activating/updating/deactivating the service

Activating the service to a customer (and all of his users) is done by calling the AddService method.

Updating the service to a customer is done by calling the UpdateService method.

Deactivation of the service to a customer is done by calling the RemoveService method.

2.2.6.Updating customer data

Updating the customer related data is done by calling the UpdateCustomer method.

2.2.7.Adding/updating additional parameter values

Adding the additional parameter values of the application is done by calling the
UpdateAdditionalParameter with the value of userGUID set to empty string.

Updating the additional parameters of the user is done by calling the AddUpdateUser method with
the specified new additional parameter values.

2.2.8.Application initialization

To enable communication with the system application will be sent the web service URL and the
application ID by calling the InitializeApplication method.

2.2.9.Retrieving the SaaS API version

To retrieve the SaaS API version the system will call the method GetSaaSApiVersion which will
return the version of the SaaS API used to implement the system.

14
 2.3.Generic SaaS interface
The generic SaaS interface is intended to provide all the necessary data to the SaaS applications so
they can implement their functionality. Also it will enable synchronization of data between the system
and the SaaS applications.

The interface consists of three parts. The data retrieval part that enables the SaaS applications to get
the required data from the system. Data propagation to the system which enables the propagation of
data from the SaaS applications to the system. The final part is the data propagation to the SaaS
application which enables the propagation from the SaaS application to the system. The described
functionality is implemented for the following entities: User, Customer, License, Additional parameter
and Customer product.

2.3.1.Entities
Entities include the data that is being synced between the system and the SaaS applications. They do
not represent all of the data on those entities on both sides but only the data that is common too both
sides.

2.3.1.1. User
User represents a collection of basic information on a user who uses the system.

Parameter Type Description

Name String First name of the user.

LastName String Last name of the user.

Email String User primary email.

Phone String User phone number.

Mobile String User mobile phone number.

Fax String User fax number.

AddressStreet String User street address.

ZipCode Int Zip code of user city address

User city address (can't be changed directly – it is

AddressCity String
changed by changing the zip code).

ID of the customer with which the user is associated

CustomerID Int?
with.

GUID String GUID of the user

15
 2.3.1.2. Customer
Customer represents the basic data on the customer. Customer has users associated to it. User can be
associated to only one customer.

Parameter Type Description

ID Int ID of the customer

Name String Customer name

Name of the contact person associated with the

ContactPersonFirstName String
customer.

Last name of the contact person associated with the

ContactPersonLastName String
customer.

Primary email of the contact person associated with

ContactEmail String
the customer.

Phone number of the contact person associated with

ContactPhone String
the customer.

Mobile phone number of the contact person

ContactMobile String
associated with the customer.

ZipCode Int Zip code of customer city address

Customer city address (can't be changed directly – it

AddressCity String
is changed by changing the zip code).

AddressStreet String Customer street address.

OIB String National identification number.

2.3.1.3. Licence
Licence represents a service assigned to the user. User with an assigned license can use the assigned
service. Unassigned licenses can be assigned to users. Number of licenses can change. Also users of
the license can change.

Parameter Type Description

RoleID Int? ID of the role

RoleName String Name of the role

IsExcluded Bool? Describes if the user can be assigned only this role.

16
 IsActive Bool Describes if the license can be assigned to a user.

BillingProductID Int? ID of the billing details regarding the license.

HasUniqueIdentifier String Describes if the license is associated to a service.

InUse Bool Describes if the license is currently assigned to a user.

AssignedUserGUID String GUID of the user to whom the license is assigned to.

2.3.1.4. Additional Parameter

Additional parameter represents a value that specifies the functionality provided to the user. It makes
the application more adjustable to the user’s requirements.

Parameter Type Description

ID Int ID of the additional parameter.

Name String Name of the additional parameter.

Value String Value of the additional parameter.

ID of the billing details regarding the additional

billingProductID Int?
parameter.

2.3.1.5. Product
Product represents the value of the service offered by the application to a customer and his users.

Parameter Type Description

AppID Int? ID of the application that is providing the product.

CustomerID Int? ID of the customer that is using the product.

ApplicationProduct Int? Size of the product.

2.3.2.Web services

2.3.2.1. GetData

The retrieval of data is done by invoking the method GetData (Result GetData(DataRequest request) with
the desired request. Based on the received request a response will be sent. All requests extend the base

17
class DataRequest. The response that will be received is of type DataResult that extends the class
Result.

Result

Parameter Type Description

Indicates if the request was successfully completed

Status Bool (Status = true) of if it resulted in an error (Status =
false)

Message String Error details if it occurred.

timestamp Datetime Timestamp of the request

DataResult

Parameter Type Description

Request DataRequest Request that is sent.

If the returned result has the Status set to true then the request was successfully processed. When the
request is successfully processed then a Result with the data requested is sent. All results sent extend
the class Result. For each request there is a corresponding result sent back. For example for the request
UserRequest a corresponding UsersResult is returned with the Users that match the request
parameters.

2.3.2.2. Gathering user data

To get the desired user data a request of type UserRequest needs to be sent. If the request is successful
then the Result will be of type UsersResult if an error occurred then the result will be of type
DataResult.

If the GUID is defined then the User with the requested GUID is returned. If the CustomerID is
defined then all Users of that customer are returned. If both the GUID and the CustomerID are defined
only the User with the corresponding GUID is returned.

18
UserRequest

Parameter Type Description

CustomerID Int? The ID of the customer whose users will be returned.

GUID String GUID of the user that will be returned.

UserResponse

Parameter Type Description

Users List<User> Users that meet the request parameters.

2.3.2.3. Gathering Customer Data

To get the desired customer data a request of type CustomersRequest needs to be sent. If the request is
successful then the Result will be of type CustomersResult if an error occurred then the result will be
of type DataResult.

If the CustomerID is not defined then all the Customers that use the application are returned. If the
CustomerID is defined then only the details of that customer are returned.

CustomersRequest
Parameter Type Description

AppID Int ID of the application that is requesting the data.

CustomerID Int? ID of the customer.

CustomersResult
Parameter Type Description

Customers List<Customer> Customers that meet the request parameters.

2.3.2.4. Gathering License data

19
To get the desired license data a request of type LicenceRequest needs to be sent. If the request is
successful then the Result will be of type LicenceResult if an error occurred then the result will be of
type DataResult.

If the UserGUID is defined then all of the licenses (only the ID-s) of the defined application that are
assigned to that user are returned. If the CustomerID is defined then all of the licenses (only the ID-s)
that are bought by the defined customer are returned. If both the UserGUID and the CustomerID are
defined then only the licenses that are assigned to the defined user are returned.

LicenceRequest
Parameter Type Description

UserGUID String GUID of the user.

AppID Int ID of the application that is sending the request.

CustomerID Int? ID of the customer.

LicenceResult
Parameter Type Description

Data List<Int> ID-s of the licenses that meet the request parameters.

To get the desired details of a license then a LicenceDetailsRequest needs to be sent. A corresponding
LicenceDetailsResult will be returned.

LicenceDetailsRequest
Parameter Type Description

LicenseID Int ID of the license whose details are requested.

LicenceDetailsResult
Parameter Type Description

Licence Licence Details of the license.

2.3.2.5. Gather Additional Parameter data

To get the desired additional parameters data a request of type AdditionalParametersRequest needs to
be sent. If the request is successful then the Result will be of type AdditionalParametersResult if an
error occurred then the result will be of type DataResult.

20
If AppID is defined then the Additional Parameters of the application are returned. If the GUID is
defined (along with the AppID) then the Additional Parameters of that user are returned. If the
CustomerID is defined (along with the AppID) then the Additional Parameters of the CustomerID are
returned. If both CustomerID and UserGUID are defined then only the user Additional Parameters are
returned.

AdditionalParametersRequest
Parameter Type Description

GUID String GUID of a user.

AppID Int ID of the application that is sending the request.

CustomerID Int? ID of a customer.

AdditionalParametersResult
Parameter Type Description

Additional parameters that meet the request

Data List<AdditionalParameter>
parameters.

2.3.2.6. Gathering product data

To get the desired product data a request of type ProductRequest needs to be sent. If the request is
successful then the Result will be of type ProductResult if an error occurred then the result will be of
type DataResult.

ProductRequest
Parameter Type Description

AppID Int ID of the application that is sending the request.

CustomerID Int ID of a customer.

ProductResult
Parameter Type Description

Product Product Details of the product.

21
 2.3.3.Data propagation

The propagation of data from the SaaS application to the system is done by invoking the method
PropagateData (Result PropagateData(PropagationRequest request)). The method accepts the requests of base
type PropagationRequest and returns the result of type PropagationResult. The data in the request is
propagated to the system. In most requests the returned result is an indicator if the request was
successful but when adding new values additional information is sent in the response.

PropagationRequest

Parameter Type Description

ResellerID Int ID of the reseller.

PropagationResult
Parameter Type Description

Request PropagationRequest Request for which this is the response.

2.3.3.1. User data propagation

SaaS applications can add new users and change existing ones.

New user is added by calling the method PropagateData with the request of type
NewUserPropagationRequest. If the request was successfully processed a response of type
NewUserPropagationResult will be returned. Also an email will be sent to the user.

NewUserPropagationRequest
Parameter Type Description

User User User to be added to the system.

ResellerID Int ID of the reseller.

NewUserPropagationResult
Parameter Type Description

GUID String GUID of the added user

22
 Username String Username of the added user.

Editing an existing user is done by calling the method PropagateData with the request of type
EditUserPropagationRequest. Only the values that are defined (are not null or empty) will be changed.
A response of type PropagationResult is returned.

EditUserPropagationRequest
Parameter Type Description

User User User to be changed.

ResellerID Int ID of the reseller

2.3.3.2. Customer data propagation

SaaS application can add new customers and change existing ones.

To add a new customer the PropagateData method must be called with the
NewCustomerPropagationRequest. A response of type NewCustomerPropagationResult is returned.

NewCustomerPropagationRequest
Parameter Type Description

Customer Customer Customer to be added.

AppID Int ID of the application sending the request.

IndetificationNumber String National identification number.

AdminUserName String Username of the admin user for the created customer.

MarketSegment String Market segment.

ResellerID Int ID of the reseller.

NewCustomerPropagationResult
Parameter Type Description

Username of the administrator for the added

Username String
customer.

23
To update an existing customer the PropagateData method must be called with the
EditCustomerPropagationRequest. Only the values that are not null or empty will be changed. A
response of type PropagationResult is returned.

EditCustomerPropagationRequest

Parameter Type Description

Customer Customer Customer to be added.

AppID Int ID of the application sending the request.

ResellerID Int ID of the reseller.

2.3.3.3. License data propagation

SaaS application can suspend and activate temporary user licenses, remove user from a license and
update user licenses. All activates are done by calling the PropagateData method and receiving a
response of type Result.

To suspend a user license the PropagateData method must be called with the request of type
SuspendUserLicencePropagationRequest. To be able to suspend a license the license needs be a
temporary license. If the UserLicenseID is defined then user is removed from that license. If
ApplicationID and UserGUID are defined then all licenses assigned to that user are suspended. A
response of type PropagationResult is returned.

SuspendUserLicencePropagationRequest
Parameter Type Description

UserLicenseID Int? ID of the license to suspend.

ApplicationID Int? ID of the application sending the request.

UserGUID String GUID of the user for whom to suspend all licenses.

ResellerID Int ID of the reseller.

To reactivate a user license the PropagateData method must be called with the request of type
ActivateUserLicensePropagationRequest. If the LicenseID is defined then the license with that ID is

24
reactivated. If the AppID and UserGUID are defined then all licenses of that user are reactivated. A
response of type PropagationResult is returned.

ActivateUserLicensePropagationRequest
Parameter Type Description

LicenseID Int? ID of the license to suspend.

AppID Int? ID of the application sending the request.

UserGUID String GUID of the user for whom to suspend all licenses.

ResellerID Int ID of the reseller.

To update a user license the method PropagateData must be called with the request of type
UpdateUserLicencePropagationRequest. If the ApplicationID, UserGUID and Licences are defined
then the current user licenses are updated with the licenses that are defined. A response of type
PropagationResult is returned.

UpdateUserLicencePropagationRequest
Parameter Type Description

Licences List<Licenses> List of licenses to update.

ApplicationID Int ID of the application sending the request.

UserGUID String GUID of the user for whom to update the licenses.

ResellerID Int ID of the reseller.

To remove a user license the method PropagateData must be called with the request of type
RemoveUserLicencesRequest. If the AppID and UserGUID are defined then all the licenses assigned
to the user are removed from him. If the RoleID is also defined then only the user licenses of the
defined RoleID are removed. A response of type PropagationResult is returned.

RemoveUserLicencesRequest
Parameter Type Description

RoleID Int? ID of the role to remove.

AppID Int ID of the application sending the request.

UserGUID String GUID of the user for whom to remove the license.

25
 ResellerID Int ID of the reseller.

2.3.3.4. Additional parameters data propagation

SaaS application can update the additional parameters by calling the PropagateData method with the
type UpdateAdditionalParametersPropagationRequest. If the ApplicationID is defined then the
application additional parameters are updated. If the UserGUID is defined with the ApplicationID then
the user additional parameters are updated. A response of PropagationResult is returned.

UpdateAdditionalParametersPropagationRequest
Parameter Type Description

AdditionalParameters List<AdditionalParameter> New additional parameters to store.

ApplicationID Int ID of the application sending the request.

GUID of the user for whom to update the

UserGUID String
additional parameters.

ResellerID Int ID of the reseller.

2.3.3.5. Product data propagation

SaaS application can update the value of the product by calling the PropagateData method with the
request with the type UpdateApplicationProductPropagationRequest. If the AppID and CustomerID
are defined then the ApplicationProduct is updated. A response of type PropagationResult is returned.

UpdateApplicationProductPropagationRequest
Parameter Type Description

Product Product Product to update.

ResellerID Int ID of the reseller.

2.3.4.Data propagation to SaaS

26
Data propagation to SaaS is done by implementing the Observer design patter. The registration of the
observer is done by invoking the RegisterObserver method (Result
RegisterObserver(RegisterObserverRequest request)). The method accepts a parameter of type
RegisterObsrverRequest and returns a response of type RegisterObserverResult. After the application
is registered as an observer to an entity, each time the entity is changed the application is notified. To
stop receiving updates on the entity the application must invoke the method UnregisterObserver( Result
UnregisterObserver(UnregisterObserverRequest request)).
The described functionality may be used to observe entities User and Customer. Entities Licenses,
Additional parameters and Application products are updated by notifying the applications associated
to the entities directly.

RegisterObsrverRequest
Parameter Type Description

ID of the application that is sending the

ApplicationID Int
request.

ResellerID Int ID of the reseller.

RegisterObserverResult
Parameter Type Description

Request RegisterObserverRequest Request to which this is the response.

ResellerID Int ID of the reseller.

Propagate User data to SaaS

To register application as an observer to the entity user the RegisterObserver method must be called
with the request type RegisterUserObserverRequest. If the ApplicationID and UserGUID are defined
then the application is registered to observe the user.

RegisterUserObserverRequest
Parameter Type Description

ID of the application that is sending the

ApplicationID Int
request.

UserGUID String GUID of the user to start observing.

ResellerID Int ID of the reseller.

27
To stop observing the user entity the method UnregisterObserver with the request type
UnregisterUserObserverRequest must be called. If the ApplicationID and UserGUID are defined then
the application will no longer receive updates when the user entity is changed.

UnregisterUserObserverRequest
Parameter Type Description

ID of the application that is sending the

ApplicationID Int
request.

UserGUID String GUID of the user to stop observing.

ResellerID Int ID of the reseller.

Propagate Customer data to SaaS

To register application as an observer to the entity customer the RegisterObserver method must be
called with the request type RegisterCustromerObserverRequest. If the ApplicationID and UserGUID
are defined then the application is registered to observe the user.

RegisterCustromerObserverRequest
Parameter Type Description

ID of the application that is sending the

ApplicationID Int
request.

CustomerID Int ID of the Customer to start observing.

ResellerID Int ID of the reseller.

To stop observing the customer entity the method UnregisterObserver with the request type
UnregisterCustomerObserverRequest must be called. If the ApplicationID and CustomerID are
defined then the application will no longer receive updates when the customer entity is changed.

UnregisterCustomerObserverRequest
Parameter Type Description

ID of the application that is sending the

ApplicationID Int
request.

CustomerID Int ID of the Customer to stop observing.

ResellerID Int ID of the reseller.

28
3. User Login into SaaS Application
ComProvis SSO portal supports exchanging authentication and authorization data in accordance to
SAML standard. SAML standard is preferred method for single sign-on functionality.

3.1. User Authentication using SAML

While preparing for the first user login in accordance to SAML, ComProvis creates SAML response to
SaaS application SAML URL that was provided at application creation. If empty response was sent,
current user session must be terminated.

After certificates are verified, within ComProvis SAML response, user is presented with local SSO
identity (GUID). This means that ssoID field is sent within SAML attributes list (see below predefined
list). It can be used for further work of the user, for maintaining established session active.

For custom logout from SaaS application, SaaS application must redirect to

http://www.portal.com/logout.aspx

SAML 2.0 is used for SSO authentication.

HTTPRedirect is used for binding. HTTPPost can also be used, but in that case it will not be
automatically returned to the SaaS portal.

29
Metadata is not necessary if it will be only one certificate by HT. Attributes that will be sent are:

 Username;
 FirstName;
 LastName;
 ssoID;
 languageID.

SAML authentication procedure

User logs in to ComProvisPortal

User clicks on desired SaaS application

ComProvisPortal creates authentication response. Response is signed XML that is converted into 64
based string.

30
SaaS application needs to check if signature is valid.

Example of signature validation in C#

31
If ISV application needs to check it must send request for authentication to ComProvisPortal

Endpoint where ISV sends SAML request is:

http://www.portal.hr/SSO/SingleSignOnServiceOut.aspx

Request must be XML that is converted to based 64 string. SaaS application will get response same as
if user clicked SaaS application icon in ComProvisPortal.

ComProvis team recommends following commercial libraries for development of SAML

communication:

http://www.atp-inc.net/saml.net/

http://www.componentspace.com/saml

Free development licenses, but payable if used for production can be obtained from Microsoft.

32