...
The solution will provide several options for showing the designer as part of SDC. The communication between the SDC and the designers on the UI side will be event based and on the back-end side it will be based on the external API’s SDC exposes.
Designer Availability
As part of the integration between SDC and the different plugins, we uphold the concept that SDC can function without any of the different plugins.
...
The diagram describes the discovery process from the point when a user access SDC.
...
2.4 Rest endpoint
2.4.1 Request (GET)
...
https://{serverRoot}/sdc1/config/ui/plugins
Name | Description |
serverRoot | Server base URL : hostname+port path Hostname shall contain the FQDN of the SDC FE server or vip |
2.4.1.1 Special Request Headers
Header Name | Mandatory? | Description |
X-ECOMP-RequestID | N | According to the general ECOMP agreement the "X-ECOMP-RequestID" header with the transaction UUID should be published by ECOMP component calling an exposed by other ECOMP component API in order to make possible the transaction traceability across ECOMP. If it is not sent it will be automatically generated by SDC on request receipt. |
Accept | N | Determines the format of the body of the response. Valid values are : “application/json” |
2.4.1.2 Request Body
...
2.4.2.1 Special Response Headers
Header Name | Description |
Content-Type | Determines the format of the response body. Valid value is : “application/json” |
Content-Length | Length of the response body |
2.4.2.2 Response body
Response body is returned as JSON object (Content-Type: application/json).
Parameter Name | Parameter Type | Description |
List of objects | A List describing each plugin location and configuration for the UI integration. |
Plugin list:
Parameter Name | Parameter Type | Description |
pluginId | String | The id of the plugin |
pluginDiscoveryUrl | String | The URL which will be used to check the plugin availability |
pluginSourceUrl | String | The URL which will be used to load the plugin page |
pluginDisplayOptions | Map of objects | An map of object representing the plugin options, the currently supported options are tab and context. |
isOnline | Boolean | This value indicates to the SDC UI if the plugin is currently online. If the plugin is down an attempt to open the plugin will result in an error screen. |
PluginDisplayOptions tab:
Parameter Name | Parameter Type | Description |
displayName | String | The name to show for this plugin in the tab area. |
displayRoles | List of string | The user roles for which this plugin will be shown. Supported roles are: ADMIN, DESIGNER, TESTER, OPS, GOVERNOR |
PluginDisplayOptions context:
Parameter Name | Parameter Type | Description |
displayName | String | The name to show for this plugin in the context area. |
displayRoles | List of string | The user roles for which this plugin will be shown. Supported roles are: ADMIN, DESIGNER, TESTER, OPS, GOVERNOR. |
displayContext | List of string | A list of contexts in which the plugin will be shown: VFC, VL, CP, VF, PNF, SERVICE. |
2.4.2.3 Response Sample
...
2.4.2.4 HTTP response codes
Response code | Service/Policy Exception | Reason /Description |
200 | n/a | plugin information is returned. |
...
2.5 Fe server configuration definition
...
The configuration allows SDC to control where the plugin UI will be displayed, tab mode or context mode.
2.5.1 Configuration fields
2.5.1 Configuration fields
The designer configuration is located The designer configuration is located under {app base}/config/catalog-fe/plugin-configuration.yaml
Field | Type | Description |
connectionTimeout |
Integer | This is the number of milliseconds, for the head request to wait for a response from the plugin. | |
pluginsList | List of objects | A list of plugins’s configurations. |
pluginId | String | The name of the plugin. |
pluginHost | String | The host where the designer is located. |
pluginSourceUrl | String | The plugin URL passed to the UI to retrieve the page. |
pluginDiscoveryUrl | String | The plugin URL used for the availability check. |
pluginStateUrl | String | The plugin state for UI router. |
pluginerDisplayOptions | String | We currently support two work modes for plugins:
displayName: "Workflow Designer" displayRole: [“TESTER”]
displayName: "monitor" displayRole: [“TESTER”] displayContext: ["VF", "SERVICE"] |
...
2.5.2 Example
pluginsList:
...
displayRoles: ["DESIGNER", "TESTER"]
connectionTimeout: 1000
...
2.6 Health Check Integration - TBD
...
...
UI Integration
SDC need to onboard plugins in a way that will be decoupled from the SDC UI implication.
...
The communication between the hosted and the hosting applications needs to be language agnostic and extendable to allow the addition of more functionality and logic on top of this communication method.
...
Solution
The solution chosen was to use IFrame to host the plugins. The iFrame provides a decupled window that can load any UI content as a separate window. The window contains the Html JS and CSS in such a way that they will not interfere between with the hosing hosting and hosted application.
The communication between the application will be done based on events.
SDC will hold an event bus in the application, we will define events for operations done in SDC that the plugins need to be notified about. On each defined operation, an event will be placed on the event bus for the plugins to consume.
...
Supported use cases
Based on the current plugin in SDC we identified two main use cases of how the plugins are used. The first is the presentation of the plugin as a tab on SDC top bar, this mode is used for Plugin that wants to design an object that can later be reused across different SDC elements, the second use case is opening the plugin as part of the service or resource where the designer will model objects in the context and using the properties of that resource/service.
...
Standalone use case
...
Use
...
in a context of a service or resource
...
Iframe initiation
When the iframe is initiated SDC pass initial information to the iframe Iframe so that the correct plugin screen will be presented. The information will assist the iframe to define the context in which it is currently being opened.
The information will be passed as part of the designer url URL as a query permparam.
...
Plugin tab mod
In case of a TAB mode, SDC will pass the logged in user.
Param | Description |
userId | The id of the user logged into SDC |
userRole | The role of the connected user, options ADMIN, DESIGNER, TESTER, OPS, GOVERNOR. |
displayType | The type of view the plugin is opened in tab/context. |
parentUrl | The URL of the SDC the plugin is opened in. used to subscribe to the event bus in SDC. |
eventsClientId | The name with which the plugin needs to register with to the event bus. |
...
Example
http://<IP>:<PORT>/designer?userId=cs0008&userRole=DESIGNER&displayType=tab&parentUrl=http://localhost:9000/&eventsClientId=plugin
...
Plugin context mod
In case of context mod SDC will pass the following info:
Parm | Description |
userId | The id of the user logged into SDC. |
userRole | The role of the connected user, options ADMIN, DESIGNER, TESTER, OPS, GOVERNOR. |
displayType | The type of view the plugin is opened in tab/context. |
contextType | The type of the context where the plugin is opened: VF/CP/VL/VFC/SERVICE |
uuid | Unique id of the context the designer is opened in. |
lifecycleState | The state the context /resource or service are currently in: CERTIFIED/ NOT_CERTIFIED_CHECKIN/ NOT_CERTIFIED_CHECKOUT; |
isOwner | A Boolean value describing if the logged user is the owner/lastUpdator of the resource/service. |
version | The version of the item displayed. |
parentUrl | The URL of the SDC the plugin is opened in. used to subscribe to the event bus in SDC. |
eventsClientId | The name with which the plugin needs to register with to the event bus. |
...
Example
http://<IP>:<PORT>/designer?userId=cs0008&userRole=DESIGNER&displayType=context&contextType=VF&uuid= a21af8a1daa948f78e30f9b269a253ba&lifecycleState= NOT_CERTIFIED_CHECKOUT&isOwner=true&version=1.0&&parentUrl=http://localhost:9000/&eventsClientId=plugin
...
UI communication
UI communication is based on an event processing. SDC creates an event bus, any plugin in the system and SDC itself will subscribe to this event bus. Events will be generated according to pre-defined events in the system. Any plugin can subscribe to events that are relevant to them.
The plugin can be enhanced so that in the future different plugins can communicate between them using the event bus. The event bus will use java script javascript for its implementation so that any UI language used will be able to use it.
SDC provides a mechanism to define if SDC needs there is a need to wait for a response from a plugin or not.
...
plugin or not.
SDC-pubsub library
befor you can integrate with SDC you will need to add our pubsub librery intop
SDC will expose a base class in JS as part of the SDC UI project. Any plugin will be able to communicate with SDC after they instantiate this class.
The class will define a set of method that will allow the communication with SDC.
Plugin registration
SDC will expose a base class in JS as part of the SDC UI project. Any plugin will be able to communicate with SDC after they instantiate this class.
The class will define a set of method that will allow the communication with SDC.
3.5.1 BasePubSub API
Base class holding all the basic operations needed for using the event hub.
API | Description |
constractor(pluginId) | Defines the name of the plugin in the event bus. |
register(subscriberId,subscriberWindow,subscriberUrl) | adds the subscriber to the subscriber list. |
unregister(subscriberId) | remove the subscriber from the subscriber list. |
notify(eventType, eventData) | send with post message the data to all the subscriber after creating the data structure(type, actualData, originId). Returns an object with a subscribe function that receives a callback. This call back will be executed when all subscribers completed their actions regarding the event. |
on(eventCallback) | add the callback to the eventsCallbacks map. |
off(eventCallback) | removes the callback from the eventsCallback map. |
onMessage(event) | Protected method, check if the origin is present in the clients list. Executes all the callbacks from the eventsCallback map. |
3.5.2 Call back definition
...
event – The JavaScript event object that was received in the onMessage function.
3.5.3 PluginPubSub API
the client class for communicating with the hub.
API | Description |
constructor(pluginId, perentUrl,eventsToWait) | Defines the communication with the hub. PluginId: defines the id of the plugin with which it will be recognized this must corelate to the id defined in the SDC configuration. parentUrl: this is the URL of the parent pub sub hub. This is populated based on the input received in the query param. eventsToWait: this parameter is optional. This defines the events that the plugin wants SDC to wait on before continuing the flow. The regular flow only waits for the call back execution, if the event is defined here sdc will wait for the plugin to respond before continuing the flow. |
subscribe(eventsToWait) | The method allows to subscribe again after unsubscribing. eventsToWait: this parameter is optional. The method is called automatically by executing the contractor. This defines the events that the plugin wants SDC to wait on before continuing the flow. The regular flow only waits for the call back execution if the event is defined here SDC will wait for the plugin to respond before continuing the flow. |
unsubscribe() | The method is used to unsubscribe from the hub. |
...
3.5.4 EventBusService API
API | Description |
constructor() | Defines the name of the hub in the event bus. |
handlePluginRegistration(eventData, event) | Protected method, handles registration of plugins to the HUB and their un registration. |
unregister(pluginId) | Notifies that a plugin is being closed before unregistering it. |
onMessage(event) | Protected method, calls the handlePluginRegistration in case of a plugin register or unregister event while passing the event to its subscribers |
3.6 Plugin API Usage examples
...
Consider refining the import if you do not need all the SDC-UI and just add this class.
3.6.2 Plugin initialization
...
In this case SDC will continue the flow only after the ACTION_COMPLETED event is recived
Example:
eventsClientId=<received from query params>
...
PluginPubSub client = new PluginPubSub(eventsClientId, parentUrl)
Example with events to wait for:
...
PluginPubSub client = new PluginPubSub(eventsClientId, parentUrl, eventsToWaitFor)
3.6.3 Send ready event
...
In this way, new events can be easily added to the system and the event originator can be tracked.
3.7.1 Event structure
...
3.7.2 SDC generated events
Name | Type | When | Data | UI state | Description |
Window out | WINDOW_OUT | Before SDC closes plugin, The event is sent on all events below except VERSION_CHANGE and check out | none | Moves out of the plugin scope | The event is posted by SDC once the plugin window is going to be closed because of user action. |
Version change | VERSION_CHANGE | After SDC retrieves item | New item version and UUID | The plugin is displayed on screen. | The event is posted by SDC once context version is changed by the user. |
Check in | CHECK_IN | Before SDC closes plugin | none | SDC opens the catalog. | The event is posted by SDC once the context is being checked by the user. |
Check out | CHECK_OUT | After SDC successful checkout the item | New item version and UUID | The plugin is displayed on screen. | The event is posted by SDC once the context is being check out by the user. |
Submit for testing | SUBMIT_FOR_TESTING | Before submitting for testing is executed | none | SDC opens the catalog. | The event is posted by SDC once the context is being submitted for testing by the user. |
Undo check out | UNDO_CHECK_OUT | After SDC executed the undo check out. | item version and UUID | SDC opens the catalog. | The event is posted by SDC once the context is being undone by the user. |
3.7.2.1 Window out event example
...
type:WINDOW_OUT
origion:sdc-hub
data:
}
3.7.2.2 Version change even example
...
uuid: a21af8a1daa948f78e30f9b269a253ba ,
version:1.1
}
}
...
3.7.3 Designer events
Name | Type | Description |
Ready | READY | The event is posted by the plugin once it is ready. |
Action completed | ACTION_COMPLETED | The event is sent by the plugin after receiving an event from SDC to notify the event passed to the plugin has be completed and SDC can continue its flow. |
3.7.4 Ready event example
...
The library allows the different designers to align their style to the SDC to create a single look and feel.
The library is located here: https://github.com/onap-sdc/sdc-ui
3.10 SDC Designer infra structure
...
3.10.1.1 SDC external API guide
...
3.10.2 SDC persistency layer TBD
4 Appendix A – References
...
4.1 SDC external API’s
...
https://wiki.onap.org/display/DW/Consumer+creation