Previous topic

Resource Query Language

Next topic

Navigation

DOCUMENTATION
Last updated 17-Jul-2017

Frontend

Integration with Odin Automation Control Panels

Odin Automation contains different types of accounts: the provider, resellers, and customers. A customer can have a number of end-users, known as service users, who are consumers of resources. In addition, Odin Service Automation allows managing its two main parts, Operations Automation and Business Automation, by using specific control panels. APS is integrated with all types of Odin Service Automation control panels:

  • Provider Control Panel (PCP) allows the provider’s staff (administrators) to manage the provider’s system configuration, applications, and application global resources.
  • Reseller Control Panel (RCP) is pretty much similar to the PCP and is limited with access to system configuration and system-wide resources.
  • Customer Control Panel (CCP) CCP v1 or CCP v2 is used by customers’ staff (administrators) to manage resources provisioned for the customer’s organization.
  • Service User Control Panel, also known as MyCP, MyCP v1 or MyCP v2 allows service users to manage the resources assigned to them.

Platform, APS, and Control Panel Versions

Starting with APS version 2.2 (Odin Service Automation version 7.0), it is possible to switch the system to using one of CCP/MyCP versions, either CCP v1 or CCP v2.

Pay attention to Odin Automation Platform-APS-CP version mapping:

Odin Automation Platform 5.5 6.0 7.0
APS 2.0 2.1 2.2
PCP/RCP version
CCP/MyCP version
[1]
[1]
[1]
[1]
[1]
[1,2]

Note

[1,2] means you can switch the system to one of the versions.

Developers of APS applications can take the following advantages of switching to CCP v2:

  • Getting highly customizable CCP and MyCP based on the APS technology and open source bootstrap3 layout
  • Using single page (IFrame) for many or all views of an application UI
  • Support for direct links that can be bookmarked
  • Responsiveness based on a single page with async support
  • Access via mobile devices based on open-source bootstrap3 layout
  • Notifications with websocket and longpoll support
  • No need in frame sets
  • Using additional widgets
  • Backward compatibility with APS applications developed for the previous generation of Odin Service Automation control panels.

On an Odin Service Automation platform that supports both CCP versions, you can switch CCP/MyCP to version 2 and backward to version 1 on the per customer basis:

  1. Navigate to System > Settings, and in the Control Panels section click Enable/Disable CCP v2.
  2. Switch to the Customers tab.
  3. Select one or several customers and assign the required version by clicking respectively Enable CCP v1 or Enable CCP v2.
../_images/ccp-enable.png

From this screen, you can impersonate a customer and go directly to CCP by clicking on the respective icon in the Actions column.

Refer to the Control Panel Version 2 document for more details about UI development in the CCP v2 environment.

Introduction to APS User Interface

APS provides methods and tools for developing custom APS user interface (APS UI) that can be plugged into different types of control panels in Odin Automation. APS JavaScript Software Development Kit (APS JS SDK) exposes a lot of JS objects that simplify the development process and make APS packages robust to hosting platform updates.

The architecture has the following key features:

  • All APS presentation logic is processed on the client side. There is no HTML rendering on the server side. A screen is rendered by a view component that is an HTML code with JS.
  • Navigation is described declaratively in the APS metadata and handled by a control panel.
  • All data is transferred to and from backend using REST requests in JSON format.
  • AJAX technology is used for asynchronous communications and for unloading the backend server from building web pages.
  • The backend server implements provisioning and security logic.
  • HTML IFrame is used to isolate a page inside its own container.

If you need to develop an APS UI, make sure that you consider the following possible options:

  1. We recommend you to use the APS JS SDK without any modifications, as it provides the following benefits for you:
    • It simplifies substantially the development of views in most cases.
    • Your custom UI can inherit HTML styles from control panels, i.e. a control panel will be able to apply its style skins to this UI.
    • It guarantees backward-compatibility with any future updates in the APS JS SDK modules.
  2. Use your own JS controls, CSS, markup, etc. without using APS JS SDK. Such a UI will also remain backward-compatible with possible future updates in the APS JS SDK modules, but it will not be able to accept skins of a control panel. That is why this option is not recommended.
  3. Use the APS JS SDK, but modify the rendered HTML. We strongly caution you against using this option because future updates in the APS JS SDK modules may “break” such a custom UI.

