Article How do I customize my community in an upgrade-safe way?

Verint Community is designed to be customized visually and functionally. With a commitment to platform APIs and scheduled API obsolescence, customizations can be made with confidence that they will continue to function through Verint Community upgrades.

When upgrading Verint Community, the upgrade takes two phases:

  • Phase 1: Platform Upgrade. The platform upgrade occurs when the new version of the software is installed, the database is upgraded, and the community is first accessed. At the end of this phase, all supported customizations (customizations using the Verint Community User Interface or supported APIs ) will remain as they did prior to the platform upgrade. The public facing community will look and function as it did prior to the upgrade. The underlying platform, management and administration user interfaces, and APIs are immediately available. New functionality, however, may not be fully exposed by the pre-upgrade public-facing user interface if the user interface requires updates to expose new features and, in that situation, administrators can choose to include updates in phase 2.

  • Phase 2: User Interface and Customization Upgrade. After the platform is upgraded, community administrators will receive system notifications related to any opt-in upgrades. It is not necessary to accept any of these changes, but the changes are presented to allow administrators to select optional updates to get new features or bug fixes. If the newly installed version of Verint Community includes updates to the default theme or default widgets, the user interface upgrade will be presented and can be used to review theme and widget updates. If the newly installed version of Verint Community includes updates to default automations or embeddables, a notification will be presented to review those updates within Automation Studio or Embeddable Studio, respectively. 

While customizations will continue to work through upgrades, it is helpful to be aware of the maintenance process and cost associated to incorporating potential new Verint Community features and bug fixes with customizations. That maintenance cost varies based on the type of customizations made. This article discusses the different types of customizations and their ongoing maintenance processes and costs:

Theme Configuration / Page Layout / Widget Placement and Configuration

Maintenance Cost: Low
Maintainer: Community/Group/Application Manager
Skills Required: Familiarity with theme configuration and page editing 

Verint Community enables community managers, group owners, and blog owners to customize the user experience using selectable options and dragging/dropping of user interface widgets . These options are exposed through the Manage Theme menu in the contextual management panel .

Implementation

Theme configuration, page layout, widget placement, and widget configuration changes are all made through the Manage Theme menu in the contextual management panel by going to the Pencil icon and choosing Manage Theme (the exact text will change contextually, for example Manage Site Theme for site theme pages, Manage Group Theme for group theme pages, etc). For more information on themes, see What is a theme? 

Maintenance

When Verint Community is upgraded, the user interface is left as-is and a system notification is provided to administrators to allow them to review user interface updates as part of the second phase of upgrading. Theme configuration, page layouts, widget placements, and configuration are not affected by the upgrade process or the interface review process. If no other customizations are made, updated theme and widget changes should be able to be reviewed and accepted--a visual review of identified changes in the user interface upgrade process can be performed to accept/deny changes for your community. No developer intervention is required.

Adding Stylesheets to the Theme

Maintenance Cost: Low to Medium (depending on the size/complexity of the stylesheet)
Maintainer: Developer
Skills Required: CSS, LESS, HTML, Theme Studio 

If the theme configuration options do not support the level of visual customization that your community requires, custom stylesheets can be added to the theme in Theme Studio to update global styling. Custom stylesheets make use of CSS or LESS to apply color, position, or behavior changes to the HTML that forms the UI of the community.

Implementation

Stylesheets can be added by going to Administration > Interface > Theme Studio, selecting an appropriate theme, and adding a stylesheet . 

Maintenance

