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
Make test request
Configure Settings (Authentication Info)
Register your 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.
Available End Points
The actions that should covered by integration service’s end points are separated in 4 categories:
Optionally, in case a service provider wants to deliver users administration functionality, the following 2 categories should also be covered:
User Services Management
A brief description of the end points of each category and their scope are available in the following table.
Get Setup Fields
Called to retrieve the settings that should be configured in order to communicate with the external system
Called to retrieve the info that should be collected in order to provision a user/customer to the external system
Called in order to create/update a user/customer to the external system
Account Is Reseller
Called in order to check if a user/customer is a reseller for the external system
Called in order to delete a user/customer from the external system
Called in order to check whether a Cloud BSS Account matches an existing user/customer from the external system.
Called in order to create a subscription to the external system
Called in order to update a subscription to the external system
Called in order to activate a subscription to the external system
Called in order to suspend a subscription to the external system
Called in order to cancel a subscription to the external system
Called in order to create an addon for a subscription to the external system
Called in order to update an addon of a subscription to the external system
Called in order to cancel an addon of a subscription to the external system
Called in order to get details for a specific customer in the external system
Called in order to get the users available for a specific user/customer in the external system
Called in order to get details of a specific user from the external system
Called in order to create a new user to the external system
Called in order to update the info of a user to the external system
Called in order to delete a user to the external system
Called in order to disable a user to the external system
Called in order to activate a user to the external system
Called in order to deprovision a user to the external system
Called in order to provision a user to the external system
User Reset Password
Called in order to reset the password of user to the external system
User Services Management
Get User Services
Called in order to get the services available for a specific user and their status to the external system
Add User Service
Called in order to assign a service to a specific user to the external system
Remove User Service
Called in order to deassign a service from a specific user to the external system
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.
Testing the End Points
By selecting action next to each point, can be used to trigger a call to the endpoint by simulating a provisioning action for a functional 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 withIsTest='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.
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.
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.
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'.