Warning

Please be aware that the applications where option 3 is chosen are not officially supported by APS.

You may use option 2 on your own but be aware that the APS support team will not accept requests for issues connected with 3rd party JS modules.

Note

For the list of certification restrictions on UI, please refer to certification requirements.

For the formal definitions of APS JS SDK modules refer to APS UI Runtime.

APS JavaScript SDK

Overview

APS JS SDK is a JavaScript library that helps developers to build custom application UI in a CP:

  • Arrange navigation between views by means of the Navigation API
  • Build views by means of Widgets
  • Bind widgets with the object model to reflect model changes in a view by means of the Model Controls

Intercommunication between a CP and an application IFrame is a two-way asynchronous intercommunication is communication. Each side can initiate intercommunication:

  • The application can call the control panel to indicate that something should be done with the CP screen:
    • Navigate to another view, for example, a user selects another resource.
    • Indicate the readiness to go to another view, for example, after saving data in the edit view or when ready to return data from the select view.
    • Communicate with controls, e.g. indicate that the Select button can be activated.
  • The control panel tells the application that something has happened outside the application IFrame:
    • The user clicks on a navigation control.

For example, if the user clicks on the Submit button:

  1. The CP propagates the event into the IFrame.
  2. The onSubmit handler in the view catches this event.
  3. The handler can do some internal application operations, then request CP to activate another view by calling aps.apsc.gotoView(), or cancel processing by calling aps.apsc.cancelProcessing().

Technology Stack

APS JS SDK is based on the following technologies:

  • DOJO JS framework for widgets as an MVC/MVVM implementation
  • HTML4/5 as the base markup language
  • JSON as the primary intercommunication data format
  • OpenAJAX Hub as an iframe secured communication mechanism in JS framework

API

APS JS SDK consists of the following API sets.

  • Navigation API allows communication between a view and the control panel.
    • gotoView() allows a view to switch to another view.
    • onSubmit(), onCancel() and other appropriate event handlers are used by views to handle navigation buttons.
  • Model API is needed for 2-way synchronization between widgets and data model.
    • Model is a data model for APS resources
    • Store sends/receives data over the APS REST API
  • View API set is used to create and use widgets in views.
    • Grid with pagination, sorting, filtering: aps/Grid
    • Input: TextBox, Select, Slider, CheckBox, etc.
    • Output: EnhancedList, Gauge, Message, ProgressBar, Radio, etc.
    • Control: Button, Toolbar, etc.

JS SDK Basics

  • The framework is modular, i.e. modules are in the Asynchronous Module Definition (AMD) format used by require.js, dojo, and other. UI controls are “thick”, i.e. they have a state and own HTML renderer.
  • A model is a special representation of JS objects, including APS resources.
  • Each property change of a widget can be listened.
  • Each property change of a widget can be bound to a data model.
  • A store is a way to operate with backend (get, post, put, delete) asynchronously.

To support modules, use the require() and define() functions, for example, refer to http://dojotoolkit.org/documentation/tutorials/1.10/modules/ for more details. To use APS JS SDK modules, you should require them by using the require([]) or define([]) function followed by the main callback function in your application.

Note

The order of arguments in the callback function MUST MATCH the order of modules declared as an array in the require([]) or define([]) function. So this is CORRECT:

require(["dojo/parser", "aps/Memory", "aps/ready!"], function(parser, Memory) {

Warning

There is a common mistake we want to warn you - placement of arguments of the callback function in wrong positions. Let us look at an example of INCORRECT usage:

require(["dojo/parser", "aps/Memory", "aps/ready!"], function(Memory, parser) {

Take a look at the order of modules in the first argument (array) and the order of arguments in the callback function. They DON’T match: the dojo/parser is exposed as the Memory variable and the aps/Memory as the parser variable. This is INCORRECT.