On upgrade, the user interface is left as is. As part of the user interface upgrade in the second phase of upgrading, custom stylesheets are merged into the default theme updates included in the upgrade (the stylesheet doesn't need to be re-added). Because the user interface upgrade may adjust base theme styles and widget HTML, custom stylesheets should be reviewed to ensure that their style rules are still accurate with the updated HTML of the community if any theme or widget updates are accepted. This review may require updates to be made to the custom stylesheet. Custom stylesheets can be edited and reviewed in Theme Studio while previewing the user interface upgrade results and accepting changes. 

Best Practices

  • Best used for global styling
  • Styles related to individual widgets should be made as customizations to those widgets.

Creating new Automations, Embeddables, Plugins, or external integrations using REST

Maintenance Cost: Low to Medium
Maintainer: Developer
Skills Required:  Server-side Javascript , Velocity , and Automation Studio for Automations ; Server-side Javascript , Velocity , and Embeddable Studio for Embeddables ; .NET Framework for Plugins ; varies for REST-based external integrations 

Verint Community provides an upgrade-safe set of APIs and events to implement custom business logic and automations. Automations, plugins, and external integrations can make use of these APIs and events to customize the behavior of your community.

Implementation

 Automation Studio is used to create Velocity or Server-side Javascript script-based customizations directly within Verint Community by going to Administration > Automations > Automation Studio. Automations can also be installed from the Marketplace. Automations make use of the Script APIsAutomation Events and Dynamic Configuration .

 Embeddable Studio is used to create Velocity or Server-side Javascript script-based content extensions directly within Verint Community by going to Administration > Interface > Embeddable Studio. Embeddables can also be installed from the Marketplace. Embeddables make use of the Script APIsAutomation Events and Dynamic Configuration .

 Plugins are compiled .NET Framework assemblies that are physically installed onto each Verint Community application node (web servers and job servers). Plugins implement one or more plugin types and make use of the In-Process API . Plugins can implement business rules like an automation but can also implement plugin types that enable extending Verint Community to support new types of content, applications, and user interface components.

 External Integrations allow applications running outside of Verint Community (either custom applications or 3rd party tools) to interact with Verint Community using Webhooks and the REST API .

Maintenance

Automations, embeddables, plugins, and external integrations using REST access the Verint Community APIs directly. These APIs are upgrade safe. API removals are scheduled with at least a one-major-version warning and are identified in the API Documentation  as obsolete prior to removal. Whenever possible, older versions of APIs are preserved to maintain compatibility and prevent maintenance requirements. In general, these types of customizations should continue to work without modification.

For plugins that extend the Verint Community user interface, additional review may be necessary if theme and widget updates are also accepted as part of the user interface upgrade review process in the second phase of upgrading. If the plugin's implementation relied on styling from the theme or widgets, that styling may have been updated and the plugin's rendering/styling should be reviewed as well to ensure it is still compatible and any necessary updates should be applied to the plugin. 

Best Practices

  • Use only documented Verint Community platform APIs. Private APIs and undocumented APIs are not supported and may change without notice.
  • When implementing plugins requiring data storage, use a unique database. Do not interact directly with the Verint Community database as it is not supported and may change without notice.
  • When implementing embeddables, keep the embeddable's styling and client-behavior contained within the embeddable. Reliance on theme or widget styling will increase the review effort when upgrading.

Creating new Widgets

Maintenance Cost: Low to Medium
Maintainer: Developer
Skills Required:  Velocity , Server-side Javascript , HTML, JavaScript, CSS, LESS, Widget Studio 

Verint Community's user interface is built by combining multiple fragments of visual and/or functional HTML called Widgets . Many widgets are provided by Verint to form the out of the box experience and new widgets can be created by developers or installed from the Marketplace to add new content, formats, and behavior to your community.

Implementation

 Widget Studio is used to create Velocity or Server-side Javascript script-based visual customizations to Verint Community directly within Verint Community by going to Administration > Interface > Widget Studio. Widgets can also be installed from the Marketplace. Widgets make use of the Script APIs , REST API , Client-side APIs , and Dynamic Configuration .

Maintenance

Custom widgets (widgets that are not customizations of Verint Community default widgets) are not adjusted by upgrades and not affected by the user interface upgrade process in the second phase of upgrading. 

Widgets make use of Verint Community upgrade-safe APIs. API removals are scheduled with at least a one-major-version warning and are identified in the API Documentation as obsolete prior to removal. Whenever possible, older versions of APIs are preserved to maintain compatibility and prevent maintenance requirements. Custom widgets should be reviewed to ensure they don't use obsolete APIs and, if they do, the affected widgets should be updated to use newer APIs to stay upgrade safe.

If custom widgets rely on theme-defined styling and theme changes are accepted as part of the user interface upgrade process, the custom widgets should be reviewed to ensure that the expected styling is still applied and any updates should be applied to a custom stylesheet in the theme or, if specific to the widget, via a widget-specific stylesheet.

Best Practices

  • Keep widget-specific styling in the widget implementation with embedded stylesheet files

Customizing default Theme / Widgets / Automations / Embeddables

Maintenance Cost: Low to High (depending on the size/complexity of the customization)
Maintainer: Developer
Skills Required:  Velocity , Server-side Javascript , HTML, JavaScript, CSS, LESS, Theme Studio / Widget Studio / Automation Studio / Embeddable Studio 

All Verint Community default themes, widgets, and automations can be edited to adjust their implementation, layout, or functionality in Theme Studio, Widget Studio, Automation Studio, and Embeddable Studio respectively.

Implementation

Default Themes are listed and editable in Administration > Interface > Theme Studio. Default Widgets are listed and editable in Administration > Interface > Widget Studio. Default Automations are listed and editable in Administration > Automation > Automation Studio. Default Embeddables are listed and editable in Administration > Interface > Embeddable Studio. Themes, widgets, automations and embeddables are implemented using Velocity or Server-side Javascript and make use of Script APIs , REST APIs , Client-side APIs , and Dynamic Configuration .

The full source implementation of all default themes, widgets, automations, and embeddables is available for review and editing. When editing a default, the theme/widget/automation/embeddable will be identified as custom and can always be compared to the default implementation which is updated as part of each Verint Community upgrade in the first phase of upgrading. 

Maintenance

Customized themes, widgets, automations, and embeddables are not changed during an upgrade.

Updates to the default implementation of customized themes and widgets will be identified in the user interface upgrade process during the second phase of upgrading. For customized themes and widgets, it is recommended that a developer review the difference between the updated default implementation and the customized version to manually incorporate any bug fixes or new functionality. This can be done within Theme Studio and Widget Studio by comparing the changes and will also be shown when clicking the "Edit" link when previewing user interface updates as part of the user interface upgrade.

Updates to the default implementations of automations will be identified in the automation update note during the second phase of upgrading and can be reviewed within Automation Studio. It is recommended that a developer review the difference between the updated default implementation and the customized version to manually incorporate any bug fixes or new functionality using Automation Studio's comparison and merging features.

Updates to the default implementations of embeddables will be identified in the embeddable update note during the second phase of upgrading and can be reviewed within Embeddable Studio. It is recommended that a developer review the difference between the updated default implementation and the customized version to manually incorporate any bug fixes or new functionality using Embeddable Studio's comparison and merging features.

Best Practices

  • For minor changes, it is better to edit a default theme/widget/automation/embeddable than to create a new one to maintain a diff/merge path during upgrades
  • When making minor modifications to a theme, widget, automation, or embeddable, it may be useful to identify in the source via comments where the change starts and ends and the purpose of the change to aid future comparison reviews
  • For significant functionality changes, it may be better to create a new widget, automation, or embeddable

Creating a new Theme

Maintenance Cost: High
Maintainer: Developer
Skills Required:  Velocity , Server-side Javascript , HTML, JavaScript, CSS, LESS, Theme Studio , Widget Studio 

Verint Community includes a single default theme as a basis for customization via theme configuration or editing via Theme Studio. Theme Studio also enables the creation of new themes or the importing of themes from the Marketplace. Multiple themes in a community can be useful if multiple groups or blogs require significantly unique visual styling or behavior.

Implementation

New themes can be created within Theme Studio by going to Administration > Interface > Theme Studio, finding a base theme, clicking the ... menu and selecting Save as Copy. New themes can also be installed from the Marketplace by going to Administration > Interface > Themes and selecting Import.

Maintenance

When creating a new theme, any theme-specific widgets from the base theme will be duplicated for the new theme and all page layouts will be copied from the base theme to the new theme. From a development perspective, you can consider this as a branch of the theme, layouts, and theme-related widgets. 

Custom themes and widgets are not changed during an upgrade and will not be flagged for updating as part of the user interface upgrade process in the second phase of upgrading. It is up to developers to:

  • Manually review new APIs and apply their behaviors to the custom theme and theme-defined widgets
  • Ensure that the custom theme includes new base styling for new default widgets included in the upgrade
  • Ensure that the custom theme's styling applies to default widget updates approved as part of the user interface update (assuming that not all widgets are versioned for the theme as theme-versioned widgets will not be updated)

Best Practices

  • Only create a new theme for a complete reimplementation of the UI or when multiple unique experiences need to be selected between groups or application themes
  • Before creating a new theme, consider creating alternative versions of specific widgets or adding logic to the default theme to select unique stylesheets based on group/application context as an alternative to creating a completely new theme.