BMC+Helix+Innovation+Suite 181101 PDF

BMC Helix Innovation Suite 18.
11
Date: 2018-12-19 01:48

URL: https://docs.bmc.com/docs/x/XHM4MQ
Portions of this document are BMC Confidential.
Contents
Release notes and notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
18.11 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
BMC Helix Innovation Suite platform enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Application development enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
BMC Helix Innovation Suite Interface design enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Known and corrected issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
18.11.01: Patch 01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Improved fallback mechanism for displaying localized field values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Known and corrected issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Downloading and updating the BMC Helix Innovation Suite SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Limitations and upgrade considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Upgrade considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Deprecated features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Upgrading BMC Helix Innovation Suite SDK to 18.11.01: Patch 01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
To upgrade BMC Helix Innovation Suite SDK to 18.11 Patch 01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
To upgrade your application or library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
To upgrade the UI automation project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Quick overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Product roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Product features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Product documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
User assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Recommended skills set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Recommended training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Developer subscription process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Key concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Product overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Anatomy of a Digital Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Digital Service application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
BMC Helix Innovation Suite licensing model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Configurable definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Object definition scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
BMC Helix Innovation Suite 18.11 Page 2

Customization layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Functional role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Leveraging conversation capabilities in BMC Helix Chatbot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Connectors overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Navigating BMC Helix Innovation Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
To access the BMC Helix Innovation Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Overview of the Workspace page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Overview of the Administration page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Overview of the application or library page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Setting the UI preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Process designer interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Rule designer interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Orientation - building a simple application for BMC Helix Innovation Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Module 1 - Developing a full solution to the lunch ordering problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Module 2 - Extending your Solution in Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Module 3 - Packaging, releasing, and upgrading your solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Hands-on Lab Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
User goals and features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Empowering non-developers to develop codeless applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Leveraging Remedy ITSM Foundation data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Leveraging cognitive capabilities in your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Leveraging conversation capabilities in your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Leveraging machine learning metrics to improve cognitive service data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Upgrading to a new version of an application with zero downtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Leveraging full-text search capabilities in your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Automating tasks through emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Extendable application definitions to allow additive changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Designing a Digital Service Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Requirements Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Sketching solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Identifying inventory of functionality required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Mapping new design objects to the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
End-to-end process for developing your Digital Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Comparison between Developer Studio and BMC Helix Innovation Studio capabilities . . . . . . . . . . . . . . . . . . . . . . . 297
Capability comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Capabilities of view definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Capabilities of rule definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Capabilities of process definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Capabilities of associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Capabilities of named lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Capabilities of configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Guidelines for code development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Guidelines for Digital Service application definitions customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Guidelines to define scope for the definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Guidelines for versioning and undeploying an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Guidelines to create accessible custom view components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Onboarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Tailoring applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Creating the definitions for a tailorable Digital Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Defining record definitions to store and manage data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Defining the user interface through view definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Facilitating data entry through named lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Defining the application business logic through processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Adding rules to validate data or trigger events in a process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
Defining a document schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Expression Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Creating configuration settings for your Digital Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Making definitions available for customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Creating and customizing application views by using Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
To access the Shell editor for applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Process for designing an application view in Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Adding navigation components to header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Enabling and customizing global search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Enabling access to reports within an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Controlling user access by assigning permissions to Shell menu elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Toggling between application views and viewing notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Configuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Adding an approval process to an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Creating an approval process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Registering a record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Configuring self approval flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
Configuring approval flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Creating approval notifications to notify approvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
Viewing and responding to approval requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
To use the Approval Console in your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
To view or update an approval request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Adding cognitive capabilities to a custom application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Enabling a custom application for cognitive service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Configuring cognitive service for a custom application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556

Types of data sets used to train and test the cognitive service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Training and testing the cognitive service for a custom application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Evaluating the cognitive service test results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Creating a Java program to use auto-assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Adding a chatbot and conversational capabilities to your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
To enable RSSO OAuth 2.0 in your chatbot application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Chatbot framework architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Creating a conversation workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
Formatting chatbot responses to support multiple messaging interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Integrating with a collaboration service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Creating a chat context listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Creating processes and actions for dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
Creating a chatbot configuration for an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
Configuring a chatbot for your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Testing the chatbot training data to improve predictability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Integrating with REST services in a codeless way . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Points to consider before connecting to RESTful service in a codeless way . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Scenario: Connecting to the JIRA REST API service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
Process for connecting to a REST API service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
Before deploying an application in the production environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
Creating a REST API web service request definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
Configuring the authentication credentials of REST API web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Configuring web requests in a business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
Mapping the REST API web service request alias to an appropriate connection . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Integrating with another application by using a connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Connector Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Example of extending BMC Helix Chatbot by using connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Adding connector configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
Integrating applications using process connector element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Integrating applications using rule connector element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
Creating alias mapping of the connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
Enabling automatic record assignment in an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
How does automatic assignment work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Methods for assigning requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
To configure applications to automatically assign requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Defining assignment policies to specify rules for assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Defining assignment processes to trigger the assignment policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
Administering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Tailoring the application skin and brand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
To configure the skins for applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
To add logo images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Embedding BMC Helix Innovation Suite views in external applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
Workflow to embed BMC Helix Innovation Suite views in external applications . . . . . . . . . . . . . . . . . . . . . . . . . . 637

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638

To prepare a view for external applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
To enable an BMC Helix Innovation Suite view to load in iFrame of external application . . . . . . . . . . . . . . . . . . 638
To configure the external application to embed the BMC Helix Innovation Suite view . . . . . . . . . . . . . . . . . . . 639
To remove access to an embedded view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
Setting up Foundation data for custom applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
Foundation data library and data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
Foundation data reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Filtering Foundation data by domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Creating or modifying Foundation data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Creating or modifying Foundation data associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Loading Foundation data in bulk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Loading existing Foundation data from Remedy ITSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Addressing data privacy requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Personal data in BMC Helix Innovation Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Capabilities for handling personal data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
To search for personal data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
To download personal data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
To replace personal data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
GDPR request status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
Managing user access and permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
Roles and permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
Creating Functional roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
Creating administrators and application business analysts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
Creating and modifying application roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Configuring incoming and outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
To configure incoming mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
To configure outgoing mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
To configure outgoing profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
To configure templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
Configuring full-text search to refine the search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
FTS configuration settings and their descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
To configure FTS settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Updating centralized tenant configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
To configure centralized tenant configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
Centralized Tenant Configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
Assigning application licenses to users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
To assign BMC Helix Innovation Suite licenses to users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
To assign application licenses to users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
To generate application license usage reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
To remove BMC Helix Innovation Suite licenses from users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Deploying codeless applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Workflow of deploying codeless applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763


Types of deployment packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Creating install packages to deploy entire applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766
Creating update packages to deploy incremental changes of applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
Updating applications by using update packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
Installing, reinstalling, or uninstalling codeless applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Creating export packages to deploy tailoring changes of applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
Importing the export packages to deploy tailoring changes of applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
Consuming a new version of an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
Process to upgrade to a new version of an application in a test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
Process to upgrade to a new version of an application in a production environment . . . . . . . . . . . . . . . . . . . . 780
To upgrade to a new version in a test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
Submitting user reported issues to BMC Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
To configure your BMC Service Cloud account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
To submit user reported issues to BMC Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
To mark an issue as duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Measuring the cognitive service consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Cognitive service operations and their measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Methods for monitoring cognitive service consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
To download the cognitive service usage report from the Telemetry dashboard . . . . . . . . . . . . . . . . . . . . . . . . 786
To configure thresholds and email notifications for cognitive service usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
To view the notification history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
Localizing field values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
To add a system locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
To edit a system locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
Best practices for defining localizable fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
Operations supported by a localizable field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
To define localizable fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
To add record instances in the localizable record definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
Considerations when assigning a Localized Text field in a process or a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
Fallback mechanism for displaying localized field values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
Developing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
Developing codeless applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
Workflow of creating codeless applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
Steps to create a codeless application bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
Steps to create a codeless library bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
Extending codeless applications with custom coded components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
Developing and deploying code-based applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
Preparing to develop a Digital Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
Creating a custom service in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823

Creating a custom user interface with AngularJS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826

Creating a custom interface with REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
Customizing an application with REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
Getting your Digital Service application ready for use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
Using Data Caching Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
Undeploying a version of your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
Enabling Remedy SSO OAuth 2.0 authentication for your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
Process of creating and adding RSSO OAuth 2.0 settings in an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
To create In-bundle settings for RSSO OAuth configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
To add the RSSO OAuth In-bundle setting in custom code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
Troubleshooting sandbox access issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
Troubleshooting user account locked error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
Troubleshooting BMC Helix Innovation Studio access authorization issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
Troubleshooting application deployment issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
Troubleshooting package creation issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
Troubleshooting application deployment issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
Enabling logging for a Digital Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
To enable BMC Helix Innovation Suite platform logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
To enable logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
Searching log files to track a single operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
Format of log messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
To disable logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
To clear the logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
Using Logger service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
Enabling browser logging in a Digital Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
To enable logging in code-based applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
To enable logging in codeless applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
Logging levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
Troubleshooting automatic assignment issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
Troubleshooting Foundation data issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
Troubleshooting issues while loading Foundation data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
Troubleshooting issues while customizing or extending Foundation data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
Troubleshooting incoming and outgoing email issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
Troubleshooting integration service connection issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
To modify the user credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
Reporting application errors as issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992
To report errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993

Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993

Contacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
Support status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
Innovation Suite Availability policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
Downtime definition by category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
Downtime definition by functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
Customer applications causing downtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
Requesting a service credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
OnDemand Change Management policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
Testing and review requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
Innovation Suite Custom Application policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
General approach to supporting custom applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
Your custom Innovation Suite application responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
Custom Remedy application integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
Support for custom applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
Upgrade process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
Subscription licensing considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
Capacity considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
OnDemand Notification policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
Maintenance notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
OnDemand policy changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
OnDemand Language Support policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
Innovation Suite Permissions policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
Summary of administration levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
Customer environments and administration access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
Administration access policy for customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
BMC quality of service commitment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
OnDemand Incident Response policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
Reason for Outage documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
Root Cause Analysis documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
Innovation Suite Upgrade policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
Release availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
The upgrade process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
PDFs, videos and API documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
API documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
FAQs and additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Example of how cognitive test metrics are calculated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
Application upgrade FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
Types of expressions in expression editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
BMC Helix Innovation Suite JavaBean Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
Securing BMC Helix Innovation Suite against web and CSRF attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
Protection against CSRF attack vulnerability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022

BMC Helix Innovation Suite platform is a combination of services and components that helps you develop, build, deploy,
and use multi-tenant applications on cloud. It also helps you to create and automate many business processes without
learning a programming language or complex development tools.
Getting started (see page 29) Tailoring applications (see page 322)
Orientation (see page 30) Customize applications according to your business processes.
Product overview (see page 36) If you are an Application Business Analyst this is a good place to start.
Navigating BMC Helix Innovation Studio (see

page 59) Configuring (see page 535)
Customize your applications by using Cognitive service, Chatbot framework, Approval library, and
Use cases (see page 277)
Connectors.
Best practices (see page 307)
Administering (see page 632)

Introduction to BMC Helix Innovation Suite
Set up users, manage roles, set up foundation data, assign licenses, submit user reported issues, and
<p> </p> create and deploy codeless applications with minimal programming knowledge or dependency on
developers.
If you are an Administrator this is a good place to start.
Troubleshooting (see page 979) Developing applications (see page 794)

Resolve issues with your environment, find solutions to
Develop codeless applications with minimal programming.
problems while developing or tailoring applications,
look up error messages or logs.
Develop code-based applications by using the BMC Helix Innovation Suite SDK, BMC Helix
Innovation Studio, and Maven archetypes to extend the BMC Helix Innovation Suite platform to
create custom components, custom REST APIs, and so on.
If you are a Developer, this is a good place to start.
Communities Developer Portal Sample Videos Podcasts Marketplace

application
Join discussions Find apps, connectors,

Learn, develop, and (see View the BMC Helix Listen to experts in
with peers and learning modules, and
connect with the Developer page 66) Innovation Suite video Digital Service
experts. more.
Community. playlist. Management.
Build an application
with BMC Helix
Innovation Suite
Release notes and notices

Consult the following table for a list of notices and information about updates to BMC Helix Innovation Suite.
Updates
The following updates have been added since the release of the space:

Date Release Summary
December 19, Patch 01 for This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
2018 18.11 (see page
Additionally, BMC Helix Innovation Suite includes the following enhancement:
23)
Improved fallback mechanism for displaying localized field values.
November 30, 18.11 (see page BMC Helix Innovation Suite has been enhanced in the following areas:
2018 14)
Foundation library
The Foundation data model for Organization and Person data is changed to have more parity with
Remedy IT Service Management Suite.
Easier conversion between types of Organization and Person.
Reduced restrictions on Organization and Person so that customers have more control on Organization
and Person data.
The Foundation Service REST APIs output structure for Organization data and Person data has changed
to match the new data model. The parameters remain unchanged for most parts.
Connect to RESTful services in a codeless way from the BMC Helix Innovation Studio UI.
Ability to test accuracy, precision, recall, and F-score of BMC Helix Innovation Suite Cognitive Service when
using for auto-categorization and chatbot.
Support for outgoing profiles to enhance the email capabilities.
Ability to access attributes such as, complex objects, array of objects, array of strings, and nested complex
objects by using a Document definition.
Ability to change the layout of view components.
Support for custom izing user menu to display the user profile.
Ability to cancel user-driven approval requests and filter approvers from the foundation data.
Ability to edit multiple records in a record grid, define filter presets, and filter rows by cell selection.
Responsive web layouts in the browser.
September 12, 18.08 BMC Helix Innovation Suite has been enhanced in the following areas:
2018
Embed BMC Helix Innovation Suite views in external applications.
Creation of codeless applications and libraries in a tailoring environment.
Using a new PIN field in Foundation data to verify individuals.
Configuring approval flows using one single wizard.
Introducing Business Analyst role in BMC Helix Innovation Suite.
Enable extension of application definitions.
Enhanced load and synchronization of Remedy ITSM Foundation data to BMC Helix Innovation Suite.
Ability to identify updates to the security label.
Enhancements in connectors.
Section 508 compliance.
July 29, 2018 18.05.01 This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
Additionally, BMC Helix Innovation Suite includes the following enhancements:
Zero downtime upgrade of Innovation Suite.
Audit fields from associated record definitions.
June 6, 2018 18.05 BMC Helix Innovation Suite has been enhanced in the following areas:

Full-text search capabilities in a Digital Service application.
Incoming and outgoing email configuration.
Deploy code-based application across environments in a dedicated systems.
Support for GDPR.
Report application errors as issues to customer support.
March 30, 2018 Update 01 for This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
18.02
Zero downtime upgrade to a new version of an application.
BMC applications and partner-developed applications can now be set to have unlimited users in a tenancy.
February 28, 18.02 BMC Helix Innovation Suite includes the following enhancements:
2018
Chatbot framework enhancements:
Support for multiple chat providers
Support for enabling chat conversations through SMS
Support for enabling chat conversations through Skype for Business
Ability to format chatbot responses
Associate and display field values for Approval record definitions
Leverage Foundation Data to assign approvers of the approval requests
Localize field values of a record definition
Localizable Foundation category data
Enable row-level security for roles from multiple applications
Enable maximum number of training data sets permitted by IBM Watson Assistant for auto-ategorization and
auto-assignment
Support for Remedy Single Sign-On (RSSO) OAuth 2.0 for BMC Helix Innovation Suite applications
January 30, 2018 Update 01 for This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
17.11
Increased limit of training data sets when using BMC Helix Innovation Suite Cognitive Service.
November 30, 17.11 BMC Helix Innovation Suite includes the following enhancements:
2017
Chatbot framework to provide virtual chat and cognitive search capabilities in your application.
Automated assignment using Cognitive Service.
Data load and synchronization capability for ITSM Foundation data.
Leverage Smart Reporting in BMC Helix Innovation Suite application.
Remove Mid Tier for tenant configuration: Licensing Management and Assignment.
Automatically persist user settings between sessions.
Display associations in Approval Console.
Hide navigation items in Shell when user does not have permission.
Disassociate records to prevent orphaned records.
Support RSSO for SAML/IDP based user authentication.
Unified logging to improve ability to query across logs.

UI improvements for creating and managing Foundation data.
Copy fields in a Record.
Clear All capability in notification bell.
Access error data in caught exceptions.
October 13, 2017 Update 01 for This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
17.08
August 25, 2017 17.08 BMC Helix Innovation Suite includes the following enhancements:
Ability to integrate your applications with third-party systems.
Support for creating codeless application.
Ease of use in deploying applications across environments.
Enhancements to improve application development experience.
July 18, 2017 Update 01 for This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
17.05
Additionally, following JAR files are no longer bundled with the BMC Helix Innovation Suite SDK ( com.bmc.arsys.rx.sdk-
17.5.0.zip), as these JAR files are used only for internal framework functionality :
com.bmc.arsys.rx.application-test.jar
com.bmc.arsys.common.jar
com.bmc.arsys.domain.jar
To test your application or library, see Testing application logic with the automation framework.
May 25, 2017 17.05 BMC Helix Innovation Suite includes the following enhancements:
Ease of application upgrade.
Enhancements to address data security and performance.
Support for better debugging and troubleshooting your applications.
New REST APIs for Foundation library and Approval library.
Support for loading Foundation data in bulk.
Ease of granting application permissions using Functional Roles.
Enhancements to the View Designer interface elements such as Record Grid, Select Group component, and
Action button.
May 09, 2017 Update 02 for This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
17.02
March 28, 2017 Update 01 for This update includes updated BMC Helix Innovation Suite SDK and fixes for defects.
17.02
February 27, 2017 17.02 BMC Helix Innovation Suite includes the following enhancements:
Lock core platform objects from being customized
BMC Remedy Deployment Application now enables you to promote your Digital Service application
customization and data across environments
February 01, 2017 IS16.12b This update includes updated standard library for BMC Helix Innovation Suite services and fixes for defects.
December 22, IS16.12a This update includes updated standard library and updated Java libraries for BMC Helix Innovation Suite services, and
2016 fixes for defects.
- BMC Helix Innovation Suite Developer release.

December 05,
2016
Related topics
Known and corrected issues (see page 20)
FAQs and additional resources (see page 1009)
18.11 enhancements
This section contains information about enhancements in version 18.11 of BMC Helix Innovation Suite.
BMC Helix Innovation Suite platform enhancements
BMC Helix Innovation Studio Foundation library enhancements to increase parity with Remedy IT Service
Management Suite
The Foundation data model has changed to reduce the restrictions on Organization and Person data so that customers
have more control on their data. Customers can now perform the following tasks that were earlier restricted:
Transition of data semantics between Remedy IT Service Management (Remedy ITSM) Suite and BMC Helix
Innovation Suite.
Convert between types of Organization and Person.
Create multiple types for organizations.
Leverage recursion for regions and support groups.
Organization data model changes

The hierarchy in Primary organization is no longer applicable. In BMC Helix Innovation Suite version 18.08 and earlier,
Primary organization was defined as one of these types: Service Provider, Operating organization, Vendor organization,
or Manufacturer. You do not need to create separate record definitions for Primary Organization data and its types, such
as Service Provider, Operating organization, Vendor organization, and Manufacturer. The types of Primary Organization
are now stored as the Type field in a single Primary Organization record definition.
The Secondary organization data model remains unchanged.
For more information, see Organization data (see page 644) .
The following image represents the changes in the Primary organization:

Person data model changes

The hierarchy for Person data is no longer applicable. In BMC Helix Innovation Suite version 18.08 and earlier, Person
data and its types, such as Employee, Agent, Customer, or Vendor were stored as separate record definitions.
Starting from this release, you do not need to create separate record definitions for Person data and its types. The types
of Person are now stored as the Type field in a single Person record definition.
The following image represents the changes for Person data:
For more information, see Person data (see page 650).
Filtering Foundation data by domain

Developers can leverage domain data tags to filter Foundation data. Filtering of Foundation data by using domain data
tag allows you to skip unwanted data, control visibility, and filter Foundation data within your applications.
For example, in your HR services application, you can apply HR domain tag to HR support groups, incident requests, or
support tickets to retrieve and show data related to HR only.
For more information, see Filtering Foundation data by domain (see page 661).

Enhancement to process variable with Document definition support

Developers can access attributes such as, complex objects, array of objects, array of strings, and nested complex objects
by using a Document definition. Developers can define document definition when communicating with a third-party
module by using custom actions or connectors. The document definition enables you to access the attributes returned
by the custom actions or connectors and use these attributes as an input or output within a process.
For more information, see Defining document definitions (see page 497).
Ability to test the BMC Helix Innovation Studio Cognitive Service data sets and chatbot applications
Administrators can test the BMC Helix Innovation Studio Cognitive Service data sets and chatbot application for
accuracy, precision, recall, and F-score. These tests are particularly important when you are implementing a new training
data set or if you have made major changes to the data sets.
Testing the Cognitive Service and chatbot has the following benefits:
Helps ensure that the cognitive service selects the correct category with the desired frequency.
Helps ensure that the chatbot correctly identifies the intent and responds to the end users accordingly.
Helps identify the exact problem area so that you can rectify the data sets to improve the performance of the
cognitive service.
Provides a history of the test results.
For more information, see Leveraging machine learning metrics to improve cognitive service data sets (see page 283).
Connect to RESTful services without using code

Developers can connect to RESTful services in a codeless way by using the BMC Helix Innovation Studio UI. This
eliminates the need to install an IDE, write Java code, or run and manage an Integration Controller. You define a one-time
configuration for each RESTful service, and create a business process for various HTTP methods such as GET, PUT,
POST, or DELETE.
For example, by using this feature, you can connect to JIRA RESTful service in a codeless way to get details of a JIRA
issue or update the JIRA issue. For more information, see Integrating with REST services in a codeless way (see page 604)
.
Application development enhancements
Email enhancements
BMC Helix Innovation Studio enhances the email capabilities by providing the following features:
Administrators can now restrict the total number of attachments and the total size of the attachments that can
be added to an outgoing email. For more information, see Updating centralized tenant configuration settings (see
page 756).

Administrators can now configure outgoing profiles to update the outgoing mailbox without the need to modify
the existing processes and rules.
For example, consider a scenario where you use HR@calbro.com outgoing mailbox in multiple processes and
rules to send email notifications to the employees of Calbro Services.
Calbro Services organization now wants to seperate HR emails based on locations (India and US). As a result, the
processes and rules will need to be updated manually for two different outgoing mailboxes.
With this enhancement, an administrator can now map the outgoing mailbox to an outgoing email profile and use
this profile in the processes and rules. So that even after you update the outgoing mailbox, the processes and
rules remain unaffected and continue to send email notifications by using correct outgoing mailbox.
For more information, see Configuring incoming and outgoing email (see page 750).
Approval enhancements
The Approval application now supports the following two enhancements:
Cancellation of user-driven approval requests that are in pending state. For more information, see Creating an
approval process (see page 537).
In general approval flows, while selecting approvers, users can now filter approvers from the foundation data.
Users can apply filters to the functional roles, business units, support groups, person, location, and so on. This
helps in narrowing your selection to an approver belonging to a business unit or functional role, instead of the
whole business unit or functional role.
For more information, see Configuring approval flows (see page 546) .
BMC Helix Innovation Suite Interface design enhancements
Ability to change the layout of view components

Developers can now change the layout of view components and improve the clarity and readability of the information
that is displayed on the application.
You can choose from the following layouts:
Display the Boolean view component as a check box or as a switch.
Display the Select view component as radio buttons or as a list.
For example, in an ServiceDesk application, that users can use to create helpdesk tickets, you can configure the layout of
view components as follows:
Status record field such that the options are displayed as radio buttons
Does this issue impact the team? Boolean field such that it is displayed as a check box
Time to Resolve record field such that the options are displayed in a list

Example of view configuration Example of view display
For information about how to choose the layout of view components, see Creating a view for a record instance using
Record Editor (see page 396).
Grid enhancements
The Record Grid component supports the following enhancements:
D evelopers can enable editing of multiple records in a record grid by using the Edit Records action. For more
information, see Configuring actions by using an action button (see page 384).
Developers can now define filter presets that can be used in the deployed application. These filter presets are
saved in the view definition and are visible in the deployed application. The users can create their own filter
presets. They can either modify a shared filter preset by adding, removing, or editing the filters included in the
preset. Users can also define multiple filters and save them as a private preset. The private presets are stored in
user preferences. For more information, see Working with the Record Grid (see page 404).
Users can also filter rows by cell selection. The record grid takes the value of the column from the selected row
and filters the rows on that value. This displays all the rows with the selected column value. You can select
multiple rows and get a list of distinct column values from the selected rows and filters the data by multiple
values. For example, Status = "Open" or Status = "In Progress" or Status = "Blocked". If there are more than ten
distinct values detected, an error is displayed.
Example of filtering rows by cell selection
Result

Example of filtering rows by cell selection
Support for customizing user menu to display the user profile

By using BMC Modern Shell, application business analysts and developers can now customize the user menu to display
information about the user's profile. BMC Modern Shell is a built-in landing page and default menu system that is
configured for every application. You can provide information about the user and the application settings for that user,
and display it on the application menu.
The following image is an example of a View Profile menu item that is added to the user menu:
For information about how to customize the user menu, see To customize user menu (see page 525).
Responsive web layout

BMC Helix Innovation Suite views are rendered with a responsive layout in browsers. In responsive layouts, the
components wrap vertically when the width of the browser's viewport is not sufficient to display them as laid out in the
View designer. This feature is useful in the mobile device browsers such as smart phones, tablets, and so on. You can also
simulate the layouts on various devices. You can control the layout size by configuring the Row Wrap property in the
Container view component and the modal views in the Open View actions.
For more information on responsive web layout, see Creating a responsive web layout (see page 393).

Related topics
Limitations and upgrade considerations (see page 24)
Known and corrected issues
BMC Confidential. The following information is intended only for registered users of docs.bmc.com.
The following issues pertain to this release of BMC Helix Innovation Suite.
Corrected issues View the issues in the following tables by the default sort order, Corrected in, which shows the corrected issues first.
The version number represents the update ( Year.Month.Release ) in which the issue is fixed.
Known (open) issues An issue with no version number listed remains open.
You can also filter and sort issues according to affected version (versions in which the issue exists), component, or
defect ID.
Issues when accessing BMC Helix Innovation Studio in Internet Explorer 11

When you access BMC Helix Innovation Studio by using Internet Explorer 11, the following features related to
developing an application do not work properly:
Component Description Corrected Affected Issue

in versions
Process In Process designer and Rule designer, names of elements that are long, such as, Disassociate All 18.05.01 DRIST
designer and Records, Automatic Assignee Suggestion, Call Assignment Policy, and so on overlap on the element -
Rule designer icon. 7047
Process In Process designer, when configuring the Timer element, the increase or decrease counter 18.05.01 DRIST
designer -
buttons are not displayed. 6086
Record In Record designer, when you create a Floating or Integer type field, you can enter letters in fields 18.05.01 DRIST
designer that must accept only numeric values. For example, you can enter letters in the Minimum Value, - 7051
Maximum value, and Precision fields.
View designer In View designer, when configuring the Action Button element, the fields in the Properties tab are 18.05.01 DRIST
not aligned uniformly. -
6996
View designer In View designer, when you enter text in the Rich Text element, you cannot select the text by 18.05.01 DRIST
double-clicking it. -
7028
Record When you copy the GUID of a record instance and paste it in the View properties, the GUID is not 18.05.01 DRIST
designer and copied appropriately. -
View designer 6999
Foundation When you search for parent operational categories from Administration > Foundation Data > 18.05.01 DRIST
library Manage Categorizations > Operational Categories, some parent operational categories are not - 7284
displayed in the search results.
Workaround:


in versions
When accessing BMC Helix Innovation Studio by using Internet Explorer or Microsoft Edge, go to
Control Panel > Language and add all the languages listed in BMC Helix Innovation Studio.
Login screen When you access the BMC Helix Innovation Suite URL in Internet Explorer 11, in the User Name 18.05.01 DRIST
field, the placeholder is not displayed. -
7004
BMC Helix Innovation Suite issues

in versions
Process When you use Exclusive gateway elements to create loops that iterates more than 15 times, 18.11 DRIST - 10231
designer execution errors are generated.
Workaround: See Workaround for using Exclusive gateway in loops (see page 443).
Process In a process, if the Profile ID attribute of the Connector Configuration system action is 18.11.01 18.11 DRIST - 10214
designer empty, the process does not work when the application is imported to the production
environment from the developer environment.
BMC Helix In the IBM Watson Assistant Service training data set, the length of the data in the Category 18.11.01 18.11 DRIST -
Innovation column cannot exceed 128 characters. 10260
Suite
For complete information about setting up the training data set, see Types of data sets used
Cognitive
to train and test the cognitive service (see page 559).
Service
View While creating views, when you open the Container > Record Grid > Add/Remove Grid 18.11 DRIST - 10227
designer Columns page and expand all of the selected column sections and clear the Sorting enabled
check box of the last selected column, the page becomes blank and stops responding.
BMC Helix As a developer, when you deploy an application to the development environment, if the 18.11 DRIST - 8354
Innovation bundle ID of the application does not match with the developer ID on the development
Suite server, then the Uninstall option is not displayed.
Workaround: None. Contact BMC Support to uninstall the application.
Manage During process execution, when the Call Activity element results in business errors, the Call 18.08 DRIST - 7109
Processes Activity element is not highlighted on the process instance canvas.
user
interface
Notifications In applications that are developed by using BMC Helix Innovation Suite, HTML tags are 18.08 DRIST - 8329
Library appended to the notification messages that appear in the bell icon.
Foundation When you create Sites from Administration > Foundation Data > Manage Locations > Sites, 18.11 18.08 DRIST - 8787
Library the GUID is displayed instead of the Additional Site Details field label.
Foundation When you use the Remedy ITSM Foundation to BMC Helix Innovation Suite Sync Utility, in 18.11 18.08 DRIST - 8774
LIbrary BMC Helix Innovation Suite, when you create a support group by using comma in the name,
an error is displayed, but the support group is created in the system.
Foundation When you load Foundation data from Remedy ITSM to BMC Helix Innovation Suite, in 18.11 18.08 DRIST - 8325
Library Remedy ITSM, if you have administrator permissions and support groups associated with
customers or vendors, although the permissions and the associations are loaded in BMC Helix
Innovation Suite, but you cannot view them in BMC Helix Innovation Suite.
Foundation When you synchronize Foundation data from Remedy ITSM to BMC Helix Innovation Suite, if 18.11 18.08 DRIST - 8347
LIbrary you change the Company Type, Client Type, or Support Staff in Remedy ITSM, the updates
are not synced in BMC Helix Innovation Suite.


in versions
Process When you access BMC Helix Innovation Suite by using Microsoft Edge bundled with Windows 18.05 DRIST - 6088
designer 10 version 1709, in Process designer, if you attempt to modify the label or description of an
element, the browser page refreshes and becomes unresponsive.
Workaround: Upgrade to the new version of Microsoft Edge to access BMC Helix Innovation
Suite.
BMC Helix After you deploy a chatbot that was created by using the Microsoft Bot Framework to 18.02 SW00541292
Innovation Microsoft Office 365 Skype for Business channel, users can interact with the chatbot, but the
Suite chatbot status shows as Presence Unknown. This known issue comes from Microsoft Office
365 Skype for Business. See Microsoft Bot Builder issues .
BMC Helix When you upgrade your applications to BMC Helix Innovation Suite version 17.8.0 and build 17.11 SW00533904
Innovation the application project by using the mvn clean install command, the UI automation
Suite project fails with the following error:
[ERROR] /C:/projects/request-manager-app/ui-automation/src
/test /java/com/verizonwireless/it/request/com/example/
uiautomation/sample/UIAutomationSuite.java:[39,8] com.
verizonwireless.it.request. uiautomation.sample.
UIAutomationSuite is not abstract and does not override
abstract method getApplicationName() in com.bmc.rx.test.
framework.UIBaseTest
Workaround: You must create a sample application by using BMC Helix Innovation Suite SDK
17.8.0 and use the newly generated /automation/ and /ui-automation/ projects in your existing
application project.
Process In Process designer, if you define a parallel multi-instance Call Activity within a sub-process 18.11 17.11 DRIST- 6629
designer that includes an Error Boundary or Error End event, and any of the iteration fails and the
transaction is rolled back, but all the iterations after the failed iteration are executed, then the
changes performed by those iterations are committed.
Example 1: If a process includes three iterations for a parallel multi-instance Call Activity:
Sub-process iteration 1 succeeds.
Sub-process iteration 2 fails and performs rollback of all the changes performed.
Sub-process iteration 3 succeeds and the changes are committed.
Example 2: If a process includes four iterations for a parallel multi-instance Call Activity:
Sub-process iteration 1 succeeds
Sub-process iteration 2 fails and performs rollback of all the changes performed.
Sub-process iteration 3 succeeds and changes are committed.
Sub-process iteration 4 succeeds and changes are committed.
Process In Process designer, if you define a sub-process that includes an Error Boundary event and an 17.11 SW00529468
designer action that performs CRUD operations on a record instance to trigger a rule, the rule invokes
an action or starts a process that has no wait state (no User Task and no Receive Task).
After performing the CRUD operations on a record instance, if you use an On Create, On
Update, On Delete, or On Import record event to trigger the rule and an error is generated in
the Sub-Process, then all the database operations performed during the Sub-Process and the
rule are rolled back.
But if you use an After Create, After Update, After Delete, or After Import record event to
trigger the rule, and an error is generated in the Sub-Process, then the database operations
performed by the rule are not rolled back.
17.11 SW00513193


in versions
View When a text field with Named List is added to a Record Grid, the Record Grid displays values DRIST - 580
designer instead of labels.
This issue occurs if you select multiple fields simultaneously.
Workaround: Use the same Source Field and Value Field in the Named List definition.
BMC Helix While developing an application, if you create a new field whose ID is not in range defined in 17.11 SW00520284
Innovation Field ID Range, the new field is still created with the following warning:
DRIST - 3269
Suite
WARNING (471): Field ID given by the user is not within
the specified range.
Workaround: Delete the field and create a new field whose field ID is within the range
specified in Field ID Range.
BMC Confidential. The preceding information is intended only for registered users of docs.bmc.com.
18.11.01: Patch 01
Patch 01 to the 18.11 release includes the following changes:
Improved fallback mechanism for displaying localized field values

BMC Helix Innovation Suite now displays the generic system locale if the user's system locale is not defined on the
Manage System Locales page. For more information, see Localizing field values (see page 788).
Known and corrected issues

For a list of issues fixed in this update, see Known and corrected issues (see page 20).
Downloading and updating the BMC Helix Innovation Suite SDK

To download the latest BMC Helix Innovation Suite SDK for 18.11.01: Patch 01, see Setting up your IDE and installing BMC
Helix Innovation Suite SDK (see page 800).
For instructions about how to update the SDK, see Upgrading BMC Helix Innovation Suite SDK to 18.11.01: Patch 01 (see
page 27).
Information and resources
How do I request an BMC Helix Innovation Suite sandbox?

Go to developers.bmc.com.
What issues were fixed in this update?

For a list of issues fixed in this update, see Known and corrected issues (see page 20).
How do I report an issue with the update?

If you encounter an issue, post the issue in the Developer Community.

How can I join BMC Communities?

Click the Register link in the Developer Community where you can learn from other innovators, get resources,
post ideas, and more.
Limitations and upgrade considerations

Learn about the limitations and upgrade considerations for BMC Helix Innovation Suite.
Limitations
The following table provides information about the limitations of BMC Helix Innovation Suite.
Release Summary
18.11 When accessing BMC Helix Innovation Studio in Internet Explorer 11, the following features do not work appropriately:
18.08 On the BMC Helix Innovation Studio login page, in the User Name field, the cursor is not displayed.
18.05.01 In Foundation library, the parent operational categories are not displayed in search results.
In Process and Rule designer, names of some elements overlap on the element icon.
In Process designer > Timer Event element, the increase and decrease counter buttons are not displayed.
In Record designer, you can enter alphabets in fields that must contain numeric values.
In View designer, the Action Button element properties are not aligned uniformly.
When copying GUID from a record instance to View designer, the GUID is not copied appropriately.
In View designer > Rich Text element, you cannot select the text by double-clicking the mouse.
For more information about these limitations and their workaround, see known and corrected issues (see page 20).
To get complete compatibility information for BMC Helix Innovation Suite, use the BMC Solution and Product Availability
and Compatibility Utility on the Product Availability and Compatibility page (requires Customer Support logon).
Upgrade considerations
The following table provides information about changes in BMC Helix Innovation Suite SDK (com.bmc.arsys.rx.sdk-18.11.1.
zip) that might break certain features after upgrade. To avoid errors, you must perform the workarounds given in the
table:
Version Summary
18.11 When we upgrade BMC Helix Innovation Suite to version 18.11 we upgrade the Foundation data for the codeless applications deployed in the
production environment.
However, for the following scenarios, Foundation data is not upgraded:
Applications that are not deployed in the production environment or currently deployed into AWS Sandbox environments.
Coded applications with angular code or Java actions.

BMC does not inspect into Angular and Java code to modify references to deprecated objects.
Extended views.
Workaround:
To ensure that applications that are not deployed in the production environment are upgraded with Foundation data model changes, perform the
following tasks:
1. Contact BMC support for a BMC Helix Innovation Suite instance prior to version 18.11, such as 18.08.01.

2.
Version Summary
2. Deploy your application on the pre-18.11 instance.
3. Contact BMC support to upgrade the pre-18.11 instance to BMC Helix Innovation Suite 18.11.
4. Export your application to BMC Helix Innovation Suite 18.11 instance.

Exporting your application will modify the application to use the updated Foundation data model. You can now deploy your application to
any instance with BMC Helix Innovation Suite 18.11.
18.11 The Record editor’s 'Can Save' property that is available within the View designer's expression editor does not consider whether there are invalid
fields on the form. For example, blank required fields.
The 'Can Save' property evaluates to 0, if any of the following is true:
The Save is already in progress.
The Record editor is in edit mode and there are no changes made to any of the fields.
In all other cases, the 'Can Save' property evaluates to 1.
If you need to disable the Save button when there are field validation errors, use the following expression for the Action button’s disabled property:
“Can Save” = 0 OR “Is Valid” = 0
18.08 When you retrieve attachments by using REST APIs, the File Name header no longer exists.
Workaround: You can retreive the attachment file name by using the Content-Disposition header.
You must also use the Content-Disposition header in the the following URLs:
api/rx/application/process/processinstance /attachment/{processDefinitionName}/{processInstanceId}/{paramterId}
api/rx/application/record/recordinstance/export
18.08 With the use of universal entry point, the URLs for the BMC Helix Innovation Suite applications have changed as follows:
Approval— http://<host>:<port>/innovationsuite/index.html#/com.bmc.arsys.rx.approval
Assignment— http://<host>:<port>/innovationsuite/index.html#/com.bmc.arsys.rx.assignment
Foundation— http://<host>:<port>/innovationsuite/index.html#/com.bmc.arsys.rx.foundation
Data Management Console— http://<host>:<port>/innovationsuite/index.html#/com.bmc.arsys.rx.dataload
Environment Configuration— http://<host>:<port>/innovationsuite/index.html#/com.bmc.arsys.rx.environment-configuration
Settings— http://<host>:<port>/innovationsuite/index.html#/com.bmc.arsys.rx.settings
18.08 The BMC logo displayed on the BMC Helix Innovation Studio login page and in the application shell header is updated and is 25px wider.
If you developed applications from an archetype that created an application-specific index.html file, the logo might be distorted in the application
shell.
Workaround: To avoid logo distortion, in the CSS file, you must increase the width of the .bmc-logo element by performing the following
steps:
1. Go to the resources/sass/partials/_app-header.scss file.
2. Update the .bmc-logo element as shown in the following code:

Before updating
.bmc-logo { display: block; width: 80px; height: 27px; background: url("#{$img-path}logo

/company.svg") no-repeat; }

Version Summary
After updating
.bmc-logo { display: block; width: 105px; height: 27px; background: url("#{$img-path}logo

/company.svg") no-repeat; }
Deprecated features
The following table provides information about the deprecations, that is, features that are no longer supported in BMC
Helix Innovation Suite. To prevent errors, you must avoid using these deprecated features.
Version Summary
18.11 To match the updated Foundation data model for Organization and Person data, the following Foundation views are no longer available:
com.bmc.arsys.rx.foundation:PER Employee Edit
com.bmc.arsys.rx.foundation:PER Vendor Editor
com.bmc.arsys.rx.foundation:ORG Manufacturer Editor
com.bmc.arsys.rx.foundation:ORG Service Provider Editor
com.bmc.arsys.rx.foundation:ORG Service Provider Create
com.bmc.arsys.rx.foundation:PER Employee Create
com.bmc.arsys.rx.foundation:PER Vendor Create
com.bmc.arsys.rx.foundation:PER Customer Create
com.bmc.arsys.rx.foundation:ORG Manufacturer Create
com.bmc.arsys.rx.foundation:PER Employee Editor
com.bmc.arsys.rx.foundation:PER Customer Editor
com.bmc.arsys.rx.foundation:ORG Operating Organization Edit
com.bmc.arsys.rx.foundation:PER Agent Edit
com.bmc.arsys.rx.foundation:ORG Operating Organization Create
com.bmc.arsys.rx.foundation:PER Vendor Edit
com.bmc.arsys.rx.foundation:ORG Manufacturer Edit
com.bmc.arsys.rx.foundation:PER Customer Edit
com.bmc.arsys.rx.foundation:ORG Service Provider Edit
com.bmc.arsys.rx.foundation:ORG Vendor Organization Edit
com.bmc.arsys.rx.foundation:ORG Vendor Organization Editor
com.bmc.arsys.rx.foundation:PER Agent Editor
com.bmc.arsys.rx.foundation:ORG Vendor Organization Create
com.bmc.arsys.rx.foundation:ORG Operating Organization Editor
com.bmc.arsys.rx.foundation:PER Agent Create
18.11 In BMC Helix Innovation Suite Cognitive Service, when you train the cognitive service by using application data, you can no longer schedule the
application data training.

Upgrading BMC Helix Innovation Suite SDK to 18.11.01: Patch 01

If you are using the BMC Helix Innovation Suite SDK to build and deploy applications and/or libraries, after you receive
the notification, you must upgrade BMC Helix Innovation Suite SDK and any application projects that you created using
an earlier version of BMC Helix Innovation Suite SDK. Note that these steps are not required for pure codeless
development using BMC Helix Innovation Studio .
Tip
For more information about issues corrected in this patch, see Known and corrected issues (see page 20).
Before you begin

To avoid errors after upgrading to BMC Helix Innovation Suite SDK to 18.11.1, ensure that you have performed the
workarounds mentioned in upgrade considerations (see page 24).
To upgrade BMC Helix Innovation Suite SDK to 18.11 Patch 01
1. After you receive notification that your BMC Helix Innovation Suite has been updated, download the BMC Helix
Innovation Suite SDK ZIP file (see page 805)(com.bmc.arsys.rx.sdk-18.11.1.zip).
2. Make sure that you have Node.js version 10.7.0 and Yarn version v1.9.4 installed. If not, s ee To install Node.js .
(see page 804)
3. Rename your current SDK folder to create a backup.

For example, rename it to com.bmc.arsys.rx.sdk-18.08.1.BACKUP .
4. At the location where you want to install the SDK, create a new SDK folder and extract the BMC Helix Innovation
Suite SDK ZIP file (com.bmc.arsys.rx.sdk-18.11.1.zip).
5. Add an environment variable, RX_SDK_HOME, that points to the sdk folder location.
6. Find the .m2 folder (usually located in your user directory, such as %HOMEPATH%\.m2 on windows). Delete the
arsys and rx folders located there.
7. Install BMC Helix Innovation Suite SDK in your Maven repository by using the following commands:
\com.bmc.arsys.rx.sdk-18.11.1> cd lib
\com.bmc.arsys.rx.sdk-18.11.1\lib> mvn clean install
8. Update the archetype-catalog.xml file to delete the earlier archetype versions (for example, 17.5.0) and ensure the
archetype-catalog.xml has the archetype version as 18.11.1-SNAPSHOT.
The archetype-catalog.xml file might be located at following locations:
.m2
.m2/repository

For example:
<archetype>
<groupId>com.bmc.arsys</groupId>
<artifactId>rx-sdk-archetype-lib</artifactId>
<version>18.11.1-SNAPSHOT</version>
<description>Generate a Rx base library.</description>
</archetype>
<archetype>
<groupId>com.bmc.arsys</groupId>
<artifactId>rx-sdk-archetype-simple</artifactId>
<version>18.11.1-SNAPSHOT</version>
<description>Generate a Rx application that has login page, landing page, a few view definitions, and
some record definitions.</description>
</archetype>
</archetypes>
To upgrade your application or library

For each new SDK, you need to update the SDK version in the pom.xml file as in <rx-sdk.version>18.11.1-SNAPSHOT</rx-
sdk.version>.
If your application, or library, was created for release 18.8.0 or earlier, and you have not already upgraded it to 18.08.1 yet,
perform the following one-time steps after the latest SDK (18.11.1) is installed.
1. Make sure that your tools are updated to the correct versions, including the SDK (18.11.1).
2. Create a new dummy application or library using the maven archetype rx-sdk-archetype-simple. For more
information, see Creating a Project using Maven and the Archetype (see page 806) .
You are not required to build the application or library. The use of this application is only for temporary use and
hence for this upgrade name the temporary application as TempApp and refer the original application as MyApp.
Important
If you have any customizations to the build scripts created from an archetype, create a backup of
MyApp\bundle folder.
3. Delete the MyApp\bundle\node_modules folder.
4. Delete the MyApp\bundle\yarn.lock file.
5. Delete the MyApp\bundle\grunt\watch.js file.
6. Copy the following files from the TempApp folder to replace the files in MyApp folder.
Copy from To replace
TempApp\bundle\Gruntfile.js MyApp\bundle\Gruntfile.js
TempApp\bundle\karma.conf.js MyApp\bundle\karma.conf.js
TempApp\bundle\grunt\saas.js MyApp\bundle\grunt\saas.js
7. Copy TempApp\bundle\grunt\chokidar.js file to MyApp\bundle\grunt folder.

8. Edit the MyApp\bundle\package.json file to update the list within the devDependencies object to match the same
list defined in TempApp\bundle\package.json.
9. Rebuild your application using the 18.11.1 SDK.
To upgrade the UI automation project

If you are upgrading from 18.11.0 or earlier, add the following property to the properties.config file .
# If you want to use drivers of your own choice, download them in the folder called drivers and provide
define the driver location.
# If you do not want to use the drivers of your own choice, leave the driversLocation attribute as blank.
# For example, driversLocation=drivers -> this will pick up drivers.exe from drivers folder under the ui-
automation.
# driversLocation= -> By default this is set to blank. It then picks up drivers bundled in the ui framework
jars. These drivers are tested.
driversLocation=
Related topic
Getting started
BMC Helix Innovation Suite is a cloud-based offering available only through Amazon Web Services. If you are looking for
information on how to upgrade to this version, you should get in touch with the BMC Software Customer Support (see
page 993) team.
Click the following topic links to understand the product and get introduced to the new concepts.
Orientation (see Overview (see page For whom? (see Navigation (see page Architecture (see Concepts (see page Glossary (see
page 30) 36) page 743) 59) page 39) 36) page 52)
(see
(see (see page 743) (see (see (see
page 30) page 36) (see page 59) page 39) page 36) page 52)
Related topic
Securing BMC Helix Innovation Suite against web and CSRF attacks (see page 1022)

Orientation
Quick overview
BMC Helix Innovation Suite helps you to build your own applications with the help of different designer consoles, deploy
them for the end users of these applications, and manage or configure them. BMC Helix Innovation Studio helps you
establish data requirements, expose fields for your user interface, and implement complex powerful business processes.
BMC Helix Innovation Studio is based on a Model View Controller pattern, which helps you to separate database tables,
business logic, and user interface. You can upload the Digital Service applications and libraries developed in BMC Helix
Innovation Studio in a central repository, called Marketplace, from where other developers can download them for reuse.
BMC Helix Innovation Suite provides the following features to create applications and smart libraries:
Solutions for your business needs
Solve problems without substantial code changes
Apply new technology to products to enhance your products
Integrate with other applications
Create shareable code extensions
Product roles
BMC Helix Innovation Suite has simplified the day to day activities of different user roles. The product primarily aims at
simplifying the regular activities of the following roles.
Product features
BMC Helix Innovation Studio includes the following consoles that help you to achieve specific goals:

Console Used to customize...
Record designer The data model of an application
View designer The UI of an application
Process designer The processes of an application
Rule designer The business rules of an application
Association designer The associations between records of an application
Named List designer A list of name value pairs used in a drop-down menu of an application
Configurations The configuration settings of an application and BMC Helix Innovation Suite
Product documentation
The BMC Helix Innovation Suite documentation helps new and experienced users implement or use this product. Based
on your role, the following sections of the documentation are recommended:

User assistance
A number of channels are available through which the developer community can get support.
You can log on to BMC Developer community to get support from other developers using Developer portal
. Experts from BMC can help you out with your queries.
You can look at Developer portal to collaborate with like-minded developers. You can co-create, innovate, and
create applications (see page 798).
Access the tutorial (see page 66) to create a sample application.
If you are a Remedy developer, you can review the comparison between the Developer Studio and Innovation Studio (see
page 297) constructs.
Within BMC Helix Innovation Studio, you can use the In-App help to get oriented to the different consoles, you can use
tool-tips to get in-place assistance for populating fields, or you can take a tutorial that takes you through building an
application process.
Recommended skills set
For an administrator
An administrator can create codeless applications with minimal programming knowledge.
For a developer
For a developer to be able to work smoothly with BMC Helix Innovation Studio and codes, the following skills set is
recommended.
Maven
http://maven.apache.org/
Angular
http://angularbootcamp.com/

https://www.udemy.com/quickstart-angularjs/
https://www.udemy.com/angularjs-jumpstart/
https://www.udemy.com/angularjs-custom-directives/
Server Side App Development
Prerequisites:
Oracle University Java SE 8 Fundamentals (required)
Oracle University Java SE 8 Programming (recommended)
Read Building RESTful Web Services with JAX-RS tutorial
http://education.oracle.com/pls/web_prod-plq-dad/ou_product_category.getPage?p_cat_id=267
http://docs.oracle.com/javaee/6/tutorial/doc/giepu.html
Client Side App Development
Prerequisites:
Oracle University JavaScript and HTML5: Develop Web Applications (required)
Read online tutorial of JSON (required)
http://education.oracle.com/pls/web_prod-plq-dad/db_pages.getpage?page_id=609&get_params=dc:
D84842,clang:EN
https://www.w3schools.com/js/js_json_intro.asp
Video
The following video gives you information on developing applications:
https://youtu.be/N8ew_BwdbPY
Recommended training
Before you start creating applications, BMC recommends the following trainings:
https://www.udemy.com/quickstart-angularjs/
https://www.udemy.com/angularjs-jumpstart/
https://www.udemy.com/angularjs-custom-directives/
Additionally, refer to the Tutorial (see page 66).
Developer subscription process

The process for registering for the Developer program and getting access to the development environment is
summarized in the following workflow diagram:

Stage Description Who
Register The BMC Developer Program provides documentation and resources to build and deploy digital
Developer
innovations for your enterprise.
As part of the BMC Developer Program , you can request access to a personal developer sandbox that
includes Orientation (see page 30), APIs, and a library of reusable components.
To register for the BMC Developer Program, perform the following steps:
1. Open the BMC Developer Program .
2. On the BMC Developer Portal home page, click REGISTER.
3. On Developer Program Overview page, in the GET STARTED section, click REGISTER for the
Developer Program.
4. In Create BMC Account/Profile, select whether you are a current/future BMC Customer or Developer
or a current BMC Partner.
5. Provide your personal details, and submit the information.
For frequently asked questions about the registration process, see FAQs and additional resources (see page
1009).
On- After you register for the BMC Developer Program, you receive an email with login credentials for the BMC
Developer
board Developer Portal. Sandbox consists of BMC Helix Innovation Suite environment hosted on the AWS instance.
To get access to the Sandbox, perform the following steps:
1. Log in to the BMC Developer Portal and click Request Sandbox.
2. Enter the required details (like Developer ID, username, password) and request access.
You must provide the following details for the following user accounts:
Developer account
This account is required for accessing the BMC Helix Innovation Suite through the URLs that
will be included in the email sent to you when your sandbox is ready for use. The sandboxes
are as follows:
https://developerXYZ.innovate.bmc.com:443/com.bmc.arsys.rx.innovationstudio/index.
html
https://developerXYZ.innovate.bmc.com:8443/arsys

Stage Description Who
Here, XYZ will be replaced with the unique number of your Sandbox. Use the developer
account for working with the various modules of the BMC Helix Innovation Studio.
This account is also used to deploy your application to the server.
Administrator account
It takes around 15 minutes to generate your AWS instance. After the instance is generated, you receive an
email with the following details:
Sandbox information
Host
BMC Helix Innovation Suite URL
AR Java API Port
Field ID range
Bundle project configurations
webURL
rpcEndpoint
You can log in to your sandbox using the credentials that you provide requesting access to the sandbox. The
following operations are available for your instance:
Restart BMC Helix Innovation Suite
Restart Sandbox
Reset Password
Decommission instance
Unlock my Account
For resolving issues related to Sandbox access, see Troubleshooting Sandbox access issues (see page 980).
Learn After you register on the BMC Developer Portal, you get access to self-learning labs, recommended learning
Developer
content, and the product documentation necessary to bootstrap your developer experience. The following
links include the learning content: Application business
analyst
Learning Labs
User assistance (see page 30)
Recommended training (see page 30)
Develop After you receive access to Sandbox, you can start developing applications by using BMC Helix Innovation
Developer
Suite. The Developing and deploying code-based applications (see page 798) topic walks you through the
process of developing applications right from creating an environment to adding views, and fields. The topic Application business
also introduces you to the concepts that you should be familiar with while developing applications. analyst
Publish Share your application on BMC Developer Community .

Administrator
Related topics
Application development concepts (see page 36)
Developing and deploying code-based applications (see page 798)
Comparison between Developer Studio and BMC Helix Innovation Studio terminologies (see page 297)

Key concepts
Before you start building Digital Service applications, you should understand the concepts related to the applications.
This section provides information about understanding what is an application, difference between applications and
libraries, application attributes, how to start with application development, and the recommended process to develop
applications.
Action Reference
Review and understand BMC Helix Innovation Suite product features. Product overview (see page 36)
Get an insight into the anatomy and architecture of an application. Anatomy of a Digital Service application
(see page 37)
Digital Service application architecture

(see page 39)
Review the BMC Helix Innovation Suite licensing model. BMC Helix Innovation Suite licensing model
(see page 40)
Understand different types application definitions that can be customized. Configurable definitions (see page 41)
Understand the object definition scope concept and learn how defining a scope can be used to limit the use of Object definition scope (see page 43)
an application.
Learn about customization layer and the need to define a customization layer. Customization layer (see page 45)
Understand what a functional role is and how a functional role facilitates you to work on multiple applications Functional role (see page 45)
without mapping the user groups with roles.
Understand the concept of connectors and learn how to integrate third-party systems with BMC Helix Connectors overview (see page 50)
Innovation Suite.
Understand the concept in approval library such as, approval processes and approval flows. Approvals (see page 47)
Review BMC Helix Innovation Suite specific terminologies. Glossary (see page 52)
Product overview
BMC Helix Innovation Suite is currently available as a cloud-based offering. There is no on premises release of this
product at this time. It is a modern, low code development platform that helps the developer to achieve faster delivery of
applications. BMC Helix Innovation Suite empowers coders and non-coders to rapidly co-create powerful and Digital
Service applications with state-of-the-art user experiences in the cloud.
The key features of BMC Helix Innovation Suite are:
modern architecture to build applications
support for popular coding languages
intuitive drag-and-drop design tools
BMC Helix Innovation Suite consists of BMC Helix Innovation Suite SDK, BMC Helix Innovation Studio, and Component
Libraries. This version of BMC Helix Innovation Suite is catered to developers and is offered for free. This modern
platform is available for Remedy and non-Remedy developers.
Related topic
Key concepts (see page 36)

Anatomy of a Digital Service application

The Digital Service application or smart library that you develop is packaged as a smart bundle. The smart bundle
contains all the essential elements, which are required to deploy an application in BMC Helix Innovation Studio. This topic
explains in detail the anatomy of an application or a smart library.
Smart bundle details

A smart bundle is a Open Service Gateway Initiative (OSGi) JAR file, which may consist of JAVA classes, web files, JSON,
and templates.
A bundle consists of the following attributes:
Bundle ID
Version number
Author
Code (for example, Java, JavaScript)
Definitions
Data
Dependencies on other smart bundles
Licensing details
The code for an application development or a library development is packaged and deployed as a bundle. The following
image describes the code division and code development personas:

The code for client UI, UI extensions, and server extensions is created by a developer. The definitions for an application
are created by either a developer or an application business analyst.
A typical smart bundle consists of code for the following sections:
Data and definitions—Set of definitions that can be customized as per the business requirements without
modifying the application code.
Data/Definitions Description
Configuration data Configures the application behavior through data.
Application data Consists of data like record instances.
Definitions Configures application definitions using BMC Helix Innovation Studio, which provides the following features:
Provides a set of visual drag-and-drop designers
Creates and customize application definitions
Change application behavior without coding
This includes the following definitions and their capabilities:
Record definitions: Customize the data model of an application
View definitions: Customizes the UI of an application
Associations: Create or modify associations among record definitions
Named lists: Customize a list of name-value pairs used in a drop-down menu of an application
Processes: Customize the processes related to an application
Rules: Customize the business rules related to an application
Client UI—Client UI is a web application written in JavaScript or is a code for a mobile application that has REST-
based interfaces.
UI extensions—UI extensions are reusable client UI extensions that are known as view components (code in
JavaScript).
Server extensions— (code in Java)
Deployment package
Applications and smart libraries are deployed as deployment packages. Deployment packages are created in the
application development environment and are deployed by using Maven and the archetype. For more information, see
Deploying your Digital Service application for the first time to start working in BMC Helix Innovation Studio (see page 813
).
Comparison between application and library bundles

You can develop an application or a smart library using BMC Helix Innovation Suite. An application provides solutions for
your business needs. A smart library is a reusable set of components that can be used to develop an application. For
example, a PTO application may include an approval library that provides the elements required to create approval
process.
Application Smart library
Purpose Provides a complete set of business ready functionality. Provide a reusable building block for building applications.

Application Smart library
Target Remedy consumer who needs business functionality. Remedy consumer, partner, or a software developer.
consumer
Application It is available in the application switcher in the navigation bar of the It is not available in the application switcher in the navigation bar
switching user interface (UI). of the UI.
Entry point It has an index.html entry point. It usually does not has any entry point. All UI entry points are from
an application.
For example, Approval library.
Related topics
Configurable definitions (see page 41)
End-to-end process for developing your Digital Service application (see page 295)
Designing a Digital Service Application (see page 292)
Digital Service application architecture

Digital Service application architecture is based on the standard model which provides the following services:
Services that can be used from Java code
Services that can be called using a REST-style HTTP interface
Clients that consume these service through HTTP
The following image explains the architecture of an application:
The architecture of an application consists of the following elements:
Element Description
Application Libraries are the building blocks of an application. An application consists of a set of libraries that are defined in a bundle. A library is a
bundles and library collection of application components such as application services, record definitions, view components, field types, rules types, and so
bundles on. A smart bundle is a package used to deploy or install software to the BMC Helix Innovation Suite platform.
BMC Helix BMC Helix Innovation Suite platform is a set of technologies that supports the enterprise applications. The available features of BMC
Innovation Suite Helix Innovation Suite are as follows:
platform and
Java based platform
framework
services Standard based interfaces, including HTTP/REST

Element Description
Powerful built-in services and ability to create custom services
Configurable definition based objects
Built-in extensible types
Process orchestration engine
Custom services You can define a custom action that can be used to define a process. The process service can be used via REST API to create and
and REST APIs update process definitions.
Designer Web-based designer (various designers available in BMC Helix Innovation Studio) allows you to define and customize the data and
definitions required for the application.
Related topic
BMC Helix Innovation Suite licensing model

BMC Helix Innovation Suite enables developers to license the applications that are created by using BMC Helix Innovation
Studio. You can assign licenses to applications that are created by BMC, partners, and customers.
Licensing an application is beneficial in the following ways:
Control access to your application.
Protect the intellectual property of your organization.
Reduce management costs, and adhere to your organization's compliance policies.
When you license an application, a named license is available. The named license is always associated with that user name
and is reserved for that user. A named license enables a user to view, create, modify, and save the service requests.
Licensing model
The following table lists the application that you want to use and the associated license that must be assigned to the
user:
Application type BMC Helix Innovation Suite license Application license
Custom application Not applicable
BMC application Not applicable
Partner application Not applicable
To use a BMC or Partner application, only an application license needs to be assigned to the user.
To use a custom application, only the BMC Helix Innovation Suite license must be assigned to the user. After this
license is assigned, a user can access and use all the custom applications that are deployed in that system for a
tenant.
To log in to BMC Helix Innovation Studio, you must have administrator permission and BMC Helix Innovation
Suite User Named license.

When a SaaS administrator creates an administrator, the BMC Helix Innovation Suite license is automatically
assigned to the administrator. However, if the administrator creates a second administrator, then the first
administrator must manually assign the BMC Helix Innovation Suite license to that user. For more information,
see Assigning Innovation Suite license. (see page 759)
A BMC or partner-developed application can be set to have unlimited licensed users for all tenants. For such
applications, the SaaS administrator must assign at least one license to each tenant and unlimited users in that
tenancy can access the application.
Licensing workflow
The following illustration describes the workflow for licensing an application:
Where to go from here

Action Reference
If you are a developer, license your application by using Maven archetype. Applying a license to your application (see page 818)
If you are an administrator, assign licenses to users. Assigning application licenses to users (see page 759)
Related topic
Glossary (see page 52)
Configurable definitions
A Digital Service application is made up of data, definitions, and code. The data and definitions can be configured to suit
your application requirements. For example, if you have an application for on-boarding a new hire, the data required in
this application are the employee details such as first name, last name, employee ID and so on. How to display this data in
your application is determined by using definitions such as view definition, record definition and so on. An application
includes a set of such definitions that work with the application code and functions as per your requirements.
You can customize various functionalities and user interface of an application using the definitions through BMC Helix
Innovation Studio. The following image provides a brief categorization of the available definitions:

Data definitions
Data definitions represent the data model or schema of an application and define the data objects that it uses.
Data definitions are of the following types (the example of the on-boarding a new hire application is continued below):
Data Description Example

definition
Record Record is similar to a database table. A record consists Employee details, employee department, employee assets are different types of
of various fields. records you can create while on-boarding a new hire.
Field Field is similar to a database column. The first name, last name, employee ID and employee department are the different
fields of the employee details record.
Association Association defines the relationship between records. Employee details record can be associated to employee department record.
Named list Named list is a reusable query that returns a logically- You can create a named list for all the employees reporting to a particular manager.
named set of data and settings.
View definitions
Applications can be implemented to have any type of user interface as per your requirements. You can modify any
aspect of the application by customizing views. Views allow you to modify the following elements:
Arrangement of UI elements
Labels
Color themes
Add elements such as fields or attachments
Logic definitions
The behavior of applications can be defined and configured in multiple ways. You can also define rules, conditions,
approvals in your business processes. The standard features and elements of Business Process Model and Notation
(BPMN) are used in the Process designer. Some of the features and elements are listed below:
Flow of process activities
Conditional gateways

Nested processes
Integration points
Related topics
Defining record definitions to store and manage data (see page 324)
Defining the user interface through view definitions (see page 376)
Facilitating data entry through named lists (see page 417)
Defining the application business logic through processes (see page 421)
Adding rules to validate data or trigger events in a process (see page 490)
Object definition scope

BMC Helix Innovation Suite enables you to define a scope for the following object definitions:
Record definitions
View definitions
Process definitions
Rule definitions
Named list definitions
Association definitions
You can define the scope to either limit the use of definitions within the same application or allow the definitions to be
used outside the application. Defining the scope allows you to control the usage of the definitions by other developers or
consuming applications.
Definition scope is of the following types:
Application/Library
Public
The following table provides the details for each of the types:
Scope Description
Application
The definitions can only be used within the same application or library.
/Library
These definitions cannot be customized by a user of the application or accessed by custom definitions, even if the custom definitions are
within the same application or library.
The following diagram illustrates the concept of Application/Library Definition scope:

Scope Description
Public
The definitions can be used by all applications or libraries.
If a Public scoped definition uses an Application/Library scoped definition, any customizations for this Public scoped definition is not
allowed.
The extent to which the other Public scoped definitions (the Public scoped definitions that do not use Application/Library scoped
definitions) can be customized is decided by the developer. The customizations can be controlled by setting the customization options
for each definition. For more information, see Making definitions available for customization (see page 515).
The following diagram illustrates the concept of Public Definition scope:

Action Reference
Review and understand the best practices for defining scope Guidelines to define scope for the definitions (see page 319)
Allow customizations for the definitions Making definitions available for customization (see page 515)

Customization layer
BMC Helix Innovation Studio provides the required flexibility to customize out-of-the-box Digital Service applications by
using customization layer and custom objects.
A customization layer is a copy of the BMC Helix Innovation Studio structure or workflow object that is used in place of
the origin object, such as the out-of-the-box applications or definitions provided in BMC Helix Innovation Studio.
With customization layer, you can customize out-of-the-box BMC Helix Innovation Studio applications and objects or
create new custom objects, such as applications, record definitions, field definitions, process, and so on. The
customization layer ensures that the customizations are not lost when your application or server is upgraded.
Customization layer protects any new functionality that you add in your application.
All the customizations created by a tenant are restricted to that tenant and are saved in the tenant tablespace (tenant
database). Tenant-specific customizations are not available to any other tenants in the tenancy.
The customization layer provides the following functionalities:
The customization layers are created in a single hierarchy. You cannot create parallel customization layer with
same overlay group as parent group.
For all run-time operations, the changes are implemented with immediate effect after the customization is done.
All the customizations are created and tested in a tailoring environment. An administrator can then create an
update package for these changes and deploy the package to the production environment.
If you delete any out-of-the-box applications or objects, all the customizations created for that application or
object are deleted along with the data.

Use the information in the following table to navigate to the topic relevant to your goal.
Action Reference
As a developer, review and understand the best practices for customizing Guidelines for Digital Service application definitions customization (see page
objects 313)
Functional role
Functional role is collection of multiple application roles. A functional role allows the user to work on multiple
applications without mapping multiple groups to the application roles and assigning these multiple groups to the user.
Once you create a functional role, the server automatically creates a new group for the corresponding application role, if
the application role is not mapped to any group and maps the application role to the group. You can then assign this
functional role to a person to provide the required permission to the application.
Administrators can create their own functional roles to meet their specific business use case. To create a functional role,
see Creating Functional roles (see page 744).
The following diagram illustrates the concept of functional roles:

Benefits of functional roles

Functional roles provide the following benefits:
Provides application permission only to users. Functional roles do not provide permissions to object definitions,
such as record instances, view definitions.
Enables you to assign multiple application roles to a person. This provides the person with permissions to access
and use multiple applications.
For example, you can create a functional role Change Assignee which is a collection of multiple application roles
and provides the user permissions to access multiple applications such as, Knowledge Management, Change
Management, and Service Level Management.
Eliminates the need to create new groups and the mapping between groups and application roles. The server
automatically performs the task of creating a new group and mapping the group to the corresponding
application role. For more information, see Server behavior (see page 745).
Enables you to develop and test the application on one server and deploy it to a number of other servers without
having to redefine permissions on each server.
You can import functional roles to a different server, without the need to create groups and mapping the groups
to its application roles.

Leveraging conversation capabilities in BMC Helix Chatbot

BMC Helix Chatbot is a chatbot application provided by BMC, that allows users to interact in a conversational interface to
resolve their issues. BMC Helix Chatbot interacts with the user in a natural language to understand the conversation
context and based on that communication, reports issues, creates requests and cases, or searches for knowledge
articles.
You can configure BMC Helix Chatbot to work with BMC applications such as BMC Business Workflows and BMC Digital
Workplace Advanced. BMC Business Workflows uses BMC Helix Chatbot to create cases or search for knowledge articles
on behalf of the user. BMC Digital Workplace Advanced uses BMC Helix Chatbot to access services from the BMC Digital
Workplace Catalog or search for knowledge articles on behalf of the user.
Requesting BMC Helix Chatbot

To request access to BMC Helix Chatbot, contact your BMC Sales representative or Customer Support.
Using BMC Helix Chatbot

You can access the BMC Helix Chatbot in BMC Helix Innovation Studio. The BMC Helix Chatbot application is available on
the Workspace tab. The BMC Helix Chatbot configuration settings (Chatbot Configuration) are available on the
Administration tab.

Getting started in BMC Helix Chatbot documentation
Approvals
You can leverage the approval library to enable an approval process and functionality in an application. When enabled,
end users can submit approval requests and manage them in the Approval Console. Get started by understanding
approval processes and approval flows. See also Adding an approval process to an application (see page 536).
Approval process
An approval process defines logic, workflows, and required steps required for an approval request to get approved. It
facilitates the end-to-end execution of events from the time a user makes a request until the request is addressed (either
approved, rejected, or cancelled). Typically, for an approval process, a request record is the input and an approval status
is the output.
BMC Helix Innovation Suite supports cancellation of approval process for user-driven approval requests that are in
pending state.
For information about creating an approval process, see Creating an approval process (see page 537).
Approval flow types and example

An approval flow defines the overall completion criteria for the approval process. The completion criteria can include
simple or complex expressions that execute the approval process. Based on the business requirements, you can create
one or many approval flows of the following types:
Self approval flows, which are system-driven
Approval flows, which are user-driven

For example, consider an example where you need to configure a self-approval flow or an approval flow for meal
reimbursement requests from the sales representatives of your company. The following approval guidelines need to be
built into the reimbursement application:
I f a sales representatives spends up to USD 40, the request can be self approved automatically.
I f a sales representatives spends USD 60 or more on meals, the request can be approved by any sales manager.
I f a sales representatives spends USD 80 or more, the request must be approved by the direct manager of the
sales representative and two other sales managers.
If a sales representatives spends USD 90 or more, the request must be approved by the direct manager of the
sales representative and the finance manager .
Self-approval flows
An approval request with self-approval flows are automatically approved by the system without requiring an approver to
approve it. You configure self-approval flows when no user intervention is needed. Self-approval flows evaluate
preconfigured expressions and optionally call a self approval process before approving the request automatically.
You can configure self-approval flows in the following ways:
If you want the system to approve the request automatically without executing the self-approval process,
configure expressions, and set the precedence. The approval flows evaluates the expressions which when true,
the system automatically approves the request.
To evaluate additional expressions, such as whether the requester's position is allowed to self approve the
request, or to perform some additional tasks, such as updating a record, create a self approval process. You add
additional logic in the approval process and select it in the self approval flow. The system first evaluates the
expressions and then executes the self approval process. If the outcome of the self approval process is true, the
request is approved. If the outcome is false, the self approval flows continue to match rest of the self approval
processes until the request is approved or terminated.
For configuring self approval flows, see Configuring self approval flows (see page 544) .
Approval flows
Approval flows determine the specific person or group of people to approve a request. In approval flows, you can
configure expressions to validate conditions and select a single approver or a group of approvers. The approval flow can
select approvers from the Foundation data by functional roles or by the relationships defined between people, location,
or support groups. When you define an approval flow, you specify the type of approval: level up or general approval. And,
you can combine them in an approval flow group.
Level-up approval flows

Level-up approval flows evaluate the preconfigured expressions to validate conditions, checks approver levels, and route
the approval request to each approver in the hierarchy. These are also called as manager approvals. In the hierarchy, you
can specify the number of approver levels that approve the request. A requester's managerial hierarchy is determined
from the Foundation data for the organization. When the request is submitted, it goes through a series of approvers in
the hierarchy before getting approved.
Returning to our example where the request must be approved by the manager of the sales representative and two more
manager's in the hierarchy, a request would be handled as follows by a level-up approval flow:

Level-up approval case 1: If you specified the number of levels as three, the approval request is sent to the
requester's manager. After the request is approved, it is sent to the manager's manager, and then the next level. If
the requester's manager rejects the request at any level, the system terminates the request and further approval
requests are not generated for the next levels.
Level-up approval case 2: If you specified the number of levels as three, and, if either the requester is not defined
correctly or the requester does not have any manager associated to him, the approval process results in an error
and the system does not approve the request.
Level-up approval case 3: If you specified the number of levels specified as three, the approval request is first sent
to the requester's manager. If the requester's manager approves it, then the request is routed to the next
subsequent level. If there is no manager for the first-level manager or no manager at the next levels, the request is
still approved.
General approval flows

I n general approval flows, you configure expressions and select a single approver or a group of approvers. These
approvers can be selected from the foundation data. With use of foundation data, t he approvers can be found either by
functional roles or by the relationships defined between people, location, or support groups.
In general approval flows, while selecting approvers, users can now filter approvers from the foundation data. Users can
apply filters to the functional roles, business units, support groups, person, location, and so on.
This helps in narrowing your selection to an approver belonging to a business unit or functional role, instead of the
whole business unit or functional role
For a general approval flow, you specify whether one or all approvers must sign as follows:
One must sign—One approval request is created where all approvers have permissions to approve or reject. As
soon as the request is approved or rejected by any one of the approvers, the request is closed.
All must sign — Approval requests are created for each approver. After each approver approves the request, the
request is closed.
For configuring Approval Flows, see Configuring approval flows (see page 546) .
Approval flow group

Approval flow groups are a collection of approval flows —level up and/or general approval flows . Each approval flow
group can have one or many flows. You can create one or many flow groups. Each flow group is tied up with an approval
process and is specified in the approval process definition at the time process creation.
Approvers types
You can specify one of the following type of users as the approver:
Individual user—Select an individual approver from the Person Foundation data, or select a field from the record
definition.
For more information about Person Foundation data, see Creating or modifying Person data (see page 664).
Group of users—Select approvers that belong to an application role or a functional role; all user account that are
a part of the selected role are designated as approvers. Group configuration is beneficial when new users are
added or existing users' roles are modified frequently in your organization. Use of foundation data is supported
so that users can select approvers from the foundation data instead of using exact values. The approvers can be

found either by functional roles or by the relationships defined between people, location, or support groups.
For more information, see Creating and modifying application roles (see page 749) and Functional role (see page
744).
Approval chaining
In approval chaining, when one approval process is complete, another process is triggered based on the outcome of the
first process. You configure the chaining of processes using the approval wizard. Chaining requires you to configure two
or more approval flow groups and configure processes for each of these flow groups. The processes can be approval
processes or any other processes.
Returning to our example where , the request must be approved by the sales manager and the finance manager , you
must define two approval process and two flow groups, one for the sales manager and one for the finance manager.
When the sales representative submits an approval request, first the sales manager approval process is executed. If the
request is rejected, the process is terminated. If the request is approved, the finance approval process is executed.
For information on how to configure approval, see Creating an approval process (see page 537) and Configuring
approval flows (see page 546).
Connectors overview
By using a connector, you can integrate your application with a third-party product, which can be a service or an
application. A connector acts as a bridge between your application and the third-party product. You can integrate your
application with external systems by using connectors without having to perform any changes to the application code.
You can develop connectors to listen for events, perform tasks, or query for information. You can develop connectors
that perform only synchronous actions. You cannot develop connectors with triggers.
You can develop connectors by using BMC Helix Innovation Suite and BMC Integration Service. The BMC Integration
Service provides an integration layer and tools that you can use to build connectors. The BMC Integration Service
enables different applications to connect seamlessly with applications that are either hosted on cloud or running on
premises.
For information about BMC Integration Service, see BMC Integration Service documentation.
Notes

When you request a sandbox (on the Developer Portal), you are provisioned with an integration
account. You can use this account to access the integration tools such as BMC Integration Studio and
BMC Connector Designer.
If you already have a sandbox, you receive an email notification that contains the integration account
details when your sandbox is upgraded.
Connector development process

The following graphic provides an overview of the connector development process. It describes the roles involved, steps
required, and the tools used in connector development and connector utilization.
Role Action Reference
Developer Sets up the connector development environment Deploying your Digital Service application for the first time to start working in
BMC Helix Innovation Studio (see page 813)
Developer Develops and tests connector Developing connectors
Developer Deploys the connector Configuring connectors
Administrator Creates connector configurations Adding or updating a configuration
Administrator Creates connector profiles Adding connector configurations (see page 616)
Administrator Performs alias mapping of connector actions with Creating alias mapping of the connectors (see page 623)
connector configurations
Application Creates a process or rule to integrate a Digital Service Automating categorization and assignment of application requests (see page
business Analyst application with external resource 478)
Application Tailors the Digital Service application Tailoring applications (see page 322)
business Analyst

Role Action Reference
End user Uses Digital Service application that leverages

connector
BMC Helix Innovation Suite provides out-of-the box connectors to integrate your applications with third-party products.
You can use these connectors in your application processes and rules. In the Process designer and Rule designer, these
connectors are available as a Connector property of the Connector element.
Example: To integrate your application with a JIRA project repository

You can develop and use a connector to integrate your application with a JIRA third-party product repository by
completing the following tasks:
Task Role Description
Develop Developer The connector for this integration is called JIRA connector.
connector
Develop the JIRA connector by using the tools - BMC Connector Designer and BMC Integration Studio.
Create JIRA connector actions such as create issues in JIRA, add comments in JIRA, and so on.
Deploy the JIRA connector to the BMC Integration Service.
Configure Administrator Create the connector configurations and profiles in BMC Integration Service so that the connector can communicate
connector with the third-party system. After the JIRA connector is configured, it is available in BMC Helix Innovation Studio for
use.
For information about creating connector configurations and profiles, see Adding or updating a configuration and
Adding accounts i n BMC Integration Studio documentation .
Build a process Developer or Integrate your application by creating a process or a rule that consists of the JIRA connector element. You do not
or rule to Application need to add a JIRA code specific to your application code.
integrate business analyst
For information about integrating your application with third-party systems, see the following topics:
Integrating applications using process connector element (see page 617)
Integrating applications using rule connector element (see page 620)
Glossary
A (see page 53)
B (see page 54)
C (see page 54)
D (see page 54)
E (see page 55)
F (see page 55)
H (see page 56)
I (see page 56)
J (see page 56)

L (see page 57)
N (see page 57)
O (see page 57)
P (see page 57)
R (see page 58)
S (see page 59)
T (see page 59)
U (see page 59)
V (see page 59)
The following glossary contains terms that are relevant to BMC Helix Innovation Suite:
A
Term Description
accuracy In BMC Helix Innovation Suite Cognitive Service, accuracy is the ratio of number of correct predictions to the total number of input samples.
For example, if the test results indicate that 9 out of 10 variations of increase RAM request are correctly predicted, the accuracy is 9/10 = 0.9.
action A predefined view component available in the View Designer, that lets you perform an action in a view definition. For example, you can create
button action buttons in a view definition for saving the view, deleting a record instance, launching a URL, and so on.
alias An alias is a placeholder for a tenant-specific configuration for connectors or RESTful services.
ancestor A top-level group within the hierarchy, with one or more subgroups associated with it. An ancestor group can be attached to one or more user
group groups.
application A type of bundle that provides business functionality to the users. Remedy customers, partners, and software developers who need business
functionality can create and use applications.
application A license that is application-specific and is required for using an application.

license
application A definition which is used only within the same application and within the same customization layer in which the definition is created. This
scoped definition cannot be customized by a user of the application or accessed by custom definitions, even if the custom definitions are within the
definition same application.
association An association lets you define a relationship between the record definitions. While creating a record association, you specify the cardinality and
the constraint for the association.
A cardinality lets you specify the type of relation between the records within the association. For example, one-to-one, one-to-many, and
many-to-many.
A constraint lets you specify the limitation for an association. For example, automatic deletion of the associated records. If a second
record is associated with the first record, and you delete the first record, then the second record should be deleted automatically.
association Defines relationships between records and relates record instances.

service
assignment Specifies the sequential rules for automatically assigning the application requests.
policy
assignment Specifies the rules for identifying the correct assignee when automatically assigning the application requests. The assignment rules are based on
rule foundation data. As per the assignment rules, BMC Helix Innovation Suite identifies the correct assignee for the request. If multiple assignees are
available, the predefined assignment methods (see page 624) are used to identify an assignee for the request.

Term Description
assignment Defines and executes the business logic as a flow of usable set of activities and conditional gateways for assigning requests. The assignment
process process trigger the assignment rules.
audit A read-only record that gets created when the record auditing is enabled. Whenever the source record is modified, BMC Helix Innovation Suite
record records the audit data from the source record to a new read-only audit record.
B
Term Description
BMC An application having Author Type value as 1, which is assigned by a developer using Maven license command.
application
BMC A special built-in configurable View that exists for all Application bundles. It is used as the outer container of an Application that creates an
Modern entry point for users to access the application on the Web.
Shell
bundle A bundle consists of the following properties:
Contains
Java code
JavaScript code
Definitions
Roles
Data
Depends on other bundles
Is licensed
bulk data The process of copying the Foundation data sets from template Excel spreadsheets and loading the data sets to BMC Helix Innovation Suite.
loading
C
Term Description
container A built-in view component available in the View Designer, that lets you define the layout for a region of a view that can include view components
or nested containers.
content Provides access to complex document types and rich media

service
context A context key is a unique identifier that you can assign to a process instance. You can use the context key to identify a process and to find out
Key the context in which the process is activated. Typically the context key is set by means of a process input parameter with some meaningful value.
For example, an Approval Process that has a context key as HPD0002340 indicates that the Incident request HPD0002340 started the Approval
Process. A context key can be a text value or a record type only. You can search a process instance using the context key. Once the system
displays all process instances
custom An application having Author Type value as 3, which is assigned by a developer using Maven license command.
application
D
Term Description
Developer ID

Term Description
Uniquely identifies the organization creating the smart bundle. Each organization developing a Digital Service application must have a
Developer ID. When you create a Bundle project using archetype, a Developer ID is assigned to the smart bundle by the archetype.
Every definition deployed with the smart bundle has a Developer ID property which is used to identify the organization that creates the
definition.
Data BMC Helix Innovation Suite provides a Data Caching Service (com.bmc.arsys.rx.services.cache.CacheService) to enable applications to cache
Caching data, metadata, and configuration items. The cache is created during application deployment and when the data entries are created.
Service
dedicated A single tenant environment is renamed to dedicated system. A dedicated system is an environment that contains only one tenant identified
system by the tenant's domain name, such as example.com.
deployment A zip file containing the compiled OSGI bundle jar and the bundle's definition file. It is produced using the maven "package" command.
package
descendant A child group within the hierarchy, that is attached to an ancestor group. A child group can be attached to only one ancestor group.
group
development Once a bundle is compiled and packaged using the maven commands, it's Deployment Package is deployed to a development server using the -
deployment Pdeployoption.
development A dedicated system with a configured developer-id, ready to be used for Development Deployment of bundles. Such a system is NOT used for
Server production use.
direct BMC Helix Innovation Suite Foundation library, direct affiliation is an association between two foundation data elements where the one
affiliation foundation data element is a part of or associated with the second foundation data element.
For example, when you create a direct affiliation between person and support organization such as Support Groups, the affiliation implies that
the associated person works for, or reports to the manager of the support organization and performs task for that support organization.
E
Term Description
export package A package created by using BMC Helix Innovation Studio, which contains only the customized definitions and configuration data. You
cannot include application code in an export package.
The export package is used by administrators to deploy the application's tailoring changes only to test or production environments.
extension record A regular record definition with fields that you want to add to the record definitions and view definitions that are not customizable.
definition
extension view A view definition that displays the fields added in the extension record definition and the fields in view that is not customizable (view
definition that is being extended).
extension A direct association between the extension record definition and the record definition that is not customizable (record definition that
association is being extended).
definition
extension Container A view component that can be added to the view that is not customizable (view that is being extended).
F
Term Description
framework Framework services are a set of services and extensible objects that allow you to access Remedy Platform capabilities using REST-based API and
services provide the ability to extend the platform with custom behaviors using Java and JavaScript. Each of these services define a collection of REST-ful
resources accessible through the Remedy Platform REST API.
F-score In BMC Helix Innovation Suite Cognitive Service, F-score is the harmonic average of precision and recall. F-score reaches its best value at 1
(indicating perfect precision and recall) and worst at 0.
Traditionally, F-score is calculated as F = 2 × (Precision × Recall) / (Precision + Recall)

H
Term Description
hierarchical Defines the relationship of user groups with each other and rank them according to the level of importance or authority. A hierarchical group is
group headed by an ancestor group with descendant groups beneath it. At each level above the bottom of the hierarchy, the descendant groups
themselves can be ancestor groups.
I
Term Description
index In a record definition, an index is a list of record fields that are frequently searched. Indexes reduce the database search time and optimize the
performance of your Digital Service application by returning search results faster. You can index the fields that users frequently search for.
However, you should use indexes carefully, as adding too many indexes to a single record definition may lead to performance degradation.
For example, a record definition for 'Task' can include an index based on the 'Assignee' field.
indirect In BMC Helix Innovation Suite Foundation library, an indirect affiliation is an association between two foundation data elements where the one
affiliation foundation data element is not a part of or not associated with the second foundation data element, but can access data from the second
foundation data element
For example, when you create an indirect affiliation between person and support organization such as Support Groups, the affiliation implies
that the associated person does not work for, or reports to the manager of the support organization but performs task for that support
organization.
inner join This type of join record combines only the matching data from multiple records. An inner join searches for fields that have corresponding
record values in the multiple records and then combines the matching data to form a join record. If a field does not have a corresponding value in any
one of the record, then that field is omitted from the join record.
BMC Helix This is a one-time platform license required for using BMC Helix Innovation Studio.
Innovation
Suitelicense
BMC Helix A zip file containing the Java libraries and maven infrastructure to build and deploy projects onto a Development Server. Indirectly it includes
Innovation API documentation and sample code as well.
Suite SDK
Install A package created from BMC Helix Innovation Studio, which contains the entire application data, such as code, definitions, and configurations.
package The install package is used by application business analysts or developers to:
Deploy an entire application to a test or production environment
Deploy an application to another development environment for collaborative application development.
J
Term Description
join A join record definition is a combination of data that is retrieved from multiple record definitions. Join record definitions are similar to database
record joins.
Join records lets you perform the following operations:
Retrieve data from multiple records
Specify the criteria for retrieving data from multiple record definitions
View or edit record fields of multiple record definitions at the same time
Join records are further divided into the inner join or outer join records.

L
Term Description
library A type of bundle that provides a reusable building block for developing applications. A library is a subset of an application. Remedy customers,
partners, and software developers who are building applications can create and use libraries.
library A definition which is used only within the same library and within the same customization layer in which the definition is created. This definition
scoped cannot be customized by a user of the application or accessed by custom definitions, even if the custom definitions are within the same library.
definition
N
Term Description
named list A reusable list of data that you can associate with a record field to make data entry faster and more accurate.
definition
named list Provides the specified set of valid options for the record fields.
service
named This license is always associated with a user name and is always reserved for that user. A Named user license enables a user to create, modify,
license save requests besides reading the requests.
node side Node Side is a parameter used for disassociating one-to-many record instances. Node Side specifies the left side or right side record definition
in an association. There can be only two values for the Node Side parameter:
Node A: Left side record definition in the Association
Node B: Right side record definition in the Association
O
Term Description
opt in Provides a choice to the administrator to consume the new version of an application in a test environment.
opt out Provides the ability to the administrator to roll back to the previous version of an application in a test environment.
P
Term Description
palette The available types of behavioral tasks, flows, and other elements that can be used in the Process Designer.
partner An application whose Author Type value is 2, which is assigned by a developer using Maven license command.
application
precision In BMC Helix Innovation Suite Cognitive Service, precision is the number of correct positive results divided by the total number of relevant
samples.
For example, for a search query that contains Calbro Services, the system returns 10 results that contain both Calbro and Services and 8 of
those results include the phrase Calbro Services. In this case, the precision is 8/ 10 = 0.8.
process An application service that performs application business logic and achieves the application purpose.
definition
process Defines and executes the business logic as a flow of are usable set of activities and conditional gateways.
service
production A Deployment Package is deployed to a Production Server using the BundleDeployment.bat utility, where it can then be configured and
deployment tailored.
production A shared system ready for Production Deployment of bundles, and configuration / tailoring by administrators. This system is not used for
server development.

Term Description
public A definition which is used by all applications or libraries. The definition can be customized by configuring the customization options for the
scoped definition.
definition
R
Term Description
recall In BMC Helix Innovation Suite Cognitive Service, recall is the number of correct positive results divided by the number of positive results
predicted by the cognitive service.
For example, for a search query that contains Calbro Services, if the system returns 10 results that contain both both Calbro and Services and 8 of
those results include the phrase Calbro Services, the precision is 8 out of 10. If 20 more instances are related to Calbro Service, the recall is 8 out
of 30.
record A built-in view component available in the View Designer, that lets you create record instances or modify existing record instances from the view
editor definition.
record Record Editor Inputs are used to add the record fields to the record that is associated with the record editor.
editor
inputs
record Units of information that collectively form a record definition. A single record definition consists of multiple fields, and each field has its own
field attributes.
For example, a 'Task' record definition can consist of the following fields:
Task ID
Assignee
Description
Submitter
Status
Due date
record A built-in view component available in the View Designer. Record grid is used to display the record fields in a tabular format on the user interface
grid of the application.
record Record instance is the data created by the application for which the structure of the data is specified by the record definition.
instance
For example, a 'Task' record definition can consist of the following record instances:
Assigned to: Seth
Priority: Critical
Status: In Progress
Due date: 20-6-2016
record Defines business entities of a data model.

service
Manages record instances by performingSCRUD(Search, Create, Read, Update, Delete) operations on data
records A record definition is a collection of the data required for building the application for your business process. A record definition is made up of
definition specific record fields.
Any important task in your organization's business process can be stored as a record.
rule A rule, along with a process, models the business logic of an application. The purpose of a rule is to perform data validation, and interact with a
definition process on record events or timer events.
rule Defines conditions with certain actions to enforce business constraints.

service

S
Term Description
security In a hierarchical group, a security label is used to dynamically control record and field access. The label can be populated with group names through
label a rule or a process. Security labels protect your database tables at the row level, by assigning different levels of security. Only those users with the
appropriate permissions can access the row data.
For example, in a car dealership company, you create security labels like car type, sales group, or dealership, and only users with the appropriate
security classification are allowed access to the relevant data.
scope Defines if the application is limited to be used within the Digital Service application or library or can be used by any other application or library.
shared Multitenant environment is renamed to shared system. A shared system is an environment that includes one or more tenants identified by their
system domain names for each user, such as example.com and example1.com.
T
Term Description
tailor Customize the smart bundle to suit your environment and business requirements. The following tasks are involved when you tailor a smart bundle:
Apply new themes by changing the application logo, color, or brand
Modify the business process model
Manage records by creating new records or editing the existing records
Modify the elements on the application
Edit the business rules thereby modifying the business processes
U
Term Description
update A package created from BMC Helix Innovation Studio, which contains only the incremental changes for an application. Importing configuration
package data is optional.
The update package is used by application business analysts or developers to:
Deploy incremental changes of an application to test or production environments.
Can use the update package to deploy incremental changes for coded or codeless application to a test or production environment.
V
Term Description
view A configurable UI widget that can be composed with others and configured in the View Designer. These can be built-in or custom Javascript
component extensions.
view In BMC Helix Innovation Studio, a view definition is a graphical representation of your application. You use the view definitions to design the
definition user interface for applications. For example, a view definition called Tracking Item, which will be used to create and update Item Console
records.
view Defines the user interface of a standard application.

service
Navigating BMC Helix Innovation Studio

BMC Helix Innovation Studio is a graphic-based interface used to develop and tailor Digital Service applications or
libraries. BMC Helix Innovation Studio provides designers that can be used to create views, records, and business logic
for an application or a library.

BMC Helix Innovation Studio UI includes the following tabs:
Overview of the Workspace page (see page 60): Displays all applications and libraries that are deployed in BMC
Helix Innovation Studio
Overview of the Administration page (see page 61): Provides interface to manage application or library
configurations
To access the BMC Helix Innovation Studio

After you have created and deployed an application, you can view and access the application in BMC Helix Innovation
Studio.
After you log in to BMC Helix Innovation Studio, a welcome screen appears and the Workspace tab opens by default.
Overview of the Workspace page

In BMC Helix Innovation Studio, the main navigation bar appears at the top of each page and provides menus that help
you navigate the application.
The following image shows the UI elements on the Workspace page:

The Workspace UI elements in the image are explained in the following table:
Annotation Element name Description
1 Workspace Displays all applications and libraries that are deployed in BMC Helix Innovation Studio.
2 Administration Displays the Administration page, where you can perform administrative tasks such as managing tenants and services.
3 Help Displays the help topic for that page.
4 Service Provider Enables you to switch between the overlay groups that are available in BMC Helix Innovation Studio.
5 Demo user for startup Displays the login name of the user account.
6 All Displays a list of all applications and libraries that are deployed in BMC Helix Innovation Studio.
7 Applications Displays a list of all applications that are deployed in BMC Helix Innovation Studio.
8 Libraries Displays a list of all libraries that are deployed in BMC Helix Innovation Studio.
Overview of the Administration page

The Administration page provides configuration settings to manage BMC Helix Innovation Studio.
The Administration UI elements in the image are explained in the following table:
1 Hide Settings Hides the navigation pane temporarily.
To view the navigation pane, click the arrow.
2 Search Searches for a configuration

Configuration
Enter a configuration that you want to search, for example, Tenant. A list of all the configuration names containing the term
Tenant are displayed.
3 Configuration Displays all the fields that you can configure for the selected option
area
Overview of the application or library page

From the Workspace page, you can click any application or library. On the application or library details page, you can
view and customize the definitions by using different designers.

The application or library UI elements in the image are explained in the following table:
1 Translations Enables you to localize—that is, change the language and locale settings—of your smart bundle, application
definitions, and data.
After you localize a smart bundle, you can view the application UI and error messages in the preferred
language.
2 Visit Deployed Application Provides a visual representation of the application after it is deployed in BMC Helix Innovation Studio.
3 Edit Enables you to create the header and navigation for an application with inbuilt navigation and framework
services by using BMC Modern Shell.
4 Records Provides the following capabilities:
Create or modify record definitions
Customize the data model of an application
5 Views Displays the Views designer, which provides the following capabilities:
Create or modify view definitions
Customize the UI of an application
6 Processes Displays the Process designer (see page 63), which provides the following capabilities:
Create or modify processes
Customize the processes related to an application
7 Rules Displays the Rules designer (see page 491), which provides the following capabilities:
Create or modify rules
Customize the business rules related to an application
8 Associations Displays the Associations designer, which enables you create or modify associations among record
definitions.
9 Named Lists Displays the Named Lists designer, which enables you to customize a list of name-value pairs used in a drop-
down menu of an application.
10 Configurations Displays the Configurations designer, which enables you to specify configuration settings and configuration
functions for an application.

Setting the UI preferences

In BMC Helix Innovation Studio, you can set the UI preferences by performing the following steps:
1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
2. Select General > UI preferences.
3. To add new preferences, click the + icon, enter the details in the required fields, and click Save.
4. To delete an existing preference, click icon.
Tip
If you have modified a UI preference, to view the modifications refresh or re-login to BMC Helix Innovation
Studio.
Related topics
Orientation (see page 30)
Product overview (see page 36)
Roles and permissions (see page 743)
Digital Service application architecture (see page 39)
Process designer interface

Process designer helps you to design processes for your Digital Service application. Process designer is a visual tool is
based on Business Process Model and Notation 2.0 (BPMN) standards. It has elements that can be dragged and dropped
on the canvas to create a process. You can also extend the existing Process designer and add your own functionality as
suited to your business requirement.
Process designer works in conjunction with other designers of the BMC Helix Innovation Studio such as the record,
association, and rule. All the artifacts created by other designers are brought together in the Process designer while
creating a process.
A process uses records created from Record designer to carry out a task defined in the process. For example, if
you are creating an Employee Onboarding process, the new employee details such as name, last name, employee
ID are the different records created in the Record designer.
A process uses associations to perform record instance navigation and to navigate to associated record
instances. For example, while working on a change management process you can navigate from the Change
record to the Customer record, without changing the record context.
Process designer features

Here are some key features of Process designer:

Visual designer - It is a visual workflow designer tool that requires minimum knowledge of coding or
programming. As the processes are displayed on the canvas, it improves communication on describing the
business procedures. You can see the process flows runtime, thus giving improved supportability. You can build
processes by easily dragging and dropping elements on the Process designer palette.
Process Dashboard - The Manage processes tab is a dashboard of your business activities. Using this dashboard
you can search and view all the processes defined in the Process designer. You can also view the details of Active,
Suspended, Completed and Failed processes. There is also an option to perform actions like suspend, resume, or
cancel processes from here.
The Process designer being a powerful tool can help you design with very complex business processes with ease. Using
this visual designer you can:
have multiple processes interact with each other,
have multiple processes embedded in a bigger process.
To access the Process designer
1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
2. Select the application in which you want to create a process.
3. In the application, click the Processes tab, and click New.

The Process designer is displayed.
Process designer interface details

The following image describes the Process designer interface:
Annotation Name Description
1 Palette Contains tabs to manage process elements and search options for process elements.
2 Process Contains process elements that you selected from the Manage Palette tab.
Elements
3 Favorites Contains process elements that you marked as favorite in the Manage Palette tab.

Annotation Name Description
4 Recent Contains elements that you used recently to create a business process.
5 Manage Contains a list of all process elements that Process designer offers. You can mark these elements as favorites or select only those
Palette that you want BMC Helix Innovation Studio to display on the Process elements tab.
6 Process Contains tools for common operations such as zoom, clear canvas, and adjust canvas grid.
Tool bar
7 Process Contains information about the process such as process name and parameters and permissions assigned to the process.
Information
8 JSON Shows JSON of the process definition. It is for troubleshooting.
9 Element Shows properties of the selected element that is used in the process design.
Information
10 Process Shows warnings if the process is invalid for any reason.

Validation
11 Canvas Is the area where process elements are placed to design the process.
Related topics
Process designer elements (see page 429)
Managing processes by using the Manage Processes dashboard (see page 474)
Rule designer interface

Rule designer provides drag and drop elements that can be used to create a business rule. You can use the Rule designer
to create or tailor a business rule.
Note
You can customize the objects developed in your own applications, but cannot customize the objects
developed in com.bmc.arsys. For example, objects in core BMC applications like Foundation, Approval, and
Assignment cannot be customized.
To access the Rule designer
2. Select the application in which you want to create a rule.
3. In the application, click the Rules tab, and click New.

The Rule designer is displayed.
Rule designer interface details

The following video (1.34) describes the Rule designer interface.
https://youtu.be/Gd2lifwL-AA

Related topics
Rule designer elements (see page 491)
Creating rules (see page 493)
Tutorial
As a developer you build solutions to solve complex business problems. When you first start a development project, you
should thoroughly understand the business need, and design a solution to meet that need. Fortunately, we've already
done the heavy lifting for you.
The BMC Helix Innovation Suite is an end-to-end framework that provides the enterprise features you need. Applications
built using the BMC Helix Innovation Suite begin with an enterprise ready data management back end, authentication
model, and security framework, leaving you with more time to design and develop solutions to meet your business goals
and objectives.
This tutorial is a series of exercises to guide to through building an application to meet a typical business use case. You
will begin by quickly building a simple code-less application end-to-end. Then you will analyze a more fully featured
version of the application, including custom Java and Javascript code, and build that. The application is simple, and
designed to give you a broad understanding of the features in a progressive, meaningful way.
It may be best to follow the modules in order to grow your knowledge incrementally. If you choose to explore the BMC
Helix Innovation Suite on your own, start with the Orientation topic to understand the application that you will build.

Module Description
Orientation - building a simple In this introductory module, you will get a quick hands-on lesson in creating your "first" application, including a single
application for BMC Helix record, view, process, and rule to submit and track a lunch order. then we will consider how to analyze a real business
Innovation Suite (see page 67) problem to extend our application using BMC Helix Innovation Studio.
Module 1 - Developing a full In this module, you will develop the initial data model, user interface, and business logic based on your design, with the
solution to the lunch ordering end result being a working application.
problem (see page 95)
Module 2 - Extending your In this module, you will add a Java-based service to a new, coded library to extend the application's backend features. You
Solution in Code (see page 202) will also create JavaScript components using AngularJS code to customize the application's user interface.
In this module, you will get your application ready for release, and learn how to go about creating an update for it.

Module Description
Module 3 - Packaging, releasing,

and, upgrading your solution (see
page 254)
Orientation - building a simple application for BMC Helix Innovation Suite

BMC Helix Innovation Suite, as a platform for developing business applications, has many capabilities. The best way to
learn about them is to develop a simple application yourself. This tutorial is exactly such a walk-through: we will build a
simple application that allows someone to order lunch from a menu for a set of employees in a company. It will span the
entire process of building the application, including:
This Orientation - getting familiar with BMC Helix Innovation Studio, and then analyzing the full requirements and
design
Module 1 - building the full application without writing any code
Module 2 - enhancing the application with a library of Java and Javascript code
Module 3 - finalizing a release of the application and preparing updates
Prerequisites
You can build the quick-start application in the Orientation, and the full application in Module 1, using only:
A working instance of BMC Helix Innovation Suite
A browser
Modules 2 and 3 can be used as information resources to learn about developing using custom code and the BMC Helix
Innovation Suite SDK. If you want to compile the sample project and extend it yourself, you will need to install additional
development tools that will be documented in that part of the tutorial.
Methodology for a solution

Normally, before beginning development, you would consider what kind of development methodology to use. BMC Helix
Innovation Suite applications are very “definition driven”, so the temptation is to dive right in and start creating those
definitions. Two recommendations here are:
Make sure you understand enough about the problem space before you start.
For analyzing the solution before you begin, its often best to work “outside-in”, starting from the users’ point of
view, and getting to the details of the implementation toward the end of your analysis. For example, the data
model should really define exactly what the Process and Views require.
When actually implementing, the dependencies flow the other way. You must in fact have the data model defined
in order to do much with Views. You may also need to have Views defined in order to build and test the business
process.
The following diagram represents this rule of thumb conceptually, and also the basic order we will follow in this tutorial.
This can be described as, "analyze from the outside-in, and build from the inside-out".

Ready for a quick start!

As we follow a journey through developing the application, we will walk through every step of this methodology.
However, it will be great to get some hands-on experience with our primary tool, BMC Helix Innovation Studio. For that
reason, we will post-pone the full analysis and design until we have quickly created a very simple "first pass" at a lunch
ordering application.
Quick start: creating a simple app to order some lunch
What we will do
In this module, we will quickly build a very simple application with BMC Helix Innovation Suite - just about the simplest
one that touches on all the major elements of this platform. Of course, I'm talking about process, view, and record. The
idea here is to help folks get their hands on BMC Helix Innovation Studio to do something useful, without diving into any
power features or even real-world use cases. You could consider this exercise like the proverbial "Hello, World!"
application inspired by the "C" programming language, although this application will do a bit more than just print out a
greeting.
Because this could be your very first experience of BMC Helix Innovation Studio, for this particular exercise only, every
step is going to be elaborately spelled out for you to follow. Don't worry, as we get a little further into the tutorial, and as
you are presumed to have the hang of using the BMC Helix Innovation Studio designers, the steps in this tutorial will be
described in a much less detailed way.
What you will need

In terms of skills, no experience of BMC Helix Innovation Suite, or any other development platform for that matter, is
required. As mentioned above, you do not need to have consulted documentation for Developing applications (see page
794), but it will not hurt, and you will certainly want to be able to do that in later modules.
You will need to have access to BMC Helix Innovation Studio, which means there is a sandbox or some other
development system available to you.

The problem at hand

Our hypothetical problem today is that managers allow staff to submit lunch orders by email with the understanding that
the lunches will be delivered before noon. However, this isn’t tracked anywhere, and there have been employee
complaints. The manager is interested in having a record of when each lunch order was delivered. So, the user stories are
pretty simple.
As an employee, I want to be able to order lunch in a quick way.
As a manager, I want to be able to know what time lunches are being actually delivered.
We can build a simple application to take care of this. Applications based on BMC Helix Innovation Suite are made up of a
few different parts. First, we need somewhere to store our lunch orders, we do this via a record definition (that
represents every order). Of course, we need a user interface in which users can submit the orders, called views in BMC
Helix Innovation Suite. In the background we need to define what is called a process to make sure the delivery time is
tracked properly.
As you become more familiar with BMC Helix Innovation Studio, the steps in this tutorial will become less detailed in
describing exactly where to click and what to type. For this first exercise, this guide will walk through every step in detail
of how to do this. Please also refer to the BMC Helix Innovation Studio documentation, as needed, found here.
Create the Application

From the Workspace page, create the new application as described in Developing codeless applications (see page 794).
You can really give the application any name you like (the Developer ID and Application ID are automatically determined
by your instance).
That's it. You will now be in the application page for your new application. By default, the Records tab is selected, which is
perfect, because that is the type of definition we need to create next.

Your first record definition

Create a new record definition with default fields by clicking the New Regular Record button in the Records tab of the
new workspace. Set the Name to Order right away using the Details pane on the right of the designer.
You might notice that your new record definition contains a few default fields, including Display ID, Last Modified, and so
on. Don't worry about too much for now, we won't need all of them. We can add all kinds of additional fields to the Order
definition. For now, we will mostly use a few of the default fields, such as ID, Status, and Description.
Status is called a Selection type field, which means that at run-time it has one of a set of enumerated values. We can use
this pre-created field to indicate where a particular Order is in terms of its lifecycle. The values created for us
automatically aren’t that applicable to something like lunch orders, so we will change the options now. To keep things
simple, for now, let’s assume that there are exactly two states that an order can be in: Submitted (the default state), and
Delivered (meaning it is fulfilled). Don’t worry – we will add a much more interesting lifecycle for Order later on.
Select Status and Edit the Options as found in the Details pane.
Remove all but two, and set the each option's Name and Integer Value (use 0 and 20 to leave room for more values in
the sequence in the future).

Let’s also add one custom Date/Time field called Delivery, using the New Field pulldown button. The idea is that this will
be automatically computed to keep track of the date and time the Status field value changes to Delivered in the lunch
ordering process.
Save and close the record editor.
We could actually start creating sample Order data right now using the Edit Data feature, but we might as well create a
simple view that end-users could use to create and view orders.
You can find out more in Defining record definitions to store and manage data (see page 324).
Your first View

The view designer is very powerful and flexible, but again, let’s keep our application simple. A single view will be used for
submitting new Order records, and listing the existing ones.
1. Go to the Views tab
2. Click on New and then Container (this creates an empty view with a flexible layout). You are now in the view
designer.
3. Set the Name as New Order, similar to the way we named our record definition.
Note: you should periodically use the Save button to store your view definition so that you can work on it later in a
different browser session if you choose.
This designer has a palette with the available view component types, and a canvas area that is blank, and will allow
components to flow vertically. We will drag in two view components to this simple layout.
First, users must specify the order details as follows:
1. Drag in a Record Editor component for submitting new Order information.
2. The Name property of this component is optional (it's only useful when you have multiple components of the
same type).
3. Pick the Record Definition Name - this is an easy one, Order, since you only have one right now. This tells the
system that this editor will be working with that kind of record.
4.
4. Switch the Mode from Edit to Create. This tells the system that this editor will only be used to create new Order
record Instances, and lets you off the hook for providing the ID of an existing record to edit.
5. Drag in a Text Area component right into the record editor's drop area, where it says Drop fields from the Palette
here.... .
6. With the text area still selected, the Properties on the right allow you to set the Field Name to Description.
Remember that this is your view, so you can give it a more appropriate label within this view if you like, such as
Details.
7. Leave the Value empty - this is only used to initially set the value when the editor is displayed.
Let's add a component that will allow the end users to submit the new Order record.
1. Drag in an Action Button.
2. Change the Label from New Button to something appropriate, like Save.

3. Click on the Add/Remove Actions link so we can specify what this button should do when it is clicked.
a. Drag in Save from Available Actions into the empty Selected Actions list.
b. Use Click to build an expression to bring up the Edit Expression dialog. This is where we configure which
component will be saved.

c. From the Available Values tree, unfold the View Components node to find the Record Editor (Order)
marker. Drag this into the Expression for View Component canvas (alternatively, you can click on its small
circular + icon). This means that whatever values are in that record editor will be persisted to the
database when the button is clicked.
d. Save the actions.
At this point, your view actually functions to create Order records. You could preview this now, but without easily seeing
the data you create, it is not very interesting. So to make it more usable, let’s add a component to the canvas that will
show the orders you have created. We also need to make sure that it refreshes every time a new Order is added.
1. Drag a Record Grid component onto the canvas, below the record editor.
2. As before, select Order as the Record Definition.
3. Use the Add/Remove Grid Columns link to configure the columns. Set them up however you like - in fact, you
could actually stop here). However, here are some suggestions:
a. Add the Delivery date/time field as a column. This could make it easier to test the business logic of the
application later on.
b.
b. You can update the Column Header of the Description field to match the label Details in the record
editor.
c. You can remove the Display ID and Modified Date columns.
d. Created Date is more useful here; you could give it a simpler label of Submitted; this also has the
advantage of matching the initial Status value more closely.
e. As a best practice, get used to also adding the ID field as a column, but turn off the Visible by Default
option. You don't really need this now, but when building a "real" application, you very often will.
Preview your view to try out what you have created so far.
1. Save your view definition
2. Click Preview
3. In the browser tab that appears, create some orders by typing into the Details field and clicking Save (you will
have to click the small refresh icon just under the Save button to see the newest orders in the Grid).

Note: you will become very familiar with previewing what you are defining. A useful tip is to keep this browser tab
around, and instead of using the Preview button every time, simply refresh this browser tab after making changes to the
definition.
You can find out more in Defining the user interface through view definitions (see page 376).
Challenge Yourself
Enhance your View so that the grid is automatically refreshed whenever an new order is placed. See if you can
figure out how to do this without any additional instructions... Note that to preview your changes after a save,
simply refresh the existing browser tab with the existing preview.
Make your view look a little nicer by adding a Rich Text component at the top and type in some kind of header.
Place your button in a Button Bar component to have more control over layout (like alignment)
Lay out the grid so that it appears to the right of the record editor and Save button.
Set up the modern shell

You have seen how to use Preview to run your view. But how will actual end-users access it? The answer is that every
application comes with a built-in landing page and default menu system called the BMC Modern Shell. You can think of it
as a special view that every application has. You can and should configure it so that it has a top-level menu link to get to
your New Order view. Luckily this is very simple.
From the application page, click on the Navigation link. This brings up the shell in a special view designer.

In the designer, you will see a special Palette of components designed for the shell. Remove the Home menu item from
the top level menu bar that is there by default.
Add a new Menu Item and configure it as shown:
Save and close the shell's designer.
Now you can quickly test the application, by clicking on the Visit Deployed Application link on the application page.
This brings up the application, running in the context of your developer account. It's worth noting here that if you want
to test as other users, is you very well may later on in order to test notifications, permissions, and so on, you would not
use this link but would instead paste the link it generates into a different browser (or another browser window with a
different session context - in Google Chrome you can do this by opening a tab in "Incognito Mode").

You can find out more at documentation for configuring the Modern Shell (see page 519).
Your first Process

Congratulations, you have successfully created an application that creates and displays data. But that's all it does at the
moment. How do you get the application to really handle your lunch requests? You need to introduce business logic into
the operations; this is often the complicated part of building applications, but the good news is that BMC Helix
Innovation Suite doesn't expect you to write complicated pieces of code, instead we declare the business process and
the system implements it for us.
Think of the process as the engine of your application, you are describing how a request is being handled. In our lunch
application. We will do this by describing the business process that you could informally call the lifecycle.
If you would like to read about the process designer first, you consult Defining the application business logic through
processes (see page 421), though these instructions may be sufficient.
Create a new, empty process by clicking on the New button on the Processes tab of the Workspace. By now, you know
the drill – give it the Name of Simple Order Lifecycle. You should notice that the process designer has a lot in common
with the view designer and you may already feel you know your way around it.
The process we will build will have a very simple flow. All it will do is the following:
1. Wait for an Order record to have its Status field value changed to Delivered
2. Update the Delivery field value for that Order to the current date and time.
Before we start building the flow of the process, though, we need to somehow tie this process to Order records
(remember that you can have many different processes, working on multiple kinds of data, and triggered by many
different kinds of events). For now we will just define an input parameter that represents an order.

Click on Add/Remove Variables in the process Properties (the GENERAL tab). Set up the properties of a new input
parameter called Order as shown below (the Variable ID can be left blank).
That’s it. Now, anywhere in your process flow, you can refer to a particular Order and its fields. It also means that when
this process is invoked, we will be required to provide a particular Order record as its context.
For the flow itself, we need to create a path between the Start and End event elements that are already in your brand-
new process (the End element may be scrolled off to the far right; you can drag it in closer to Start). To keep things very
simple for our “Hello World”, all we need to do in this process is two things:
1. Use a User Task to wait for an Order record to have its Status changed to Delivered.
2. Update the Delivery field value for that Order to the current date and time.
As you might guess, this will mean dragging in two activities from the Palette to the canvas, and connecting them with
flows. Let’s try it.

First, the User Task. This is a very flexible activity in the process designer, sometimes called the "Swiss Army Knife" of
business processes. We will use it here specifically to cause the process to pause until a particular record is updated so
that its Completion Criteria are met (specifically, until its Status field's value is changed to Delivered).
Drag in new a new User Task activity and connect the Start element to it. Now select it to configure its properties.
1. The Label doesn't really matter as long as it is unique. For this simple application, you can put the type of activity
into the Label as a prefix to make it easier to understand at a glance.
2. Make sure you change the Mode from the default of New Record to Existing Record (because we will be waiting
for a specific order record instance to change its status).
3. Now you can select Order as the Record Definition; this exposes two required properties that you will set next.
4. Configure the Record ID using Click to build an expression.
5. Use the resulting Edit Expression dialog to pick the ID field of the input Order (be careful not to pick the Display
ID field - that is not the right field for working with data in the process designer). You are instructing the activity
to wait for some condition about this particular order. Pay attention to the small glyph on the tag with an arrow
going into a box - this has the meaning of "input".

6. To set the Completion Criteria, use its Click here to build an expression. Again using the Edit Expression dialog
again, make sure that you first select the Status field from the User Task element itself (unlike the last step, do
NOT use the Order input parameter here. Be sure that the glyph has the "bent arrow" glyph - meaning "output" -
in front of it, as shown in the following screenshot). The reason for this is that the process needs to read the
active status as soon as it changes within the User Task.

Why set it to be "greater than" Submitted instead of "equal to" Delivered? Of course, since we only have two possible
states, the behavior will be the same. The difference is that using the inequality gives us more flexibility later on to test
for additional status changes without blocking here. After all, this phase is really about still being in Submitted state, and
less about being in some other specific state. We will take advantage of this later on.
The business logic now calls for the process to automatically update the Order record's Delivery date field value after it
has been delivered. All we have to do is drag in, and configure, an Update Record activity from the Palette (you may have
to scroll down to find it), and then connect the flows through to the End element.

Leave the Record Source as Database (this means it will be operating on the persisted record, not just the current
transaction), and select the Record Definition Name as Order.
This again exposes Record ID, which you can set to input variable Order ID field in exactly the same way as the previous
step.
Click on Add/Remove Input Map Fields in order to select the fields that will be getting new values from this operation. We
only are updating the Delivery field in this case.

All that's left for the Update Record configuration is for you to specify the value, which is the current date and time of
process execution. The Edit Expression dialog comes to our rescue again; there is a keyword under the General set of
expressions for Current Date and Time. When the process actually runs for an order, this step will execute just after the
delivery, and this keyword will essentially timestamp it accordingly.
Before you click Save, be sure there are no errors or warnings in the messages area, and if there are, be sure to correct
them before proceeding.
You have now created a useful process to wait for an order to be delivered, then capture the delivery date and time.

Your first Rule

In BMC Helix Innovation Suite, you can define all sorts of process definitions, but they do not execute by themselves. This
was part of the design intentionally to give you flexibility about decided exactly when a process should be instantiated
and run and with what input data. Although there is a REST API that can be used to invoke a process, the easiest and best
way to kick one off is usually by creating a rule to tie the record data to the process. This works well because rules
naturally are triggered with regard to data transactions, such as when a record is created or updated.
In English, you could say that you would like a rule with the following meaning:
Whenever a new Order record is created, as part of that processing, start an instance of the Simple Order Lifecycle
Process.
We specify this as follows:
1. We relate the rule to the Order record definition.
2. We specify one of the rule's Trigger conditions as After Create.
3. We add an action to the rule that performs a Start Process, and pass in its current record context as the Order
parameter that the process is asking for.
Let's try it, step by step.
First, go to the Rules tab of the Workspace.
Click on New.
Now define the rule.
1. In the rule editor, give the rule a Name, such as Start Order Lifecycle after Create.
2. Click on Add/Remove Record Definitions and add the Order record definition.
3. Select the Trigger and select After Create. This will cause the rule to run as soon as a new Order record instance
has finished being created.

3.
4. Drag in and configure the Start Process action.
5. Note the Order parameter that must be specified. It is there because of the Order input parameter we specified
in Simple Order Lifecycle. You must specify the current record context of the rule as the parameter (NOTE: do
NOT use the Order information that appears in the Edit Expression dialog; make sure you are passing the Current
Record keyword from the General part of the dialog as shown).
As soon as you save your rule, it will be in effect.

You can get more information about rules here (see page 490).
Try it out!
You may have already noticed that we have not yet created any view to update the status of an order to Delivered. Here’
s how to demonstrate that it is working…
Launch the application by clicking on the Visit Deployed Application link in the application main page (if you have already
launched it from earlier, just refresh the browser tab instead).
Submit a new order. The grid should show it with Delivery as blank.
Back in BMC Helix Innovation Studio, go to the Processes tab, and click the Manage Processes button.
1. Select the Simple Order Lifecycle process
2. There should be an active instance of this process for every Order submitted since you created the rule that
triggers it.

3. Drill down on that instance’s Context Key in order to see the runtime diagram. It should show the User Task: Wait
for Delivery activity as the current one.
In a different (or the same) browser window, go to the Records tab, select the check-box for Order (not the link), and
click on Edit Data.
Using the built-in Data Editor, open your latest Order record (the one the process is waiting for) and change the Status
value to Delivered (do not change the Delivery date field value, the process will do that for you).

Now back in the Manage Process diagram, refresh the diagram. It should now show the process instance has run through
the Update Record: Set Delivery to Now activity and is now complete.
Refresh the application (or even just the record grid of submitted orders). You should now see the delivery time to be
current as of when you updated the order.
What we learned
Voila! You have now created a complete working application, though not a particularly complex one. Along the way you
have discovered a lot of fundamental capabilities of BMC Helix Innovation Studio, including:

Record, view, process and rule designers
Previewing views
Managing processes
Using the built-in data editor
The product documentation for Innovation Suite (see page 794).
Of course, a real application will typically need much more, including being able to use foundational shared data,
managing data relationships, access permissions, complex views, error handling, sophisticated process logic, leveraging
custom Java and Javascript code, just to name a few. Perhaps more importantly, as you start to support more “real
world” requirements, you will need to know the best practices for identifying just how to pull all of these things together.
There’s a lot to learn, but the good news is that this tutorial will take us through all of these aspects. You have a great
start now in understanding the basic patterns of how BMC Helix Innovation Studio works and that it is safe to explore
and build your own very flexible workflow-driven applications.
Analysis and design for a solution to the lunch ordering problem

Let's walk through our chosen methodology for designing the solution:
1. Understand the users and their pain points.
2. What are the specific user stories we will be implementing?
3. What is the overall business process that our application will provide?
4. What kinds of interactions will our users experience with that process?
5. Capture the data model, including both out-of-the-box enterprise data, and our own definitions that specifically
support this application.
Then we will begin development with a quick hands-on exercise to familiarize ourselves with BMC Helix Innovation
Studio. You can jump right into that if you like, and return here for developing the full solution.
Pain points
In this scenario let’s say that the problem goes well beyond not knowing what time a lunch was delivered. In fact, there
are problems because:
A manager will often order food on behalf of other employees. They want this to be an easy process, like
checking off names. Note that this does not have to be someone with a particular title; anyone can submit orders
on behalf of others (typically it is an admin assistant).
Only the Facilities Coordinator can allow certain restaurants and even certain dishes to be available.
Orders are not always validated, submitted past the restaurant’s cutoff time (by default, 11am is the latest time to
submit an order for that day)
When an order is cancelled, not everybody finds out who needs to know.
The facilities coordinator is frustrated by not knowing what kinds of orders are being fulfilled, or how much they
are costing the company.

Who are the users involved?

Let’s understand the personas (more properly, the roles) that the various users will play. Sometimes they are spelled out
in the problem statement or requirements, and sometimes you need to extract them by looking at the “people” and
“job” words. We can quickly identify the following functional roles:
A Meal Program Member - such as an Admin Assistant - places the order. Let’s call her Maria.
The Meal Program Manager – let’s call him Leon – handles the menus and reporting.
What kind of application might you build to solve these problems? Where do you start?
User stories
A useful format for understanding what the various personas will do, and capturing the desired behavior of the system, is
the User Story. We will identify the following for this example:
I, ... As a... ...want to... ...so that I can...
Maria Meal Quickly pick from my lunch options: which restaurant, Spend more time doing productive work.
Program and which items from that restaurant.
Member
Maria Meal Be able to cancel my order as late as possible. Change my mind, and, avoid having my order delayed or extra costs
Program incurred by cancelling after it has been prepared.
Member
Maria Meal Be notified when my order is now being worked on by Be aware of any problems early on, and answer questions to the staff
Program the restaurant, and when it has been delivered. Also about it.
Member have the consumers automatically notified.
Leon Meal Choose which restaurants and menu items (including Manage costs and keep employees happy and productive.
Program price) will be available to employees
Manager
Leon Meal Stop employees from ordering after the appropriate Maintain the expected service delivery and manage employee
Program cut-off time. expectations.
Manager
Leon Meal Monitor the status of Orders that are in progress. Track the overall status of service.
Program
Manager
Leon Meal Review the total costs (invoice) from all the orders Quickly make changes to the program offering if I need to in order to
Program every day at Noon. manage costs.
Manager
In addition to these fairly explicit requirements, there are usually implicit ones that should be agreed upon before going
very far with development. These are capabilities that we can anticipate will be expected for this type of application. Let’s
list out some additional requirements or assumptions that we will use for this exercise:
The consumers (not just the submitter such as Maria) are also represented as Employees in the existing
Foundation Data, so we don't need to create a functional role for them.
It is expected that photos of the restaurant and each dish would be provided, much as you might see in a web site
such as Door Dash.

The business process

A good place to go next is to think about the business processes and other kinds of logic (such as business rules)
involved in implementing this, at a very high level.
With the Quick Start application, we already defined a very rough business process around the "lifecycle" of a lunch
orders. Looking at the additional requirements, it's clear that there are more than the two distinct phases we have
already started to address.
Order Lifecycle Phases
For each of these, start thinking about what kind of "activities" will be occuring. When will the process pause and wait for
something? Note that you can start to formalize the terminology here so your design can eventually be translated into
actual objects.
1. The Submission phase occurs once an Order has been placed but before cooking starts. The Order needs to have
associations with both Dish and Restaurant. An Order can only go into this phase if it is in the future, but before
the cutoff time for Order.
2. The In Progress phase is once the Order is actually underway. It is put into this phase by input from Leon.
3. The Delivery phase happens when the Order is accepted. It is important to track the time when this change
happens, and at least two kinds of notifications. As we have already seen from the Quick Start application, this is
where the actual delivery time is captured. For our simple example, we will say that this also occurs because of
input from Leon.
4. The Closure phase means the Order is considered historical and will normally not appear in the application. Each
Order will automatically go into this phase within a certain amount of time after delivery occurs, or they can
manually "closed" also.
5.
5. Cancellation would always require a notification.
From this analysis, it seems likely that the “Lifecycle” Process for Order needs to do a lot more than just update the
delivery time.
Also, some logic will be required to do that particular validation about the cutoff time. Specifically:
Don't allow an Order to be submitted whose expected date is in the past.
Don't allow an Order to be submitted on the same day but after the cut-off time.
Future Order submissions are fine.
Views and interactions

Now that we have a good overall understanding of the activities going on, such as "Maria places an Order", and "Leon
manually marks an Order as In Progress", we can start to think about what kind of interactions will be directly supported
by the user interface of the application. Usually we would think in terms of "top level" Views (that are directly reached by
the Application Shell without any context), and "supporting" Views. The obvious "top level" Views that will be needed are:
Top Level Persona (Role) Needing Possible Supporting View Data Use Cases Involved
View Access
Restaurants Leon (Restaurant Popup to create new Restaurant, Popup to Manage Restaurants. Manage Dishes for each Restaurant.
Manager) create new Dish
Dishes Maria (Meal Submitter ) Dish View Dish details, create new Order based on Dish, with
associated Person (of type Employee) recipients
Orders Leon or Maria (all Roles) List of Orders with Dish and Restaurant information. List of
Associated Persons. Ability to change the status of an Order to In
Progress, Delivered, or Cancelled.
With the quick start application, we began with a single View for submitting and viewing an order without any concept of
dish and restaurant (we will leave this for a later part of the tutorial).
Foundation data and access control

Part of understanding interactions is to think about how to secure the activities and data based on roles. This is obvious
from the Persona (Role) Needing Access concept from above.
With BMC Helix Innovation Suite, developers define part of the access control model as part of the application definition,
and part of it is assumed to be specified by the actual consuming customer of the application. As a developer, this means
you should define some test data in order to make sure access control is working as you expect. The idea is that you
build the application in such a way that the roles of the users can be easily mapped into various kinds of Foundation data
that will exist on the customer side. Understanding the difference between these is important, so you will be able to
deploy an application that can be secured by customer.
The following diagram shows the elements that you will be including with your application definitions:
Roles
These actually control runtime access to specific definition objects such as Records, Fields, Processes,
and Views.

Furthermore, in the case of Fields, the access can be for Change (allows update) or View (read-only). For
example, meal submitters can create Order records and can view Restaurant and Dish records. For
managers its likely the other way around.
Roles are only mapped indirectly to users. There are two ways this can be done:
Roles contain a mapping to Group that contains users - this can be done by customers of the
application can, but not by developers, because Groups are test data and are not deployed with it.
So, this is not the best practice and we won't use it for our application.
Roles can be mapped into Functional Roles that are assigned to users.
Functional Roles
These model how you envisage what the personas will be allowed to do given the user stories you
support.
Each Person (including Employee) is assigned a list of these.
However, these are abstract and do not directly map to definition objects such as Records, Fields, and
Views. Instead, they include a mapping to Roles.
Note: Groups are not needed at all to implement access control, and the use of them is more of a tool for adminstrators
than it is for developers.
At this point we can start thinking of what kind of test data we will eventually need to create in order to build out the
application.
Person - some examples
Maria Vasquez (Type: Employee, Functional Role: Meal Program Member)
Leon Krantz (Type: Employee, Functional Role: Meal Program Manager)
Li Po (Type: Employee, Functional Role: Meal Program Administrator)
Primary Organization (of type Operating Organization)- example
Ordinarily, all Person records are secured on a instance (row) level so that you can only access your own
Record. Our application requirement is that folks who submit an order can include a list of Person
records that will consume the meal.
Luckily there is an easy way to grant row-level access to other Person Records - by putting such Person
records into the same Primary Organization (type is Operating Organization) in the Foundation. This
automatically adds a permission to those users to see the Records within that organization. You will
create one of these just for testing purposes.
Here is the complete picture:
As the diagram shows (over-simplifying because each Field can have its own permissions set), we can allow Maria to
submit an order (she has Change access). Leon can update the order and is the only one to manage restaurant and dish
information.

You can read the documentation about the Foundation Library (see page 661) for more information about Employees,
Organizations, and Functional Roles such as AR Foundation Person Read. We will actually enter (or import) this data in
the next part of the tutorial.
Records and associations

By now we have a pretty good idea of the overall data model; in fact, we have started to call it out explicitly in the analysis
of Views and Permission Roles. What's left is to design the associations between them, which is primarily represented by
their "cardinality" - how many of each one are associated to how many of the other.
Thinking ahead of what will be needed for the Process and View aspects of the application, certain fields stand out as
being required already, though we can always adjust this later.
At a high level, it's a good practice to visualize the entire data model. BMC Helix Innovation Suite in particular will need to
know not only Fields, but also information about the Associations: cardinality, and a name for each "role" of the
Association (this is used to represent them in the Designers). Also worth noting - some of the data model elements may
already be present in other Applications or Libraries, such as Employee in this case. We can still use it in our Associations.
Ready to build!
We have put a lot of time in up-front to understand our application at a high-level. We have gone "outside in" from the
requirements to come up with a design, starting from the problem statement and ending with the data model as
expected. This should lend our application to be fundamentally process-oriented and user-centered - a good recipe for
success. Now we are ready to build up a high-quality application that handles all of the user stories.
Module 1 - Developing a full solution to the lunch ordering problem

By now you have already gotten started by building a simple version of an application, and have dived into the
requirements and high-level design of a real solution for our sample problem. With our design in hand, we are now ready
to start building out the real thing.

Prerequisites
This module assumes you have already done the exercise Quick start: creating a simple app to order some lunch (see
page 68) earlier in this tutorial.
If not, you can go back to do that exercise now (this is strongly encouraged).
If you would like to skip this, or want to be sure you are starting with a clean version of the basic application, you also
install a pre-built one by using the following steps:
1. If you already have an application in your sandbox called com.example.lunchtutorial, you should uninstall it from
your workspace (of course, you can use Create Install Package first to keep a snapshot of it before you do this if
you like). This is to make sure that you don't have a mix of definitions, because installing an application does not
remove any previous definitions.
2. Download com.example.lunchtutorial-1.0.1-INSTALL.zip. This package includes the work that would normally by
done in the orientation.
Important
To download the ZIP file, right-click the URL > Save link as. The ZIP file will get downloaded to the
default download location of your web browser. You must use the 7-Zip utility to extract the contents
of the ZIP file, and view the install package components. The contents of the install ZIP file cannot be
extracted by using the Windows Zip utility or Mac archive utility.
3. Use the Install button from the Workspace view to install this application.
4. Also download and install the package com.example.util-lib-1.0-SNAPSHOT.zip. This includes some handy
additional view components to spruce up views, including a picture viewer. It won't be needed until mid-way
through the tutorial but there is no harm in installing it now.
Defining the data model

It is time to begin constructing our definitions, and according to the methodology described earlier there is no better
place to start than defining the Functional Roles, Records, and Associations that will support the Views and Process we
have already identified that we need.

Define permissions and sample data

It's worth noting that you actually have a choice here. Defining the permission model up-front is technically more
efficient because you can assign Permission Roles to individual records, fields, views, and processes in a single pass as you
build them out. However, it's also true that as long as you are willing to test your application only as Administrator, then
you could always postpone setting up roles and Functional Roles until after the application is developed. So, if you skip
this part of the tutorial for now, that's fine but do remember that it will not be enabled for other users until you come
back and revisit this topic.
That being said, assuming you want to set up permissions at the beginning, let's dive in. Recall the access control model
we determined we needed during analysis:
This consists of setting up permission roles and functional roles as part of the application, and also creating (or
importing) some sample test data. As mentioned previously, you can choose to skip this lesson for now, but this means
that your application will only be able to be run by someone with Administrator permission. You can always choose to do
this later and revisit your definitions to apply permissions when ready to do multi-user testing.
Create permission roles

Let's do this first, since functional roles need to be mapped to these.
1. Go to the Administration area of BMC Helix Innovation Studio.
2. In the Settings list, go to Configure My Server Application Permissions Manage Role Permissions.
3. Click New.
4. Specify the properties for an Order Submitter role as described in the preceding logical model.
a. Application Name - this must match the application ID that was set when you first created the application
(it is generally in the format developerid.application-short-name). If you used the install package to catch
up, it will be Lunch Tutorial.
b.
b. Role Name - Order Submitter
c. Role ID - you can specify any id as long as it is negative, unique, and in a very large range as it will prompt
you. For more complex applications you should think about what kind of system to use to maintain these.
d. Group Mapping - you can leave these blank, since we are going to map these Permission Roles to Person
via Functional Roles.
e. Save it.
5. Repeat for Restaurant Manager.
Functional roles
Although our permission roles can be specified for our definitions, as mentioned above, they can't be mapped directly to
our test users. That's what the functional roles are for.
1. Go to the Administration area of BMC Helix Innovation Suite.
2. In the Settings list, go to Configure My Server Application Permissions Manage Functional Roles.
3. Click New.
4. Specify the properties for Meal Program Member
a. Application Name - same as used above.
b. Functional Role Name - Meal Program Member.
c. Description - up to you.

d. Selected Role - this is where you map the permission roles for this functional role.
i. Search for Order Submitter and select it.
ii. Also add AR Foundation Person Read.
e. Save.
5. Repeat to complete all the mappings needed according to the diagram: Meal Program Administrator and Meal
Program Manager.
Functional Role Mapped to Role
Meal Program Member Order Submitter,
AR Foundation Person Read
Meal Program Administrator Order Submitter,
Restaurant Manager,
Meal Program Manager Restaurant Manager,
Test yourself: why do we need to map the Permission Role for Person Read for this particular application?
When you are done, the Functional Roles list should look like this, matching our diagram.

Import Test Data

The application's access control model is complete, but for any kind of testing, you will also need Person and Primary
Organization records. You can create these manually, or as a short-cut, you can use the Data Management Console to
import them from the provided for this tutorial.
Important
To download the ZIP file, right-click the URL > Save link as. The ZIP file will get downloaded to the default
download location of your web browser. You must use the 7-Zip utility to extract the contents of the ZIP file,
and view the install package components. The contents of the install ZIP file cannot be extracted by using the
Windows Zip utility or Mac archive utility.
Get and unzip the data spreadsheets found in Tutorial Foundation Sample Data.zip. You should now have the following
three files:
01-Tutorial Organization Data.xlsx
02-Tutorial Person Data.xlsx
03-Tutorial Person Associations.xlsx
The use of the Data Management Console is fully described in Loading foundation data in bulk (see page 684). The
important thing to remember is that each spreadsheet should be loaded in the order shown above (associations last).
If you see the Data Load Result as Processed, refresh the list of Employee records to see if they have been imported
properly (if the status is not Processed, you can download a spreadsheet containing the error codes)

Sometimes, even if the status is Processed, there still could have been errors on a particular row basis. One common
reason is when the create operation specified in the spreadsheet is specified repeatedly, those rows might error out.
Also, when you import an operating organization, a group is automatically created based on a a group ID in the
spreadsheet. You may need to manually delete this permission group in order to retry, and then you will have to re-
import all subsequent data that depends on it as well.
If you did not use the Data Management Console, you will need to manually associate the employees to the operating
organization.

Assign functional roles

Now that you have some employees, you can assign them the functional roles called for in our design. To map a
functional role, find the Employee record in the Administration area, and use the Functional Roles picker.
Repeat this as needed to make the test data match our access control diagram. For example, Maria would be given the
Meal Program Member functional role.

What we Learned
There are quite a few useful things you have now tried out.
Prepared the permission roles so you can use these while creating the definitions in a single pass (otherwise, you
would have to go back and apply them after development).
Learned about functional roles, which is a great way to bind specific users to permissions, and even works across
Applications and Libraries.
You learned about the Data Management Console, an out-of-the-box Application that provides nice way of
importing Foundation data.
You used the built-in Foundation data editors to assign functional roles to person records (in this case,
employees).
Defining the Restaurant, Dish, and Order records

The expanded data model for the application was described at a high level previously. Click on it to enlarge.
As you go into the Records tab of BMC Helix Innovation Studio, and begin building this out, you will need to set certain
properties of the record and its fields. For this project, the properties that will matter are:
Field Type (specified when you create a new Field)
Field Name
Record and field Permissions (roles, not groups) - assuming you chose to define them earlier:
Order Submitter role permission (View and Change)
Restaurant Manager role permission (View and Change)

Is the field Required?
Default Value
Other type-specific constraints.
Most of these are set using the Properties inspector after selecting a field.
Rather than a step-by-step guide to setting these, the desired property values are described in the following tables.The
method of setting these is the same as in the first exercise of the tutorial, so you can reference that if you don't know
where to start, or consult Creating the definitions for a tailorable Digital Service application (see page 323).
Person
This is the easiest one - it already is defined in the Foundation. You can use it like other Record Definitions. One thing to
keep in mind whenever trying to select Person as a record definition - remember that because this is not defined within
your application, you will have to find it under All Records, or the easiest way, by using the search feature of the Record
Definition Name pickers in BMC Helix Innovation Studio.
Restaurant
Create the new record definition. Using the record's Properties inspector, set the Permissions list to allow access to the
Manage Restaurants and Order Submitter Roles.
Another property to consider here is Should Export Data. If you turn this on, your data will be exported and included in
any install package later on, which is useful if you want Restaurant data to pre-loaded when the package is deployed
(usually this is only used for configuration data but this choice is yours).
Here is what it looks like to set the permissions for the record:
Here is an example of setting permissions for a field:

Now, go ahead and set up the fields for Restaurant, following this summary of property values for each one. Some things
to note:
In some cases, the field is "Core" (always there) and doesn't need to be created.
We will be re-naming the Description field to be used as the Name field required by the data model. The
Description field is always present in every Record Definition in BMC Helix Innovation Suite, and it is a good idea
to find a meaningful use for it, as some human readable (but not necessarily unique) description of each Record
Instance.
You can assign field ID from the range allocated when you signed up for your instance, or let the system generate
unique IDs for you.
Type Field Name Permissions Other Properties Note
Text Display ID Default:RST- Set the default value and length to create a more
friendly Display ID
Length: 10
Text Created By
Text Name(renamed from Field 8 - Restaurant Manager: Default: New Providing a default makes UI construction easier
Description) Change Restaurant
Order Submitter:
View
Selection Status Restaurant Manager: Options: Open (0) Leave this for future use.
Change
Default: Open
Order Submitter:
View
Text About Restaurant Manager: Default: About this Default is like a prompt.
Change Restaurant
Order Submitter: Length: 8192

View
Required
Attachment Photo Restaurant Manager:

Change
Order Submitter:
View
Decimal Delivery Charge Default: 0.00

Restaurant Manager: Min: 0.00

Change
Max: 100.00
Order Submitter:
View
Dish
Again, create this record definition, and using the record's Properties inspector, set the permission list to allow access to
the Restaurant Manager and Order Submitter permission roles. Also, again note that we are renaming the core field
Description as Name.
Text Display ID Default: DSH- Set the default value and length to create a more friendly
Display ID
Length: 10
Text Created By
Text Name(renamed from Default: New Dish Providing a default makes UI construction easier
Field 8 - Description)
Selection Status Restaurant Manager: Options: Available (10) Leave this for future use.
Change
Default: Available
Order Submitter: View
Text About Restaurant Manager: Default: About this Dish Extending the length for longer descriptions
Change
Length: 8192
Required
Attachment Photo Restaurant Manager:

Change
Decimal Price Restaurant Manager: Default: 0.00

Change
Min: 0.00
Max: 200.00
Required
If you are a developer accustomed to building database applications, as you examine this list, you may be feeling that
something is missing. We know that a requirement has been stated that each Dish belongs to exactly one Restaurant. In a
database application, you would probably need to create a "foreign key field" to track that relationship. With BMC Helix
Innovation Suite, the ability to define and work with Associations is a built-in feature that should be mostly transparent to
you. We will soon get to define these associations, but for now, the important thing to notice is that we don’t ask you as
the developer to create and manage key fields. You should only create fields that represent “attributes” of the record at
hand.
Order
As part of the earlier exercise, you already created the Order record definition. With the expanded requirements, we will
need to add more fields and make sure their properties are correct.

Set the permission roles for the Order record to allow access to the Restaurant Managers and Order Submitter roles.
Note that, at the field level, the permissions are somewhat opposite to Restaurant and Dish, because an Order Submitter
(like Maria) works primary on Order while managers work mostly on Restaurant and Dish. You will have to look at each
field on a case-by-case basis, however.
For the fields, note that what we created earlier was insufficient for our User Stories so we will adding additional fields
now.
Text Display ID Default: ORD- Set the default value and length to create a more friendly Display
ID
Length: 10
Text Created By
Text Description Default: Description Providing a default makes UI construction easier
Selection Status Restaurant Manager: Options: Submitted (0), In Everyone gets to change Status!
Change Progress (10), Delivered
(20), Cancelled (30), See the following table for details on Options.
Order Submitter:
Closed (40)
Change
Date/Time Delivered Restaurant Manager:

Change
Text Special Restaurant Manager: Length: 8192

Instructions View
Order Submitter:
Change
Date Requested Date Restaurant Manager: Required By adding a new Required field, you will have problems updating
View such a record if the Requested Date field is not exposed in the UI
that is attempting the update. It is a good idea to remove all
Order Submitter: previous Order Record Instances (or provide them all with
Change Requested Date values) using the Edit Data feature.
Time Cutoff Time Restaurant Manager: Default: 10:00am We will need this to implement the cutoff time validation later
View on.
Required
Order Submitter:
Change
As we have seen from the earlier analysis, much of the business logic for this application will revolve around the lifecycle
of every order. We can track this in different ways, but for this application, we will keep it simple and continue to use the
Status field of the Order. At this point Status should have two options: Submitted and Delivered. We need to track
additional states now, including the ability to represent an Order that has been cancelled. Set the Options accordingly.

Challenge
Add some additional fields to these records and consider how you might expose them in your UI
Consider performance of lookups. What indexes might help based on the search patterns you expect? For
example, a UI may be frequently retrieving all the Order records submitted by the current user that are in
Delivered state; also Restaurant and Dish both have a Name field that will frequently be searched and sorted.
Create the relevant indexes.
What we learned
We have now created the records part of the data model. What's new here is:
Setting role permissions for records and fields
Thinking through the lifecycle needs of a record
Configuring the Display ID format for readability
Other properties, such as Min, Max, Length, and Default Value
Now we must define the associations between the records, as this is where much of the behavior of both the business
logic, and the UI, will come into play.
Specifying the associations for our application

Recalling the desired data model, we are ready to implement the association definitions using the association editor. The
designer itself is pretty straightforward to use, but you can access help about it from Creating record associations (see
page 342). The following table summarizes the properties of each association described in our diagram.

Note: the descriptive names used here don't really matter at run-time, but can help in using these associations later in
development. Some optional naming conventions are shown here - best practices but not required.
The name makes clear the 1st record / 2nd record ordering. This will help remind you later of which one is 1st.
The plurality is indicated by the names also, as in Restaurant (singular) fulfills Orders (plural).
Association Role of First Record and Role of Second Record generally include both objects, but make it clear
which "end" of the relationship this object represents. Later, in the process designer, you will see only these, and
not the association name itself, so naming these appropriately will help make it clear what they mean. Also, the
wording should be specific to what the association is really about, as there could be more than one defined
between the same kinds of records.
Name Description 1st Record Cardinality 2nd Record Role of 1st Role of 2nd Deletion Requirement
Constraint? Constraint?
Restaurant Fulfills Each restaurant fulfills Restaurant Has Many Order Fulfilling Orders to be No No
Orders many orders Restaurant Fulfilled
Dish can be Ordered Each order refers to Dish Has Many Order Dish Orders for No No
one dish Ordered Dish
Restaurant provides Each restaurant has Restaurant Has Many Dish Providing Provided Yes No
Dishes multiple dishes that Restaurant Dishes
only it provides
Orders on behalf of Staff are included in Order Many to Person Orders Consuming No No
Employees orders. Many (remember Consumed Employees
you will have
to search for
this)
Your Associations tab should now look very much like the table above:
If you open up the record designer you may notice that in one of your record definitions ( Dish), a text field was
automatically generated and added by the system, deriving its name from the Role of Second Record you specified when
you created the association Restaurant provides Dishes.

This is because you specified the constraint of deleting the Dish records when their associated Restaurant record is
deleted. This is the only case where the system uses something like a foreign key field for its own record-keeping. For the
most part we will ignore this field's presence though there are a few cases where knowing about it does come in handy.
It is worth noting here that at this point, all you have done is enabled the kinds of relationships that can possibly exist,
such as that every Dish belongs to exactly one Restaurant. A common mis-conception is that this will magically construct
the associations within your data. Actually, if you want to associate an instance of Dish, such as "Coffee", with a specific
Restaurant, such as "Starbucks", it is up to other UI and/or business logic to actually associate those specific instances at
runtime. We will implement that logic later on, using views, and processes, and rules.
What we learned
You can easily implement the association definitions as part of constructing the data model.
For the most part, you do not need to think about foreign key fields (with one exception).
Run-time associating, and dis-associating of instances is something else that will be done in our views and/or
application logic.
Creating views for restaurants and orders

You are now ready to implement the basic view definitions to support our user stories for our personas: Leon (who
manages restaurants) and Maria (who creates orders), as well as being able to view and update order status.
Note: if you have not successfully completed the earlier data definitions, you should go back and do that now; or, you can
opt to uninstall your com.example.lunchtutorial application and install a pre-built version of it that includes the record
and association definitions, found in this package: com.example.lunchtutorial-2.0.2-INSTALL.zip.
Important

You have already a bit of experience using the view designer from the quick start exercise, but if you get stuck you can
also read the documentation found at Defining the user interface through view definitions (see page 376).
The views we will build have some things in common that will be helpful to understand first, before actually building the
views.
NOTE: this is just an explanation of a common pattern we will use, as background material: these are not yet steps to
follow explicitly.
Whenever you create a new view, you specify the layout. It's generally best to start with a simple Container type
of layout, because this will give you flexibility to change the structure of the page later on. You can always add
Container components to the view to make a more sophisticated design. For example:
For views that will be used for popups and blades, you will probably leave it that simple and not require any
additional containers.
For “top level” views (accessible through the shell), we will build our own "standard" layout
In many views, you would place a Rich Text component at the top of layout (header area). We will
generally do this with the views later in the tutorial.

In many cases, you will create a side-by-side layout underneath the header. You can do this by dragging in
a Container below the header, and setting its number of columns to 2.
The “Left” side will often be used for for lists
The “Right” side will often be used for for details and associated data.
Another technique we will use is adding a nested Container component when things are conditionally hidden. For
example, a group of components should only be seen when there is a selected record
Yet one more use of a container is to make it always hidden, and place components there that are used only in
the invisible logic of the view and are not meant to be seen by the user.
Finally, remember that views have permissions too, and we will be thinking about which permission roles to allow access
to which views, as our earlier analysis already touched on.
Let's dive in! The first one we will implement is the one for adding restaurant and dish information. We do this one first
so that we can have actual data to use to associate a Dish record to to an Order record later on.
A view for Leon to manage restaurants

This view will be more slightly more complex than what we created before in the quick start exercise. It will combine
information about Dish and Restaurant records and support creating and editing them. When we're done it should look
something like this:
Restaurants View Preview

Restaurants View Preview
Those action buttons indicate it will use other helper views. If we create them first, it will make the construction of the
"top level" view a little bit easier, so let's do that now. We will need one simple view to create a Restaurant. There will be
one more to create a Dish.
Defining the New Restaurant Blade

We will call this one a "blade" because we intend for it to slide out from the side of the parent view when it is time to
create a new Restaurant record.
From the Views tab of , create the new view as Container type of layout. We will keep this layout very simple. Give the
view its Name: New Restaurant Blade.
Although we didn't bother with this before, you will need to set Permissions so that non-Admin users can access it, by
adding the Restaurant Manager Role. This will give users like Leon access to it; other users simply won't see it.
As you did earlier for the New Order View, drag in a record editor (where Mode is Create) and configure it for the
Restaurant records. Also add a Button Bar, with an Action Button within it labelled Create.
You should add at least these fields using Quick Add/Remove Fields: Name, About, Delivery Charge. and Photo.

If you quickly switch back to the view's Properties inspector (the GENERAL tab), you will see that a view can define both
Input Parameters and Output Parameters. Strictly speaking, we will not actually need either of those for this view to
work. However, when building a view to create a single kind of record, it is a good practice to map the ID of the created
record as an Output Parameter; that way, the calling view can obtain the ID of the created record instance. Now that you
have added the record editor, we have access to this ID.
To do this, add an Output Parameter named id.
For the Source, use the Edit Expression dialog to drag in the ID of Record Editor (Restaurant) Record Instance.

To configure the Create button, all you need is a single Save action that applies to Record Editor (Restaurant). You
should check the Close After Save option, so the view will simply close itself after creating a new Restaurant Record.
When you are done, the view looks like this in the designer. You can save it.

You can now test it using the Preview button. Of course, since this is our first view for Restaurant, the only way to know
that it worked right now is to use the Edit Data feature from the Records tab of the Workspace.
Creating the New Dish Blade

This will be so similar to the New Restaurant Blade View that we will not go over the steps in any detail. The highlights of
this one are:
Same permissions: Restaurant Manager.
The record definition is Dish, or course. You will need at least these fields:
About
Name
Price
Photo
As before, add an Output Parameter to the view that maps the record instance ID field back to the calling view.
This time, it is actually needed in order to use this view to create a Dish associated to an existing Restaurant, as
we will discover when trying to build that UI in a later step.
The Save action is the same.
Now we are all set to work on the "top-level" experience for managing Restaurant and Dish records.
Creating the top-level Restaurants view

Our design calls for having one place where Leon can do various things without having to "navigate around" too much.
See which Restaurant records exist

View information about a restaurant
Create a new one (our helper view will come in handy here)
Associate a Dish to a Restaurant
View information about it.
The overall structure of this view could still be pretty simple, but it would be nice to have 2 columns, with the list of
restaurants on the left, and the details (including associated dishes) on the right. Also, we should hide the details
whenever there is no Restaurant record selected, so this will require a Container component as well to control visibility.
Sometimes it helps to visualize the structure of a view in a simple diagram on a whiteboard. The equivalent here might be
this, with the three internal containers called out. The buttons will be used for creating a new restaurant, and dish for it,
respectively.
Restaurants View Layout
Start by creating a new view of type Container; give it the name Restaurants, and the same permissions Leon will have,
which is the Restaurant Manager role.
Drag in a Rich Text component that is a header and set the title you want there.
Underneath it, drag in a Container. In it's Properties inspector, you can set a Name such as Main (this is optional, but
helps to keep track of them when you have a complex layout). Set the Number of Columns to 2. You have now created
the implied left and right areas of the view. You can adjust the Column Span by dragging the line between them; since the
left side will only expose the restaurant names it can be narrower.

Drag in Button Bar, Action Button (into the Button Bar), and Record Grid components to the left side.
You've configured a record grid before and this is very much the same. Here is what you need to know about its
properties:
The Record Definition, of course, is Restaurant
Enable Row Selection is Single row.
Grid Columns should include:
Name
ID (set Visible by Default to be off).
The idea will be to bring up the New Restaurant Blade from the New Restaurant button, then refresh the record grid.
Let's configure the properties accordingly.

Use these actions:
Note that the Refresh action will help the user experience quite a bit, by giving the user immediate feedback after
creating a restaurant.
At this point you can save and preview your view. It should let you create some restaurants and these should appear in
the grid.

Now configure the right side.
Drag another Container component to the right side. You can give it the Name of Details if you like. As mentioned earlier,
the only reason to put an extra container here is to have all the detail components on the right side hidden by default.
They will become visible only when there is a selection in the Restaurant record grid, and there is therefore valid data
available. To configure this, note that the Container has a Hidden property which is not on by default (in other words, the
Container is visible).
To get the effect we want, click on Hidden, then select When condition is true. This now lets you specify exactly when
the right side contents should be hidden.
To do this, build an expression for the Condition property that will be evaluated to mean that there are no selected
records in the restaurant's grid. The way to express this as a Condition is to say that the currently selected ID column
value from Record Grid (Restaurant) First Selected Row is equal to NULL. At runtime, this will effectively cause the
Details container to become visible only when there is a grid selection. The Edit Expression dialog should look like this:

Since the Details Container is still empty, you can't test this effect just yet. Let's fix that by dragging in some content to
the Right side.
Drag in Button Bar, Action Button, and Record Editor components into the Details container.
Ignore the Action Button for the moment.
Up to now, we have only used record editor components where the Mode was Create. This time, we want to tie it to a
specific record Instance of Restaurant - something you can only do where Mode is Edit. This requires creating an
expression that must resolve to a valid record ID for a Restaurant. By binding the Record ID property to the Record Grid
(Restaurant) First Selected Row ID, the editor will always show the details of the Restaurant record selected in the grid.
Furthermore we can make it look nicer for display purposes by clicking the checkbox for Show a read-only state for this
component. To finish it off, add some fields from Restaurant.

You can save and preview here. When nothing is selected, nothing within the Details container should appear.
When a Restaurant is selected, the details appear.

A powerful built-in capbility of the record editor is that users can themselves switch into an editable form for updating
Restaurant data (users can click the Edit link, and this automatically adds a Save button that works without any further
configuration).
To complete the view, we will work on the UI for working with dishes now. First, let's add a Record Grid to show the
associated Dish records. Start by dragging in a Record Grid Component to the right side, underneath the record editor
(but still in the Details container).
The grid properties have a twist here, because we don't simply want to specify a Record Definition. We actually also need
to specify an Association to use (that has Dish on the "many" side), and the Associated Record ID. In this case, we can use
the same old Restaurant ID we have already used twice in this view.
Add some columns to the record grid for Dish, such as Name, Price and usually we like to add ID as a hidden column also.
The configuration of the Record Grid for Dish will look like this:

You could save and preview this, but there won't be any Dish records associated yet, so the new record grid will always
be empty. Therefore, the last step of building this view is is to configure the New Dish Button so that it does this. Luckily,
there is a specific action called Associate Records that does exactly this. We use this instead of Open View.
Each property of Associate Records needs to be set. Most of these are obvious.
1. Record Definition to Associate: choose Dish

2. Association to Use: select Restaurant provides Dishes
3. Associated Record Node Side: select Provided Dish
4. Associated Record ID: this refers to the Restaurant to which the Dish records are associated. Once again, use
Record Grid (Restaurant) First Selected Row ID.
5. View for Selecting or Creating Associated Records: this is none other than the view we created earlier, New Dish
Blade. Here is where that Output Parameter - set to the ID of the new dish - is needed to implicitly make this
work. A view that does not "return" a valid ID that matches the association requirements will not work here.
Now you are ready to save and preview it in all its glory. You will notice that each Restaurant has its own particular Dishes
which is exactly what the associations capability is all about.
Challenge
Earlier, you configured the application shell to have a menu Item that launches the New Order View. Now, update
the shell definition so Leon can get to the Restaurants view you just created.
You now know how to have a record editor in sync with a record grid to edit data. You will notice there isn't a
way here to edit a Dish's data after it was created - at least, not in this view. Add this feature.
If you have the Util library installed, you can use its custom view component Display Image, to show the photo of
the selected Restaurant, and the photo of the selected Dish.
What we learned
We've covered a lot of ground here, and these patterns will be very useful in creating similar kinds of interactions using
BMC Helix Innovation Studio's view designer.
We've created and used helper views for creating records
Used a view output parameter

Used the Open View action
Learned about using a record editor's Edit Mode to display data in a read-only fashion.
Used a record grid with a built-in constraint to only show associated records.
Used the Associate Records action with a record grid.
We will build on these same techniques when putting together the remaining views, as well as introducing more powerful
patterns as we go along.
Now that we can create a real menu of meals, it's time to enhance our original New Order view to take advantage of this.
#BeFearless #BeFocused #BeFirst
Enhancing our New Order view to use associations

The requirements call for someone with the Meal Program Member Role to be able to submit an order for a specific dish.
Cleaning up the view

In the earlier exercise, we built a very simple view called New Order, but this didn't use any information about Restaurant
or Dish records. Also, before we forget, make sure that this view has granted access to the Order Submitter role.
Now to add support for ordering a dish. This is easy to fix. When we last saw our New Order view, it looked something
like this:
We see that the user puts some text into the Description field (originally called Details in this view) and submits. The
order is more complicated now, however, in several ways:
The user picks the Requested Date.
It needs to be associated with a Dish (that happens to be associated with that Restaurant). The Order will no
longer uses the Details Field; we are going to retire it. That is now replaced by its association to Dish.

It needs to be associated with a Restaurant. This is also new.
It can be associated with multiple Person Records; another new feature.
The record grid should show more relevant details.
The view we are building here will look like this (the actual position of the fields is somewhat up to you).
Luckily, all of these things are very easy to do because we have set up the data model very nicely, and we can use a
powerful view component that we haven't touched on yet, called Association.
We will need to clean up the fields:
Mark the Details (that is, the Description) field as Hidden At All Times. We are not currently going to use it,
though eventually it might be useful to generate some kind of "one-line" description of the order automatically.
If necessary, add the Requested Date field (or make sure the Hidden checkbox is cleared if it was already there).
Add the Special Instructions field.
Since we will be adding new components, we can improve the experience by laying them out in a multi-column way. You
already know how to do this: by adding a Container component. The difference here is that you can drag it directly into
the record editor component for the order, make it 2 columns, then drag the Date Requested field into the left side
(leave the right side empty for the moment). The hidden fields' position in the layout does not matter.

Adding dropdowns for Restaurant and Dish associations

For the associations to a single record, like Restaurant and Dish, the idea is that the user will pick Restaurant from a
dropdown list, and based on that selection, will the pick the Dish. Both of these are done by adding an Association
component and configuring it to act like a dropdown.
Let's think about what this means. Consider the data model we came up with during analysis; recall that there is a third
association involved here: the one that constrains selection of a Dish to be associated with a given Restaurant. The
following diagram shows the relationships involved.
Three-way Association Constraints

Three-way Association Constraints
Logically, we would only use a dropdown UI for selection when there is exactly one record on the other side (the "one"
side of the relationship). The second dropdown would in effect be a "cascading picklist" based on the selection of the
first one.
Drag in a Association component from the Palette directly into the record editor for Order. At first, it does not look like
a dropdown, but this changes once the Association Editing Mode option is picked. Note that you want to see all the
Restaurants, so we will leave the Filter By Association as blank.
Now repeat this to create a Dropdown for Dish. Note the additional properties exposed for Filter By Association.

When you specify the record ID associated with Filter by Association, be sure to pick the ID from the Associations part of
the Edit Expression fialog. The full "path" is
View Components Record Editor (Order) Associations Restaurant Fulfills Orders First Associated Record ID

At this point you can save and refresh your preview (or shell). If you have created some Restaurant and Dish data (using
the Restaurants View you have completed earlier), you will see them appearing in the dropdowns. Note that the Select a
Restaurant: dropdown shows every Restaurant, and Select a Dish: only shows the Dish Records that are associated to the
Restaurant.
Associating persons to the order

Of course, we aren't done with associations. Recall the requirement that Maria can specify a list of persons who will be
consuming the lunch.
Once again, the Association component comes to the rescue; but this time we won't use the Association Editing Modeof
Dropdown, because there are more than one possible Person record to be associated. It does require that there be a
view already created that has an output parameter that returns a set of selected Person records. Luckily for us, the
Foundation Library already includes exactly such a view, called PER Person Search. Let's configure it.
This time, drag a new Association component to the right side area. Configure the Record Definition to Associate.
Tip: recall that the easist way to find definitions in the Foundation, or any other library, is to search for them:
The rest of the properties are straightforward (you will have to search to find PER Person Search). Note that because
there is no Many:1 association selected these records, it doesn't even offer you the Pulldown option.

You will find that the Association component comes with quite a bit of built-in functionality that handles this case very
nicely. You can try it out when you save and refresh your preview (assuming you have created or imported some Person
records in the Foundation - if not there will be none to select from).
A blade with the PER Person Search view appears. If any records have been defined, they will appear here (if not, you can
go to the Administration Tab Foundation Data Manage People Person screen and create a few). Select some Person
records and click the Select button.

When you click Select in the blade, the associations to Person are created in a state that reads to the user as Pending.
Once the order is submitted, the associations are created on the back end at the same time as the Order record instance
. If you haven't done so already, be sure there is a Refresh action as part of the order's Save button actions, so that after
the Order is submitted, the record grid is automatically refreshed.
Use associated data in the record grid

Make the following changes to the record grid configuration:
1. Remove the Details column (we are no longer using that field).
2. Add the restaurant name:
a. You will find it in the Associations tab of the Available Columns in the Add/Remove Grid Columns dialog.
b. Drag it in as the column identified by Restaurant Fulfills Orders Name
c. Because the user will just think of this as the restaurant name, change the Label to Restaurant
3. Add the dish name using very similar steps to the above.
You should now have a completely functional, revised New Order view that understands associations.
What we learned
Because the association definitions were already in place, creating this functionality was actually a bit of a breeze. We
learned that:
Fields within a record editor can be layed out using container components too.
Action buttons can similarly be placed within a record editor's layout.
You can use the Association component as a dropdown to allow users to select a single associated record.

You can also filter it the Association component to create a "cascading" effect when associations between the
selected records themselves are defined.
You can use the Association component as a special list UI that can use a configured view for selecting "many"
records to associate.
The Foundation already includes re-usable views for its data, as well as record definitions and associations.
Maria now has a way of creating an Order record and specifying a Dish, and multiple Person records for it. We could
imagine a much improved view that allows Maria to "shop for" a Dish and then create an associated Order. However, that
gets a bit more complicated and we will leave that as a project for the reader.
Now let's turn to the last view we need in order to fully enable the Order Lifecycle Process to handle the requirements -
namely, a view that shows order status and lets users update it.
Defining a view for managing orders

We are pretty close to having a complete set of views that do what we need for the basic user stories. We still need to
provide some way to interact with the lifecycle of orders - for example, to move an Order Status from Submitted to In
Progress, Complete, or Cancelled.
Overview
As usual, we should think about the design of the view as a whole before we dive in to adding components. In terms of
layout, this one will be a lot simpler: it’s basically a list of orders. Leon would expect to see the Dish and Restaurant
record information brought right into the list. It would also be very nice to also have a list of employees who will be
receiving the selected order, case there is a problem with it.
The result might look like this:
Also, we will introduce a new concept here: using a hidden record editor to directly modify the Status of the Order
record on the click of a button; we will keep it out-of-sight in its own container at the bottom of the view. As we have
done before, let’s look at the underlying structure of the view diagrammatically:
Order Status View Layout

Order Status View Layout
To build this, the important things to know are that:
Record grids can be automatically filtered to show associated records only. You will see this in the employee list.
In other words, to implement this, you do not need to worry about database joins or foreign key fields.
The record grid has a built-in button bar that is automatically exposed whenever there are Action Button
components there, and only when there is a current selection in that record grid. Otherwise the button bar is not
visible and is replaced by standard refresh and filtering controls. All this behavior is completely automatic except
that you need to confgure the button actions.
You can hide a record editor in the view (or, more precisely, place a record editor within a container component
that is always hidden). Just as when you are using a visible record editor, it can synchronized with the record grid’
s selection. Effectively this creates a data model in the view’s memory that can be used to invisibly manipulate
data.
An Action Button (in this case, placed in the record grid’s button bar) can have multiple actions combined to do
useful things in a view. Here, we would like users to be able to instantly update data in the database and record
grid. One technique that we will use could be called “push and refresh”. It consists of the following sequenced
actions:
Set Property – updates the hidden record editor’s data model as desired, such as setting the Status field
value.
Save – asks the hidden record editor to push it’s changed values to the backend Record Service.
Refresh – ask the visible record grid to refresh, in order to show the updated value instantly and give
feedback to the user.

These hints may already be enough information for you to compose the view and compare it with the "finished"
screenshot above. If you become stuck, you could follow the following general steps for the trickier parts.
Start by creating a new view (Container layout) called Orders and give it both permission roles: Order Submitter and
Restaurant Manager. Add the Rich Text component for the header.
Hint: It is a good idea to give your container a Name so that it will be displayed later in the Edit Expression dialog.
Otherwise, it can be tricky to identify the right Container to find the components you are interested in.
Build out the nested containers structure as shown in the diagram - this is similar to what was done with the Restaurant
Details container for the Restaurants View.
Displaying orders
Add the record grid for Order and set Enable Row Selection to Single row as usual.
The Column configurations are interesting here. As we did in the New Order View, you can bring in columns from
Restaurant and Dish because each Order is associated to exactly one of these. As before, this is a great example of
changing the Column Header to be meaningful (otherwise, Dish and Restaurant fields that are both called Name will both
show up as Name).

Displaying associated employees

For the record grid component for Employee, placed in the Container component on the right side, it’s important to
specify the Mode as Association and not Record. Once you identify the Record Definition to Show as Employee
(remember that you will find this using search because it is in the Foundation library), you will then be asked for two
additional pieces of configuration:
The Association to Use: select Orders on Behalf of Employee
The Associated Record ID: you will want the ID of the selected row from the Order Record Grid as we did
previously to bind a record editor to a grid selection; find this using the Edit Expression dialog. Note: if the ID
column is not there, go back and add it and make it not Visible by Default.
Columns: probably all you really need here is something like Full Name and perhaps the Primary Phone Number.
After all, the most that might happen here is identifying someone here giving them a call. You could also navigate
to some UI that shows more information about them, such as their manager, and so on. However it's worth
noting here that record grids can only show associated data "two levels deep" (that is, they cannot show
associations of your associations).

Instant updates for the order

At this point, the view is functional in terms of displaying Order records, but doesn't allow any modification of them. Now
this view is going to get much more interesting - it is going to provide a way to update the Status with the cick of a
button.
As described earlier, ahidden record editor for Order is needed for the “push and refresh” of status information. After
dragging it in to your hidden container, make sure it is in the Edit Mode and Record ID property is pointing to the same
selected ID from the order grid.
Hint: you can can leave the container's Hidden property as Never while you are trying out the technique, and change it to
At all times later on once you are confident that the view works correctly.

Creating the button components to instantly act on a selected Order is a very useful technique, and turns you into a true
view designer “power user”. Let’s see the detailed steps to implementing this for one case: setting the Status to In
Progress with a click of a button (the other updates are almost identical to implement). Before we start, let’s review the
requirements for this Button. Recall that it needs to
Instantly update the Status value on the back-end (this will be a combination of Set Property and Save actions).
Allow the user to see the updated value of the Status in the record grid (this is a simple Refresh action).
Let’s go through this step-by-step.
1. Drag an Action Button into the built-in button bar at the top of the grid (note: if you drag it anywhere else, it will
be visible at all times, even when there is no record grid selection.

2. Set up the Action Button properties the way you like. Although normally a button's Label should be some "action
word" (verb), like Update to In Progress, but in this case it might be clear to users enough simply show up as In
Progress. The following screenshot also shows the Disabled Condition but you should leave this configuration
alone for the moment, until the update behavior is working correctly. - for now just leave that blank.

3. Add a Set Property action the In Progress button..
a. This is for changing the in-memory "model" of the Order record to set its Status to In Progress.
b. The tricky part of this is setting the right Property Path expression. You will need to “find” the right Status
element that will be updated, and in a complex view this might take some exploring. Note that you are
only specifying the path to the value here, not the new value.
c. For the Property Value itself, choose the new selection value In Progress from the Options under the
Status field as shown:

4. To actually persist the change, the next action will be a Save on Record Editor (Order). Do not use Close after
Save here because we aren't in a dialog.
5. Finally, add the Refresh action for Record Grid (Order) - this way the updated Status value will be reflected
immediately in the record grid.

At this point you are ready to try it out, by launching (or refreshing) the preview browser tab. Select an order that is not
in the state of In Progress and use the In Progress button to update it.
A final enhancement to this technique: think about under what conditions the user will be clicking on In Progress.
Remember that the purpose of the Action Button is to advance the Order record through its lifecycle. In this case, the
lifecycle essentially progresses from Submitted to Closed (or Cancelled); this is one reason that the Status values have
numeric equivalents which go from 0 to 40.
Consider the times when should a user see the Action Button as enabled. After all, a user should not expect to be
marking an Order as In Progress if it has already reached or surpassed that phase of its lifecycle. Letting a user do that
could be very confusing. We would like to only enable it conditionally, which is very easy to do in the view configuration
without the need to write code. Here is the solution.
In this case, you will notice that most components have a Disabled property, which is set to Never by default. What we
would actually like to is to specify that the In Progress action button should be disabled whenever the selected Orderhas
a Status value of, or numerically higher than, In Progress. By using the inequality of >=, the logic is less fragile by handling
intermediate states because it handles the state "jumping past" the normal sequence. Let’s configure this.
Note that the Condition here is about when it should be disabled, not when it should be enabled. To understand the
meaning the other way, this button will only be enabled when the state of the Order has not yet reached In Progress.
Once you have tested the In Progress Button behavior, use it as a kind of recipe to implement the similar behavior for
Delivered and Cancel Buttons. You can re-use the same hidden record editor for each one, but each action button will
need its own actions list and its own Disabled conditional expression.
Once all the buttons have been implemented, to test this more fully, try selecting orders, one at a time, some of which
are still in Submitted state, and some in later states. If we have implemented this correctly, the later states should have
the In Progress button as disabled. The following test cases show each button tested against all the lifecycle states.
Note that these screenshots show exactly the same kind of logic to create "smart" Action Buttons for Delivered (hidden
when Status >= "Delivered") and Cancel (hidden when Status >= "Cancelled"). You can re-use the hidden record editor,
but just set Status to different values.

Did it work?
If the Action Buttons are not enabled at the right times, or don't seem to have any effect, here are some things to check:
The Save action is effectively disabled when not all required fields in the Order record have a value. Since we did
add some required fields along the way, make sure you have provided missing values, or just remove these older
record Instances using the Edit Data feature.
Are you using the correct Property Path for the Set Property actions? These can be confusing because the
individual field components show up as well, such as Status, but we always need to identify the Record Instance
itself.
As mentioned before, the Disabled conditional is not evaluating when to be enabled, but rather when it is the
opposite (disabled). Make sure your logical expression isn't the reverse of what you intended.
As before, you will find that if there is a Description field in Order that has no default, the Save action may silently
fail.
Make sure the Refresh actions are pointing to the record grid, not a record editor.
Update the shell

As before, be sure to update the shell of the application to have access to this view. It should now look something like
this:

Challenge
Set up the filtering of the record grid for the Order records to exclude orders that are Completed by default.
Display the Special Instructions information for the currently selected order (not just as a column in the record
grid). If you want an extra challenge, display the information in a non-default font.
Build a simple view to display the details of a Restaurant. Launch this view as a centered modal dialog, by clicking
on a restaurant's name in the record grid for Order.
What we learned
Record grid components can include columns from a singly-associated record
Record grid components can be constrained to show multiple associated records as rows
An easy way to hide components is to put them into a Container that is Hidden - At all times.
Container component Name is optional, but a great way of making it easier to find the one you want later on,
especially in a complex view.
Components can have conditional properties, such as Disabled and Hidden.
An Action Button can be configured to do many things, such as an sequence that effectively updates a record in-
place.
We have come a long way toward building a complete and useful application, and learned a huge amount of BMC Helix
Innovation Studio skills along the way. The data model and UI are completely functional.
Now that we can actually associate data, and easily manipulate the Status of an Order, we should turn our attention into
building out the Order LIfecycle Process to implement the required user stories.
Creating a view to order from a dish

We now have a fairly complete application: we can manage the menu (restaurants and dishes), order a new dish, and
track it through its lifecycle. If you are eager to get started with the application's order process, you could skip this
section, since it is not really adding any back-end functionality. However, from a learning perspective, going through the
following exercise will help you learn about some powerful techniques, including displaying pictures in a view, and calling
a process directly from a view to help control your logic.
Let's consider the current state of the Lunch Tutorial application. You might notice that the user experience of using the
New Order view we created earlier is not ideal. For example, users have to pick a restaurant, then pick the dish from the
drop-down. A better experience, and one more natural for users, would be to browse through the available dishes, and
simply order one, as one would from any e-commerce site. Also, recall that we have defined restaurants and dishes to
have photos and long descriptions; but these aren't much use to the user unless they can look at them before choosing
to order.
We can solve this by creating a pair of new views: a Dishes view (independent of restaurant choice), and a Dish view to
show all the details of a dish and allow quick ordering of it. This will require some view-building techniques that are a bit
more advanced that what we have seen with previous views, with even more nesting of containers and use of advanced
button actions.

Note: if you have not yet installed the util-lib package that was described at the beginning of this module of the tutorial,
you will need it now in order to show pictures in your views. If you don't have it, you can download com.example.util-lib-
1.0.zip now and install it using the Install command from the workspace.
Important
The goal is to create a Dishes view that will look like this. You can see that we are now able to effectively use the picture
and text for the selected restaurant (implied by the dish) and the dish itself.
Clicking on the dish's name brings the user to the Dish view, where the user can immediately order it by providing the
few details needed.

Build the Dishes View

Starting with the first view, it is clear that it is a relatively simple list of Dish records, but also shows additional associated
information about each one when it is selected. As usual, let's sketch out a layout for the components before beginning
to build it in the tool. Note the three levels of nested containers: Main (2 columns), with "Details" containing both
"Restaurant" / "Dish", each of which have 2 columns also.

The easy part of this is building out the list part, as it involves components we should be familiar with from previous
views.
1. Create the new view (of layout type Container) and name it Dishes.
2. Add the "Available Dishes" header using a Rich Text control.
3. Place a new container below that, with 2 columns; you can set the proportion however you like.
4. Add the grid on the left side, setting Record Definition Name to Dish.
a. Set the Enable Row Selection option to Single row.
b. Configure the columns.
i. Consider that the grid will be doing more than just showing visible information: it will also be
pulling in data that will not be displayed in the grid, but will be available to be formatted nicely in
the rich text controls that will eventually be added to the right hand side. Also, we take advantage
of the ability to include columns from associated records to pull in information about the
restaurant.
ii. Note that large text fields (such as the About fields) will need to have Sorting enabled turned off.
iii. Here is one set of columns that will allow this to be done (if you don't remember how to bring in
associated columns, check the documentation or some of the earlier parts of this tutorial). Recall
that it is often a good idea to re-label associated fields, such as changing the restaurant's Name
column to Restaurant to avoid confusion with the dish Name.

At this point, if you save and preview the view, it should look like this:
Now let's add the single-column "Details" container to the right hand side. Set its Hidden property to be conditional so
the container only appears when there is a grid selection.
Now we will add the restaurant information here.
1.
1. Within the "Details" container, add another Container control with 2 columns (you can use a 5/7 ration for their
width); call this the "Restaurant" container.
2. On the left side, drag in the Display Image component from the palette (it will be there as long as you have
installed the Utils library; alternatively, it is also found in the Task Manager Library) and configure it. Note that you
will only be able to get the Restaurant ID from the grid if you had previously added it as a hidden column.
3. On the right side, drag in a Rich Text component and configure it
a. Insert an expression using the Edit Expression dialog
b. Select the Restaurant from the selected row of the grid.

c. Add static text, and insert an additional expression for About Restaurant, and format to taste.
4. Save and preview the view, to make sure it is showing a photo and blurb about the restaurant correctly when a
dish is selected.

5. If desired, add another rich text below the "Restaurant" container to create a horizontal rule (you can just use
dash characters for this).
6. Now repeat these steps for the "Dish" container. This time, you will be configuring the photo using the ID from
the grid, and About field to get the detailed information. You can also format in the Price of the dish in the same
fashion. Remember that you can add any other information about the dish simply by adding it to the grid
configuration as a hidden column, and then formatting it using the rich text.
You should now have a fully functioning view. If the containers are nested properly, and the "Details" container has the
Hidden condition set properly, the photo and blub will only appear when a dish is selected. If both "Restaurant" and
"Dish" containers have the same column ratio (5/7) then the photos and text will also appear to be vertically aligned.
At this point, all the user can do is browse through the dishes. What we want to do, however, is enable the dish Name to
be clickable, to bring up a view of the dish for ordering purposes. We will build that view first, then come back and enable
the Name column to be clickable.
This is probably a good time to go ahead and add the Dishes view to the application shell, so it appears as menu item.
You could call it Menu, because that is how the end user should think of this view.
Now you can test this view in the context of actually running the application.

The user can browse through dishes, but can't order them yet, so we will turn to adding that functionality next.
The Dish View for Ordering

Let's dive in to creating the second view, in which the dish is displayed and can be ordered. When we are done, it will look
like this:
When we think about the information architecture of this view, we can note several challenges that we will have to solve.
Information about the dish needs to be displayed right at the top, without the user clicking anything. We can
easily use the same controls to display this as we used in the Dishes view, but one thing we are missing is the dish
information itself (the dish ID, description, and price). There are multiple ways to solve this:
We could pass all the required parameters in explicitly (ID, description, price, etc). This may make our
view harder to re-use in different contexts, however.

We could simply pass in the dish ID, because we can use that to load the other Dish fields from that using
a record editor in Edit mode. This is what we do here; furthermore, we will keep this behind-the-scenes
record editor within a hidden container, because the end-user does not need to be aware of how we are
loading the data.
Obviously we will need another record editor for Order, in Create mode - this time, it will be visible for the end-
user to use. That's easy to solve.
To complete the experience there will also need to be an association component for adding the Person
consumers to the order, exactly as we did in the New Order view.
The most complicated thing is the button to send the order. When the user saves the Order record, we will
somehow have to associate the order with both the Dish record, as well as the indirectly associated Restaurant
record. Let's consider three different approaches to this.
We could put back into the view the two association components for Restaurant and Dish; this means
asking the user to explicitly re-associate the restaurant and dish before saving. But this would be a terrible
experience, since they have already selected the dish they want before coming to this view; it defeats the
main design purpose of this view.
We could have a rule configured to run "On Create" of the Order record and have it do the associations
for us. This will work, but will get pretty messy. The problem here is that the process needs to know the
dish ID in order to do this, and the only way to pass information like that to this process would be to place
it in a temporary field before creating it. This wastes database storage. Also, it would mean accessing the
system field that keeps the foreign key of the restaurant; not something the UI logic is supposed to be
playing with.
The cleanest way to solve this, and what we will do here, is create a special process to perform the
association. Rather than trigger it from a rule such as "On Create", which would require a temporary field
to pass the dish ID, we can use the Launch Process action right from the same button that saves the
Order record. Since we already have the Dish ID available in our view, we just pass it directly to the
process to create the necessary associations. Don't worry if this is not yet completely clear; there will be a
complete explanation of this technique when we get there in the step-by-step instructions.
Given these design decisions, we can sketch the layout of components that we will need to make this view successful.

Displaying Dish Information

The first thing we should do is make sure the Dish record is loaded up when the view is shown. For this we will need to
create a view Input Parameter - we will call it Dish ID.
Add the "Info" and "Hidden" containers.

Drag in a record editor to the "Hidden" container, set it to Edit mode, and bind it the Dish record definition, where the
Record ID is set to the Dish ID view input parameter. You will need to add the required fields. Remember, the only
purpose of this record editor is to load the dish details when the view loads, so they can be referenced in the "Info"
section. You can almost think of this components as the "model" of the dish data within this "view".
Now we can configure the "Info" contents, which are going to be visible.
1.
1. Make sure it has 2 columns.
2. On the left side, add a Rich Text component.
a. Insert an expression for the dish name, and style it as desired.
b. Insert an expression
c. Grab the Dish Name
d. Style the name

e. Do the same thing for the description about the dish, and price.
3. On the right side, add the Display Image component and configure it, just we did for the Dishes view earlier.
At this point, you can save and preview the view. Note that you will be prompted for a valid Dish ID, which you can obtain
using the Edit Data feature from the list of record definitions.

At this point you should be able to see the information about the dish. If you are also seeing the record editor at the
bottom of the view, it is probably because you did not yet mark the Hidden attribute of the container as At all Times.
Hint: once you have a preview browser tab for this, the URL contains the parameter directly. So, if you keep this tab
around, you can simply refresh it when you want to try the latest definition, without having to launch it from Preview
again and paste in a Dish ID.
Placing the Order

Now we need to provide a way for the end user to order the dish. We essentially follow similar steps to those used to
create the New Order view - with two major differences.
We will not need to ask the user to specify the Restaurant or Dish - the view already has that information.
We will need to build out some special logic to associate the new Order with the dish and its restaurant, using a
small helper process.
Between the existing containers "Info" and "Hidden", place a record editor component for the Order record in Create
mode, and follow the similar steps as before to create the rich text label, get the requested date, and the associated
persons.
One easy way to build this out is the following sequence of steps:
1. Bring in the Record Editor
2. Drag in a Container component into the top part of the Record Editor component itself, and set it to 2 columns.
If you want to name this, you could call it "Order Fields".
3. Drag in the Rich Text on the left side for the "Order it Now!" label.
4.
4. Below that, drag in a Date component.
5. On the right side, drag in a Text Area component.
6. Below the text area, drag in an Association component.
7. Drag in a Button Bar, and then a Button, within the record editor area but below the Container.
Now you can complete the configuration by binding the fields for Requested Date and Special Instructions.
Just as we did in the New Order view, configure the associations for Person (remember, you will find this record and
view name in the Foundation, not in this application).
Give the button the label Save. At this point, the layout for the order record definition looks like this:
To configure the button, however, will require a power technique of creating a special process to be invoked by the view.

Creating the Logic to Save and Associate the Order

Let's consider the button actions we will need. We can start by configuring the regular Save action for the Order, as we
did with the New Order view previously. Make sure you pick the right record editor to save (there are two)!
Is this enough? Well, it will accomplish part of what needs to be done - saving the order. However, if you try out your new
view, you may notice something is missing from the data - the associations to it's dish and restaurant.
On the one hand, we have made the UI simpler for the end-user because they do not have to pick the restaurant, or dish,
within this view. On the other hand, the associations are important and still need to be created. How can this be
automated so that the user does not have to specify it explicitly?
The answer is that we can create a small process - like a kind of script that we can triggered from the Save button itself -
using the Process Designer. The process will take the Dish ID and the Order ID as input variables (parameters) and use
these to accomplish this. It will also be necessary to load the Dish record into a local variable in order to access its
Restaurant information. The following diagram illustrates the logic of this process - remember that you can click on it to
make it more readable.

We can now build out this process, following these explicit steps.
1. Back in the workspace, go to the Processes tab and click New.
2. Give the process some name, such as "Associate Dish and Restaurant to Order"
3. Add three variables to the process
a. Click the Add / Remove Variables button.
b. Add an input parameter for Dish ID.

c. Add another one for Order ID.
d. We will also need another Local Variable that will be used to load all the information about the Dish (in
order to access its associations). It will be used only during the execution of the process. Let's declare
that now. Note that it is not an Input/Output Variable, and its Data Type must be set to Record, and the
record definition is Dish.

d.
e. Once you save the variables, the process properties tab will now show a summary of your variables, which
should look like this:
4. Associate the Dish to the Order
a. Drag in the Associate Records activity from the palette.

4.
a. Portions of this document are BMC Confidential.
b. Give the activity a more descriptive name, and select the appropriate association.
c. Using the Edit Expression dialog, select the Dish ID input parameter as the value for First Record ID.
d. Similarly, set the Order ID input parameter value as the Second Record ID.

5. Load the dish record
a. Drag in a Get Record activity and configure it to load the Dish based on the Dish ID input parameter.
b. Configure the OUTPUT MAP of the activity to set the Dish local variable.

c. Use the Output of the activity as the value for the Source expression. This works because the output of
Get Record is always a full record object.
d. The configuration of Get Record is now done, and the summary should look as follows:

6. Associate the restaurant to the order.
a. Drag in another Associate Records activity.
b.
b. This time, to get the First Record ID, we will have to find the restaurant ID by looking in the associations
of our Dish local variable. Note that this only works because we placed the Dish variable in the OUTPUT
MAP of the Get Record earlier.
c. As before, the Second Record ID is the input parameter Order ID.
7. .Add the four flows to connect the activities.
8. Save. If you have any validation errors you will need to fix this and make sure all the configurations are correct.
Now that the process is done, it would be a good idea to test it, independently of the view that will be invoking it. One
easy way to do this is as follows:
1. Manually create an Order record, using the Edit Data feature.
a. Take note of its ID field value, for example, paste it into a notepad.
b. Verify that the order exists in the Orders view, and has no associations.
2. Similarly take note of an existing Dish record's ID field value, using the Edit Data feature.
3.
3. In the Processes tab of the workspace, click on Manage Processes button.
4. Select your new process and click Run.
5. Provide the Order ID and Dish ID parameters when prompted.
6. Click the Run button.
a. If the process completes successfully, check the Orders view to see if the order now shows the correct
dish and restaurant.
b. If it fails to run, the message may help you identify the problem in your process definition.
Finishing Up
First, we should integrate the new process with the Save button in the Dish view.
1. Add a Launch Process action to its action list, after the Save action.
2. Set the Process to Start and turn on Wait for Process Completion.
3. Configure the Order ID parameter by getting it from the record editor for the new order (the ID field value is set
implicitly by the Save action, as long as it runs after the Save action).

4. Configure the Dish ID parameter using the view's input parameter for Dish ID.
You should also add a final action to this button, to cause it to navigate to the Orders view. Presumably the user is done
with this view after placing the order.
Save the view.
At this point you can test out the full behavior of the view, using Preview, or go ahead and integrate it with the Dishes
view.
To add the hyperlink to the Name column of the grid of dishes:
1. Open the Dishes view.
2. Select the grid of dishes.

3. Click on Add/Remove Grid Columns.
4. Open the properties for the Name column
5. Turn on Make column value an Action Button.
6. Click Add/Remove Actions. In the Selected Actions list, and configure the link as an Open View action. Note that
the ID column must be present in the grid (it is normally hidden from users). Be sure to pick it from the Last
Action Row, not First Selected Row, because treating a value as a link does not involve selection.
The tooltip will confirm you got the right ID.

7. Save and test the Dishes view using Preview or by using the shell, including the behavior of ordering a dish.
What we Learned
Creating this view was loaded with power techniques, and also was a good review of many of the view-building strategies
we learned earlier.
Designing complex views starting from sketches, and then laying out the nested containers.
Using attachment field values to display dynamic images in the view.
Views with input parameters are not only for modal popups and blades.
Using rich text to format information in a nice way, with the model loaded in a hidden record editor.
By the use of the Launch Process action, and the Process Designer, sophisticated logic can be invoked directly
from the view, without using rules to run processes. This can significantly improve user experience without
requiring the use of custom UI code.
We have had a little taste of using the Process Designer just to add a little bit of functionality to a view. Now we will dive
into it much more deeply in order to build out the back-end lifecycle process for a lunch order.
Building the Order Lifecycle process

We now have an application that has a functional user interface, at least one good enough to start adding some of the
business logic of the application. We can always come back and improve the user interactions, but once the basics are in
place, each one can be worked on and improved in parallel.
Note: if you have not successfully completed the earlier view definitions, you should go back and do that now; or, you can
opt to uninstall your com.example.lunchtutorial application and install a pre-built version of it that includes the view
definitions, found in this package: com.example.lunchtutorial-3.0.2-INSTALL.zip.
Important

There is a lot to learn about building a business process; if you need help along the way, all the activities are documented
in Defining the application business logic through processes (see page 421). This tutorial will try to show the trickier
steps in a step-by-step fashion.
We will start by copying a new process from the Simple Order Lifecycle that we created in Module 1, and incrementally
enhance it, testing along the way, to build out the behavior called for by the requirements we analyzed in Module 1.
To recall where we were, we last saw Simple Order Lifecycle just supporting two phases, something like this:
You may notice that the labels of the activities don't match exactly what we did in the Quick Start exercise, where the
example included the type of the activity within the label as a convention to help understand what it was doing. In fact,
the labels are up to you, as long as they are unique. Also, note the annotations are optional.
This process updates the date information, but only after the Status field value changes to Delivered. In truth, if this is all
we wanted to do, it would have been easier just to create a rule that triggers After Update to perform the same action.
We didn't do that, because we knew that applications like this will typically have a much more complex lifecycle for their
records, and that building up a large collection of interacting rules would become very difficult to maintain or even
understand. One of the key lessons here is that using the process designer allows us to visually orchestrate the fulfillment
of requests in a straightforward fashion.
Consider the five Status values that now exist, and consider the implications for the Order Lifecycle, including these
behaviors:

More phases, including In Progress and a concept of Closed.
Automatic closure of an order some period of time after it's Status field value becomes Delivered
Notifications to the submitter, and to all consuming employees, when certain phases are reached.
The ability to cancel an order and send a notification
The final process we are building will take care of these requirements. We will build it out, step by step, so that as we go
the process can be saved, tested, and troubleshooted.
When the process is fully developed, it will visually tell the complete story of the business logic for ordering.
Along the way we will learn about some powerful concepts:
The Exclusive Gateway for branching the flow based on a Condition.
The Send Message activity for generating a "bell icon" notification for the shell.
The ability to loop over a list of things, in this case, the associated Employee records
A Timer for doing something based on elapsed time.

Throwing a Business Error that can be caught by some wrapper process, for error handling
There is a lot to learn here. Rather than take this all in one gulp, we will start with the first requirement: adding an In
Progress phase and a notification for that.
Adding additional states to the order lifecycle

The first step will be to make a new copy of our lifecycle process, so that the current application will be unaffected until
we are ready to test the changes.
Copying the process

Follow these steps to make a copy the process.
1. Go to the Processes tab
2. Select the checkbox for Simple Order Lifecycle.
3. Click the Copy button.
4. A copy of the process appears in the Process Designer with a blank Name. Note that it still includes the previous
activities and input parameter.
5. Give it the name Order Lifecycle.
6. Save the Process
Remember that the existing rule that runs this Process on After Create of Order records is still invoking Simple Order
Lifecycle, so this new process will not yet be run when creating a new order. We can make that change when we are
ready. In other words, we can consider this new Process as a kind of "draft".
Now we can move right into working on the process.
Add an in-progress phase notification

For this overall step, we will add an additional phase to represent In Progress, before the Order reaches the Wait for
Delivered activity. We will also add some of the required notifications that were mentioned in the user stories.
First, move around the elements a bit to make sure there is room for two additional activities before Wait for Delivered.
Insert a new User Task into the flow to represent Wait for In Progress. Drag one in and configure it in the manner as you
did in Module 1, setting the Label to Wait for In Progress. Remember that it will be an Existing Record, and that the ID
comes from the input parameter, but that the Completion Criteria must use Wait for In Progress to find its values for
comparison.
Hint: check out the existing Wait for Delivered configuration, especially the Completion Criteria, to be sure you are doing
this correctly. This configuration is worth double-checking, or you will not get the result you expect.

Now drag in a Send Message activity which will be the next step in the flow. For its configuration, the Subject can be
whatever you like since it is not currently displayed in the UI and is only used for email output. The Body will be evaluated
and will appear in the bell messages list in the shell.
When building the expression for the Body, we see something very interesting: the Edit Expression dialog allows us to
find associated field information from our associations with Restaurant and Dish. This is very useful and shows the power
of having predefined association definitions in the data model.
To include information from the Dish, open the tree of values to find the Name of the associated Dish, like this:

Tip: you can easily move between the expressions for various properties without closing this dialog, by using the
buttons.
Now you can configure use of the restaurant Name in the message, the same way.

For the Recipients, in this case it makes sense to notify the person that actually submitted the order. This is easily
available as the Created By field from the Order process variable (our input parameter).

The whole configuration of the activity now looks like this:
The delivery phase notification

Now, add a very similar User Message activity to run in the delivery phase (after the Update Date Delivered activity). You
can decide what information to put there. We will add notification to each consuming employee in a later step: for now,
just send it to the submitter again.
At this point, with the additional activities, the process should look like this (note that the annotations on the right side
are optional):

Update your rule

Don't forget that the rule created in the Quick Start exercise, Start Order Lifecycle After Create, probably still points to
your old process, Simple Order Lifecycle. Make sure you either update the rule, or create a new one and disable the old
one (you will have to select again the General Current Record keyword as the value of the Order parameter).
Testing the process

We are now ready to give a quick test of this Process to see if it actually works. You have already learned how to test a
process using the Processes Manage Processes and Records Edit Data buttons. Now that we have a working UI, and
have actually created Restaurant, Dish, and Order records and associated them, we can test it using a combination of the
application itself, and also use the Manage Process console to troubleshoot it.
One easy way to do this is to have two browser tabs open: one with BMC Helix Innovation Studio, and one with the
application. In both cases, log in as the developer.
To test and troubleshoot the process, you can use the two browser tabs as follows:
Step In your Application What to Expect In BMC Helix What to Expect

Innovation Studio
1 Run the application. Submit a new Order record Order appears in record grid Under processes, Current actvity is Wait
instance using theNew Order View, including associated click the Manage for In Progress
Restaurant, Dish and multiple Employee records. Processesbutton.
Refresh the
instances.
Drill down on
Instance by clicking
on the Context Key

Step In your Application What to Expect In BMC Helix What to Expect

Innovation Studio
2 In Orders View, select the Orderand update it to In Notification arrives in the bell Refresh the diagram. Current activity has
Progress. notification area of the shell, about changed to Wait for
the Order now being In Progress. Delivery.
Refresh the browser tab (to force the bell notifications
to refresh quickly) NOTE: in order to see bell
notifications, you should create a
Foundation Employee record, and log
in as that user in a browser tab in
"incognito mode" (using a Google
Chrome example here). You will need
to grant the BMC Helix Innovation
Suite User Named license. If you do
not have permssions assigned yet,
you can make the user a Tenant
Adminstrator also.
When actually logging in, you will

need to add "@developer.com" as the
domain of the user, because this
Foundation Employee is actually a
tenant user of the special "developer"
tenancy. For example, if you create an
Employee with login id of "joe", you
would log in as "joe@developer.com".
Remember, logging in as the

developer user, which is what
happens using the Visit Deployed
Application link, will not show you
notifications.
3 Update the Order again to change its Status to Delivered Notification arrives about the Refresh the diagram The process is now in a
. delivery. The Order Status has Completed state.
changed to Delivered and the Delivery
Refresh the browser tab again. date/time field has the current time.
Troubleshooting
Did everything work correctly? If so, congratulations!
If not, don't worry, you will become used to troubleshooting processes sooner or later . This is not a bad place to
start. Here are some common pitfalls and ways to figure out how to fix it.
1. Did the process instance actually start? If not -
a. Is the Rule in place to launch the Order Lifecycle Process?
b. Is the Process in an Enabled state? Remember that Process Designer will automatically save it as not
Enabled if there are certain design-time errors that it caught.
c. Did you actually see the feedback in the Orders View that the Order was submitted?
2. Is the process instance in an error state?
a. This means that some exception may have been thrown at runtime.
3. Did it misbehave? Check each activity's configuration, especially:

3. Portions of this document are BMC Confidential.
a. User Task configuration can be tricky. It waits for the Order parameter's ID field, but the Completion
Criteria references the Status field from the activity itself (review the screenshot earlier).
b. Send Message configuration
4. Did notifications not appear in the bell icon? If you are logged in as the developer, see the note above - this is
normal behavior. You will only see notifications when you log in using another user, such as a Foundation Person
record (such as Employee). For ease of testing, if you are not concerned yet with permissions, just give this user
the "tenant administrator" role. Also, you will need to log in with your full domain, such as myuser@calbro.com if
your development environment was created with domain "calbro.com".
5. Last resort - pull over the Process Log using MC Remedy Mid Tier.
What we learned
Copying a Process and managing the Rule that calls it.
An efficient way to use the Edit Expression Dialog
The User Message Activity
A general method for testing and troubleshooting your Process execution in conjunction with the UI
Implementing Order completion using a Timer

Let's implement another phase of the process: Closure.
Think about the lifecycle of an order, and that fact that its status will eventually go to Closed (or Cancelled, which we will
deal with later). Of course, we could build a UI experience for someone having to close the order... and perhaps it will be
set to Closed through some other way... but perhaps this isn't really a thing a user should worry about doing manually.
Let's say that the requirement is that an order will stay in the state of Delivered for some period of time, then it will
automatically become Closed. It turns out that it's very easy too have our Order Lifecycle Process take care of this by
having a flow from an element called a Timer.
Adding the Timer

Here are the quick steps. Remember that you can always get more information from the documentation - if needed
please refer to Adding a Timer element to a wait step (see page 446).
The logic goes like this:
1. After the existing Notify Submitter of Delivery, the process should wait until the Order becomes Closed. Nothing
new here - we just use the User Task again.
2. This User Task should time out using a Timer element that is dragged onto it. For quick testing purposes, we can
set it to something small, like 1 minute.
3. The flow from the Timer means that after one minute goes by, it can branch to some other path. In this case, we
will flow to an Update Record activity that will force the Order record into a state of Closed.
The new steps of the process look like this:

The Wait for Closed Activity is standard stuff for us now - just configure it to use Existing Record, the order's ID, and a
Completion Criteria that uses the Wait for ClosedStatus to be >= "Closed".
Since the user may never explicitly close it, we can ensure it closes by drag a Timer onto the border of the activity. Set
the Interval to 1 minute just to make this easier to test.

Add drag and configure the Update Record activity. This one is very easy and is an activity we already used in the quick
start exercise.
1. Specify the Record Definition Name and ID for the order.
2. Add Status to the Input Map.
3. Set the value expression to "Closed" (including the quotes).
Set the flows to the End element in each case.

That's it! You are ready to test it.
Testing
This time it's very easy because the application UI is not affected, so you can test it using your view (by the way, when
you have only changed a process or a rule, there is normally no need to refresh the application page or preview).
To try it, create a new Order and set it to Delivered using the UI. About a minute later, refresh the record grid, and you
should expect the Status to automatically change from Delivered to Closed (you will have to refresh the record grid to
see the update).
What we learned
You have learned how to use a Timer to effect a time-out during a process. By the way, this is the first of four
ways a process flow can change dynamically (the others are Exclusive Gateway, Dynamic Call Activity, andError
End, and we will have a change to try all of these in upcoming lessons).
Actually it's worth thinking about when the Timer can be used. It actually only makes sense to use it when the
process is blocked, waiting for something. There are only a few things that cause this to happen; it is usually one
of these cases:
A User Task with some Completion Critiera
A Receive Task (we haven't used this yet in this tutorial)

A Call Activity to another process that itself blocks for some reason
Another more general thing to note from this: BMC Helix Innovation Suite is said to follow the Model / View / Controller
pattern. This really just means that you can approach data, UI, and logic as separate things. Using the Timer this way is a
perfect example of how you can enhance the application's behavior without touching the UI, because this behavior is
fundamental to the business process and should be true no matter how users are interacting with it.
Using a Multi-Instance Loop for Employee notifications

We still have the requirement that all employees who are consuming the order need to be notified when it is delivered.
So far, we have only implemented notification to the submitter of the Order record, using a Send Message activity. For
the Recipients property of User Message, we need to find the Login ID of each associated Employee record in turn in
order to notify them. How can we do this?
By now you will have already guessed that we will need to use the association definition we used in the New Order View,
called Orders Submitted on Behalf of Employees. As you recall, this is a many-to-many relationship, so any given Order
record can have multiple Employee records associated with it. Wouldn't it be nice if we could simply ask the Send
Message activity to act on a set of data instead of just one object? The good news is that the process designer supports
almost all activities doing exactly that: using properties that turn the activity into a Multi-Instance Loop.
Configuring the loop

The configuration for these properties can be a bit hard to understand the first time, so we will describe how the loops
work in general, and then show how the configuration works, step-by-step (for more information, please check out To
enable multi-instance loop in the article Creating process steps or activities (see page 434)).
For the purposes of this particular example, the important properties to configure are:
Input Data Item - this refers to a process Local Variable that can describe one instance of the data in question.
Before choosing this, the Local Variable must have been created first, so, setting this up is a prerequisite.
Loop Data Input - this is an expression that refers to the set of data to be looped over. When using associations,
this will be the Role Name of the association you want to use.
Once these are configured, the Loop Data Item can be used within this activity to refer to exactly one of the employees
that will be consuming the order.
The following diagram depicts visually how these configurations interact with the data in our specific example. The most
important aspects are the references to the associations, and to the Local Variable that will be used as the Input Data
Item. If you still find this confusing, don't worry, because we will show the details for each of the five numbered steps as
well. Remember that you can click on the diagram to make it more readable.

Let's walk through it step-by-step. As usual, we will "start from the bottom" and configure the prerequisities first, and
then put them together to complete the configuration.
1. Define a Local Variable that represents one Employee record instance.
a. Go to the Properties inspector (GENERAL properties).
b. Use Add/Remove Variables
c. Use Add Variable
d. Define the name of the new Local Variable. This label can be anything, but consider our convention
(described earlier) that the "many" side of the Association Role Name would be plural (in this case,
Consuming Employees). A nice convention for the Input Data Item will be to use the singular of that,
Consuming Employee, and this makes it pretty clear what your intention is in declaring it. It references
one from that set.
e. Choose the type as Record because it will represent a while record.
f. Choose the Record Definition as Employee (once again you will need to use the Search button to easily
find the Foundation's Employee record).

2. Configure it to be updated for every iteration of the Multi-Instance Loop.
a. Drag in a new Send Message activity and give it the label Notify Consumers.

b. Down near the bottom of the Property Inspector, in the MULTI INSTANCE LOOP section, choose the
Loop Type as Sequential. This now expands to show the other loop control properties.
c. From the Input Data Item pulldown, select the Consuming Employee Local Variable you just created.
3.
3. Identify the set of data to loop over. You need to find the right association Role Name to use.
a. From the Loop Data Input property, bring up the Edit Expression dialog.
b. In the Available Values tree, open Process Variables Order Associations
c. Drag in Consuming Employees into the Expression. (Note: don't be confused by the variable called
Consuming Employee - singular).
4. Leave the Completion Criteria empty (this is used only when there is some "early termination" condition you want
to handle, not when you need to process every element of the data).
5. For the Recipients property, access fields of the current Consuming Employee
a. The data we really need to use is the Login ID found under Process Variables Consuming Employee.
b. All we have to do is reference it in the Edit Expression dialog.

6. For the Subject and Body, use other Associations as we did with earlier Send Message activities, to pull in data
such as Restaurant and Dish.
Note that the Notify Consumers activity now shows its looping nature at a glance with the horizontal bars glyph.
Change the flow so our new Notify Consumers activity follows Notify Submitter of Delivery.
Testing
Now you can repeat the testing of the Order Lifecycle Process. One difference here is that the recipients of the User
Message may not have Developer credentials and therefore may not have access to run from BMC Helix Innovation
Studio. You may run into permissions problems for the first time here, and you can trouble shoot these now if you like. If
you simply want to test this new looping behavior, make sure there are some Employees who have the Tenant
Adminstrator flag set so you can see the Bell Notification behavior without any issues because of incomplete
permissions.
Challenge
Extend the Order Lifecycle to send one notification to the employee, and a different notification to the manager
of the employee.

Implement a broadcast notification to all employees
What we learned
Looping is a powerful technique. The important points are:
When configured with associations, it makes an easy way to traverse across related records.
You can also use it to traverse the Output of any activity that brings back multiple records, such as Get Records
by Query, or a custom-coded activity that returns an array (that is, a collection) .
The looping properties can be set on most activities
One, in particular, called Sub-Process, is very powerful. This is because the looping properties can apply to a flow
within your process where multiple activities can access the Loop Data Item.
The Completion Criteria give you flexibility to loop over anything, combined withe the Compute Value activity to
keep track of a loop counter (we will work with Compute Value more in a later part of this tutorial).
Now, we are ready to move on to the last part of our Order Lifecycle process: implementing the ability to cancel an
order using error handling.
Order cancellation with conditional gateways and exception handling

Up to now, we have been implementing what is more-or-less a "straight-line" process from beginning to end. Realistic
business processes are rarely like this, though. If there were never any dynamic conditions to handle, there wouldn't be
very much point in using the process designer to model it out.
We have already built the Orders View that allows users to set the status of an Order as Cancelled. We would probably
not think of this as the expected part of the life-cycle of an order, though - it is something unexpected. We will combine
two powerful techniques - Exclusive Gateway and Business Error (see Handling errors in a process (see page 452)) - to
create one implementation of this requirement.
Using an Exclusive Gateway for conditional flow

Let's say that while waiting for the Order state to become In Progress, somehow its Status field value became Cancelled
instead. We need to handle that. The simplest way to do that is to put a conditional check right after it wakes up.
Luckily, we have designed the process so far that when there is a "wait" going on, it "wakes up" because the Status value is
"greater than" where it was expected to be - Submitted at this point - so we know that it will, in fact, wake up. Note how
wise we were to have the most general condition possible there, because Status >= In Progress covers Cancelled as well
as In Progress.
We then can put an Exclusive Gateway element in the flow, so it can take alternate flows depending on whether it is
Cancelled or something else (like In Progress or Delivered). You might think that the easiest thing to do here is just flow
to a Send Message activity and terminate the process, something like this:

All of the conditional logic is built into the flows coming out of the Exclusive Gateway, where each can have a Condition
defined (the Exclusive Gateway element itself does not have any condition). At least one of the flows must have no
Condition defined; this is called the default flow. In this case, the default flow is to continue the process with Notify In
Progress.
To create the Condition that will cause it to flow to Notify Submitter of Cancellation:
1. Select the flow from the Exclusive Gateway to Notify Submitter of Cancellation.
2. Click on the Condition to bring up the Edit Expression dialog.
3. Create the expression in a similar way to the Completion Criteria of User Task, making sure to select the Status
field from Activities Wait for In Progress. This time, we are looking for an exact match of Cancelled, since this
flow is specifically to handle cancellation.

The flow properties now look like this:

The default flow coming out of the gateway now represents every situation where the Condition is false, including all the
other Status values greater than Submitted.
This works, and can be tested. However, let's consider the implication of this approach. This "brute force" approach to
handling cancellation will require that the handling of every condition will be by a flow to either duplicated handling (like
notifications), or, criss-crossing lines that will be become difficult to maintain. In this case, you can see that you will
actually have to include the Send Message activity, or another flow to it, from every place where a User Task can cause
the process to wait.
What would be nice is to have the ability to just jump out of the process whenever cancellation has occured, and handle
it in one place. We can do exactly that using the error handling capability of process designer. Perhaps more importantly,
we can use this case to understand how to consolidate error handling in one place in general.
Throwing a Business Error when the Status becomes Cancelled

Let's imagine that cancellation should interrupt the process, but you would like the handling of it to be elsewhere. We
can create a simple example of this by the following strategy:
1. Instead of terminating the process, a state changed to Cancelled should raise something called a Business Error.
2. We can write a "wrapper" process that will "catch" these errors, and handle them.
Conceptually the process runtime execution is like this (remember you can zoom in on this diagram by clicking on it).

A few interesting things to note here:
Throwing the error, through an element called Error End terminates the current flow, but does not terminate the
process.
The error can be handled by another event called Error Boundary, which can turn execution back into a "normal"
flow to handle it however you like (retry, send a message, do something else, and so on).
The Error Boundary - much like the Timer - has to be decorating some element that represents a "scope" of
execution where the Error End was executed. This could be a Sub-Process. We have chosen to make it a Call
Activity that runs the Order Lifecycle process.
Let's build this, starting from the Order Lifecycle process. The first thing we will do is replace the Notify Submitter of
Cancellation activity with an Error End and terminate the flow. The specific steps are:
1. Drag in an Error End element from the Events section of the Palette.
2. Select the Cancelled flow coming out of the Exclusive Gateway to Notify Submitter of Cancellation and drag the
end to flow to the Error End element instead.
3. Delete the Notify Submitter of Cancellation activity - we are going to handle this in the wrapper now.
4. Configure the properties of the Error End to have it throw a Business Error called Cancelled.
The Order Lifecycle process should look like this. Note how we configure the Business Error with a simple text name (we
will need to use this name later, so something like an identifier is appropriate).

Handle cancellation after delivery

We are assuming this would be allowed while an Order is In Progress (you could make a case that we should not allow
this, but for this tutorial, we will show how the wrapper will handle it for multiple cases).
Repeat this same technique as above by creating an Exclusive Gateway after Waiting for Delivery that flows to the same
Business Error.
The error flows now look like this:

Now, you can save and close the process and create the "wrapper".
Handling cancellation in the wrapper process

Create the new process, called Order Lifecycle Wrapper. Make sure it has the Order record input parameter defined, so
we can pass it down to the Order Lifecycle process.
To create this is pretty simple, and is mostly laid out in the conceptual diagram above. Here is a step-by-step:
1. Configure a Call Activity to invoke Order Lifecycle. Note that the entire Order input parameter can be passed
cleanly down.

2. Drag in an Error Boundary event from the Palette and attach it to the edge of the Call Activity, much as we did
the Timer earlier. Configure it with Add/Remove Errors to Catch a Specific Business Error. You should see
Cancelled in the list of Error End Event.
3. Drag in, and configure, a Send Message activity to handle the error by notifying the submitter, and connect the
flow from the Error Boundary to it.
4. Create the missing flows to the End Event to make the process legal.
The Order LIfecycle Wrapper should now look like this.

Updating the rule

If you thought you were done now, there is one thing you may have forgotten. What causes these Processes to be run?
At the start of this Module, you created a Rule that fires after Order creation, and it explicitly starts the Order Lifecycle
Process. Don't forget to go update that Rule to invoke the Order Lifecycle Wrapper instead.

That's it! You have now set up the logic needed to handle errors thrown by the lifecycle process.
Testing
You can test this exactly as you have tested the other enhancements to this process: changing the Status of the Order
and observing what happens. You should notice that when an Order is active, you will see both Order Lifecycle and
Order Lifecycle Wrapper processes in the Processes Manage Processes console.
Challenge
Branch your process unconditionally (execute multiple flows that then join up) to produce two notifications in
parallel.
In the Order Lifecycle Wrapper, instead of hard-coding the name of the Order Lifecycle to be invoked, configure
it to get the name of the process to call from an expression.
A new requirement has come in. Now, once the Order is In Progress, you will not be allowed to change it to
Cancelled using UI.
What we learned
You learned many cool and powerful techniques in putting in this particular feature:
An Exclusive Gateway can be used to make a conditional branch in a flow. The Condition is specified on all flows
except one (the default flow).
The Error End event can be used to terminate a flow without terminating a process
The Error Boundary event can "catch" an Error End without a flow being drawn between them, and handle it with
whatever logic is appropriate
One process can call another one using Call Activity. The process to call can be hard-coded or dynamically
determined.
Rules can be used to validate data submitted in the user interface.

Recap of Module 1
Congratulations! You have achieved creating out a modern, Enterprise-ready application without writing a line of code.
To do a quick review of all the techniques you have mastered:
You have built on your familiarity with defining records, views, processes, and rules
You learned about role-based permissions and setting up the access control model for your application
Powerful view-building techniques including:
Container-based multi-column layouts
Rich text
Record grids and editors, working with data from both records and their associations
Contextual action buttons
Invoking a synchronous process directly from a button in a view
Key process flow techniques, including:
How to build a record lifecycle
Sending messages to users
Conditional flow with exclusive gateways
Looping over sets of data
Implementing a time-out on a wait state
Modularizing your processes with Call Activity
Handling exceptions using Error End and Error Boundary
This may be a great time to "skip ahead" in the process to create an Install Package of your solution, purely as a backup.
This is more fully described in Module 3.
There's plenty more to learn about BMC Helix Innovation Suite. The next stop is to explore extending your application's
behavior using powerful Java and JavaScript techniques.
Module 2 - Extending your Solution in Code

Up to now, the only tool we have used to build the Lunch Tutorial solution has been BMC Helix Innovation Studio. As
powerful as that is, one of the great features of BMC Helix Innovation Suite is that developers who are handy with Java or
Javascript can fully use those tools to extend applications, and even create add-ons that can be used by others in BMC
Helix Innovation Studio without writing code themselves. In this set of lessons, we will create a Library, called meal-
program-lib, that will be used to deploy custom Java and Javascript for our solution. This is not intended to replace the
documentation found at Creating a custom service in Java (see page 823); rather, it illustrates some of these techniques
in the context of this tutorial.

Prerequisites
You may be wondering about whether this module is for you, or not. This is a fair question. Up to now, there have been
few assumptions about the technical skill or experience needed to complete the tutorial. However, since we are going to
be working with Java and JavaScript code here, and working with standard frameworks such as Jackson (for JSON
serialization) and AngularJS (for client-side JavaScript), that is not true any longer. The assumption here is that you are a
developer that knows, or is learning these skills, and is interested in learning how to apply them to augment BMC Helix
Innovation Suite applications.
The goal of this tutorial, after all, is not to teach you how to code (there are many great resources out there for that).
Rather, it is meant to help you, as someone who already has coding skills (from moderate to expert) get a heads-start in
how to use the BMC Helix Innovation Suite SDK in particular. For example, you will need to know about the standard
library we provide, the API documentation, deployment tools you will use, and so on. We will also see examples of
services written in Java that are designed to go hand-in-glove with the particular Lunch Tutorial solution we are building
so you can hopefully get some insights about how to make these two kinds of development work together.
Before starting this module, you will need to build a lunch ordering application as described in Module 1 of this tutorial. It
is highly recommended that you go through the exercise of building it yourself using BMC Helix Innovation Studio, at
least through the end of Module 1.
If you would like to skip this, or want to be sure you are starting with a complete version of the application, you also
install a pre-built version by using the following steps:
1. If you already have an application in your sandbox called com.example.lunchtutorial, you should uninstall it from
your workspace (of course, you can use Create Install Package first to keep a snapshot of it before you do this if
you like). This is to make sure that you don't have a mix of definitions, because installing an application does not
remove any previous definitions.
2. Download com.example.lunchtutorial-4.0.2-INSTALL.zip. this is the tutorial as of the point where all the codeless
development of the application is complete.
Important

To download the ZIP file, right-click the URL > Save link as. The ZIP file will get downloaded to the
default download location of your web browser. You must use the 7-Zip utility to extract the contents
of the ZIP file, and view the install package components. The contents of the install ZIP file cannot be
extracted by using the Windows Zip utility or Mac archive utility.
3. Use the Install button from the Workspace view to install this application.
Overview
Rather than lead you step-by-step in building the code, the approach here will be to start from a fully-functional set of
source code. We will build and deploy it together and you will integrate it into your application. Each area of functionality
will be highlighted and explained. If you are fairly new to these technologies, reviewing this material may be a little bit
mysterious, but the techniques involved are standard ones and you can learn a lot of useful concepts here that can be
applied to any Java or JavaScript development.
NOTE: since the provided sample code will refer to the specific definitions in Lunch Tutorial, running it requires having
completed the earlier modules of this tutorial.
The first set of lessons will be about creating Java-based services,exposed with their own REST-based interfaces,
and/or Service Actions that show up in the Process Designer.
The next set will be about working with JavaScript and AngularJS to extend the User Interface with custom View
Components and custom Actions, that will show up in the View Designer.
That being said, let's get started.
Setting up the Sample Meal Program Library Project

It is assumed that you have already completed Module 1, and now have a working code-less Application.
To augment it in code, there are two paths you could theoretically follow:
1. You could convert the Application you have already build from a code-less to a coded one, and then start adding
code. In the end you will have a single Application that has both definitions and code.
2. You could build and deploy a new Library project, then modify your Application to use it. Your code will always
remain in the Library, and most of your definitions will always remain in the Application.
For this tutorial, the sample source provided is based on option 2. What we will do is:
1. Get the Sample Source
2. Build It using Maven
3. Set up your Development Environment
4. Adjust the source to match your Application (we will make a quick check that the constants in it match your
definitions)
5. Rebuild and Deploy it using Maven
6.
6. Quick Sanity Check (that the code was successfully deployed into BMC Helix Innovation Suite)
Only then will we take an in-depth look at all the custom Java services,and Javascript components, that this project
contains.
Get the Util Library

If you have been following along with the tutorial, you have already installed this and you will see com.example.util-lib
package, listed in BMC Helix Innovation Studio simply as Util. If not, you can get it by following the directions described in
Creating a view to order from a dish (see page 145). You will need this because it is a dependency of com.example.meal-
program-lib.
Get the Sample Source

Get a hold of the source code in the attached project: sample-project-meal-program-lib.zip.
Important
Create some working folder, shown as \projects in this tutorial, that you will use for your projects. Unzip it so that you
now have the project source residing in \projects\meal-program-lib. At this point, it should look like this:
Build It
You will need to follow documented steps for Setting up your IDE and installing BMC Helix Innovation Suite SDK (see
page 800). In fact, it's a good idea if, by now, you have installed everything, set the RX_SDK_HOME environment variable,
created and deployed some small Application or Library, successfully used the Maven Archetype, modified the POM.xml
file to put your credentials in, and so forth. Consult the documentation to be sure your environment is configured
correctly.
Go ahead and build the source code (don't try to deploy it yet).
Build your Project
projects\meal-program-lib> mvn clean install

It should succeed if your environment is set up correctly. You should see the success messages like this - if not, there is
something amiss in your environment setup and you should refer again to Setting up your IDE and installing BMC Helix
Innovation Suite SDK (see page 800) and/or Deploying your Digital Service application for the first time to start working
in BMC Helix Innovation Studio (see page 813).
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] meal-program-lib-all .............................. SUCCESS [ 0.251 s]
[INFO] Meal Program Library .............................. SUCCESS [ 30.665 s]
[INFO] meal-program-lib-package .......................... SUCCESS [ 1.242 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 33.480 s
[INFO] Finished at: 2017-09-15T17:30:31-08:00
[INFO] Final Memory: 34M/323M
[INFO] ------------------------------------------------------------------------
Open the Project in an IDE

You can use any IDE you like, or a simple text editor. For example, to bring this Maven-based project into Eclipse, use the
"Import…" and "Existing Maven Projects" option to import the following POM file.
projects/meal-program-lib/bundle/pom.xml
The steps are very similar for other IDEs, such as IntelliJ IDEA.
If Enabled, Set up Remote Debugging

For cloud-based instances, debugging is not typically enabled by default, so this section will not apply. If you do have
remote debugging enabled, you can follow these instructions to connect from your instance of Eclipse (or use a similar
procedure for your particular debugger).
1. Right-click on the project node, and select Debug As > Debug Configurations
2. Create a new configuration for Remote Java Application. Set the debugging Host and Port of your instance
(these are not currently available for AWS-based sandboxes).
3. Click Debug to connect


Adjust the source to match your Application

In your IDE, open up the source file MealOrderConstants.java and take a look.
One thing about code-less development in BMC Helix Innovation Studio is that it is very easy to create Records (which
have names) and Fields (which have IDs), and other definitions with specific identifiers (like Associations). You don't have
to think about these all that much when working code-lessly. However, when using the API found in the BMC Helix
Innovation Suite SDK, you will find that it requires knowing the exact identifiers that you have created for your definitions
in BMC Helix Innovation Studio.

If you had actually installed a solution for the com.example.lunchtutorial, the constants may already match with your
definitions perfectly. If you built your own application according to the tutorial steps, it's possible that some of the names
and id definitions may not match exactly and you will need to adjust the sample source code for meal-program-lib.
The identifiers that appear in in the sample source code for Meal Program Library do not match your definitions, even if
you have followed the steps in the tutorial exactly. What you have to make sure are matching are:
Identifier Type Example(s) Constant in Source Example Value that may require correction in Source
Bundle ID LUNCH_TUTORIAL_BUNDLE_ID com.example.lunchtutorial
Record Definition MEAL_ORDER_RECORD_DEF_NAME LUNCH_TUTORIAL_BUNDLE_ID + ":" + "Order"

Name
Field ID MEAL_ORDER_DELIVERED_FIELD_ID_STRING "10029002"
Field ID MEAL_ORDER_REQUESTED_DATE_FIELD_ID 10029004
Field ID MEAL_DISH_PRICE_FIELD_ID_STRING "10029005"
Field ID MEAL_RESTAURANT_DELIVERYCHARGE_FIELD_ID_STRING "10029005"
Selection Field Value MEAL_ORDER_STATUS_CANCELLED "30"
Assocation Name MEAL_ORDER_DISH_CAN_BE_ORDERED_ASSOCIATION LUNCH_TUTORIAL_BUNDLE_ID + ":" + "Dish can be Ordered"
Assocation Name MEAL_ORDER_RESTAURANT_FULFILLS_ORDERS_ASSOCIATION LUNCH_TUTORIAL_BUNDLE_ID + ":" + "Restaurant Fulfills

Orders"
Assocation Name MEAL_ORDER_RESTAURANT_PROVIDES_DISHES_ASSOCIATION LUNCH_TUTORIAL_BUNDLE_ID + ":" + "Restaurant Provides

Dishes"
For example, when reviewing the Delivered Field ID constant in the source, you might see this:
MealOrderConstants.java Excerpt
public static final String MEAL_ORDER_DELIVERED_FIELD_ID_STRING = "10029002";
you would open up that Field in the Record Designer and check it to make sure it matches.
If it does not, since it is not easy to modify the Field ID in BMC Helix Innovation Studio, update MealOrderConstants.java
so that the code refers to the correct Field ID values.
MealOrderConstants.java

Here are all the constants that need to be checked and possibly corrected:
Rebuild and Deploy your Project
package com.example.meal.business.impl;
public class MealOrderConstants {
/**
* CONSTANTS YOU ARE LIKELY TO HAVE TO CHECK AGAINST YOUR
* APPLICATION IN INNOVATION STUDIO
*/
// Change this to reflect the actual bundle id of your code-less app.

public static final String LUNCH_TUTORIAL_BUNDLE_ID = "com.example.lunchtutorial";
// Order
public static final String MEAL_ORDER_RECORD_DEF_NAME = LUNCH_TUTORIAL_BUNDLE_ID + ":" + "Order";
public static final Integer MEAL_ORDER_STATUS_FIELD_ID = 7;
public static final String MEAL_ORDER_STATUS_FIELD_ID_STRING = "7";
public static final Integer MEAL_ORDER_REQUESTED_DATE_FIELD_ID = 10029004;
// Selection values for Status of Order

public static final String MEAL_ORDER_STATUS_SUBMITTED = "0";
public static final String MEAL_ORDER_STATUS_INPROGRESS = "10";
public static final String MEAL_ORDER_STATUS_DELIVERED = "20";
public static final String MEAL_ORDER_STATUS_CANCELLED = "30";
public static final String MEAL_ORDER_STATUS_CLOSED = "40";
public static final String MEAL_ORDER_STATUS_FIELD_NAME = "Status";
// Dish
public static final String MEAL_ORDER_DISH_RECORD_DEF_NAME = LUNCH_TUTORIAL_BUNDLE_ID + ":" + "Dish";
public static final String MEAL_ORDER_DISH_CAN_BE_ORDERED_ASSOCIATION = LUNCH_TUTORIAL_BUNDLE_ID + ":" + "
Dish can be Ordered";
public static final String MEAL_DISH_RECORD_DEF_NAME = LUNCH_TUTORIAL_BUNDLE_ID + ":" + "Dish";
public static final String MEAL_DISH_NAME_FIELD_ID_STRING = "8";
public static final String MEAL_DISH_PRICE_FIELD_ID_STRING = "10029005";
// Restaurant
public static final String MEAL_ORDER_RESTAURANT_FULFILLS_ORDERS_ASSOCIATION = LUNCH_TUTORIAL_BUNDLE_ID +
":" + "Restaurant Fulfills Orders";
public static final String MEAL_ORDER_RESTAURANT_PROVIDES_DISHES_ASSOCIATION = LUNCH_TUTORIAL_BUNDLE_ID +
":" + "Restaurant Provides Dishes";
public static final String MEAL_RESTAURANT_NAME_FIELD_ID_STRING = "8";
public static final String MEAL_RESTAURANT_DELIVERYCHARGE_FIELD_ID_STRING = "10029005";
. . .
Rebuild and Deploy it using Maven

In order to actually deploy it to your server, make sure you have updated the POM file credentials as described here (if
you have already successfully deployed another project using Maven, you can "steal" the credentials part from that POM
file and copy them in here).
Innovation Suite Credentials in POM.XML - Snippet
<properties>

<developerUserName>DEVELOPER_USER</developerUserName>

<developerPassword>DEVELOPER_PASSWORD</developerPassword>

<webUrl>DEVELOPMENT_URL</webUrl>

Once credentials are in place, you can go ahead and deploy it.
Rebuild and Deploy your Project
projects\meal-program-lib> mvn clean install -Pdeploy
This time with your success messages you should see that it was deployed as well as built.
Quick Sanity Check

At this point, the additional Service Actions and View Components are now available in BMC Helix Innovation Studio.
You will have to refresh the browser (a hard refresh, such as Shift-Refresh on Chrome, is recommended - to make sure
the code is present and ready to use). To verify that it is there,
1. On the Workspace page, you should now see the Meal Program Library appearing. Don't be concerned if you
don't see a lot of definitions inside it - after all, it is mostly code that you will not see in the Workspace.
2. Open up the Process Designer within your Lunch Tutorial Application (for any Process or create a new one). The
palette should contain a new section with custom Service Actions for the Meal Order:

3. The View Designer, similarly, will have new View Components in the Palette.
What you Learned

We have set the stage for diving into a lot of really useful coding examples and techniques. We can now examine the
code, and immediately test it out. First we will look a lot more deeply at the design of the Java services in the sample
project and the code that implements it.
Building custom Service Extensions in Java for the Meal Program Library
We will start by looking at the Java side of the picture. As an overview, here are some of the topics you will learn:
Understanding the design of a custom Meal Order Service
Using built-in platform services such as Record, Association, Setting
Understanding Exception Handling
Exposing custom Service Actions for Process Designer
Exposing your own REST-based interfaces for Lunch Tutorial
With Java code, it's possible to create many different ways of the outside world accessing your service. The following
diagram shows four important interface styles that are all represented in the Meal Program Library project.

As you can see, all of these are based on the concept of a Service that you implement that has registered Java interfaces.
The Service can accessed from outside in any or all of four ways:
Interface How to Create It How it is Used Tutorial

Method Example
Service Annotate the It appears as what is called a Service Action in Process Designer and can be used just like any built-in Get Meal
Action implementation with the Activity. Order
@Action keyword, and
register it with your
MyLibrary class
Data Page Extend the DataPageQuery Any HTTP client can perform a GET on the special DataPageQuery resource, and provide the Meal
Query class in the Standard custom DataPageQuery class and required parameters. This returns a standard JSON structure with Order
Library, and register it with an array of any kind of data. Data Page
your MyLibrary class. Query
Custom Extend the RestfulResource Any HTTP client can perform any operations such as GET, PUT, POST, DELETE you implement on Meal
Resource class in the Standard your resource. These are normally not needed for typical data operations on Records (sometimes Order
Library, and register it with called CRUD operations), because the Record Service already exposes resource such as Resource
your MyLibrary class. RecordInstanceResource for that kind of interaction.
Custom Extend the Command class Any HTTP client can perform a POST to the special Command resource, and provide the custom Cancel
Command in the Standard Library, and Command class and required parameters. This is intended to perform some kind of action that has Meal
register it with your side-effects on the system and would not follow standard resource-oriented semantics (GET, PUT, Order
MyLibrary class. POST, DELETE). Command
Take a look at the package structure to see how the code is laid out. Each package and Java class has a purpose as
described below (remember you can click on the diagram to see it full-size).

Organizing it this way is a best practice, and this sample code follows the same package structure as the standard library
in the SDK itself and is highly recommended. Note that when you create your own project, using a Maven archetype, the
class that is generated for you is the Bundle class (in this case, MyLibrary.java). The rest of the structure is up to you to
create.
We will go over the interesting aspects of this code, which should give you a good starting point for creating your own
services.
The Bundle class

Every project has a class that is generated by the archetype that extends com.bmc.arsys.services.common.RxBundle. As
generated by the archetype, this class simply activates your code bundle at deployment time, which by default has no
custom code in it. It also registers the URL for static resources that are part of your application.
The archetype generates it in the bundle sub-package of the "package" name you provided with the archetype.
The following code snippet is DUMMY code to generally explain the bundle class and how various extension objects are
registered. Don't worry about what these extension objects are just yet, but as you go through the tutorial, note what the
sample code puts here. For your own extensions, you would have to return to this class whenever you want to activate
any of these services.
NOTE: as you will quickly learn when coding your own services, forgetting to register your implementations here is the
first thing to check when your code does not seem to be invoked at run-time!
A Bundle Class - Pseudo-code
package com.companyname.mypackage.bundle;
import com.bmc.arsys.rx.services.common.RxBundle;
// Easy to update this in Eclipse with Control-Shift-O

import com.companyname.mypackage.application.SomeResource;
import com.companyname.mypackage.application.command.SomeCommand;
import com.companyname.mypackage.application.datapage.SomeDataPageQuery;

import com.companyname.mypackage.business.impl.SomeServiceImpl;
/**
* Rx Web Activator class.
*/
public class MyLibrary extends RxBundle {
/* (non-Javadoc)
* @see com.bmc.arsys.rx.business.common.RxBundle#register()
*/
@Override
protected void register() {
// Register Commands
registerClass(SomeCommand.class);
// Register Data Page Queries

registerClass(SomeDataPageQuery.class);
// Register Services
registerService(new SomeServiceImpl());
// Register Resources
registerRestfulResource(new SomeResource());
// Register any web application resources

registerStaticWebResource(String.format("/%s", getId()), "/webapp");
}
}
Note that is also possible to place custom code in a project created as an non-code-less Application (not a Library)
bundle. The only difference is that the name of the class generated by the archetype is MyApplication.java instead of
MyLibrary.java.
The best way to quickly see which resources and services are in the meal-program-lib bundle, just examine the bundle
class where you will find:
MyLibrary.java - snippet
. . .
// Register Commands
registerClass(CancelMealOrderCommand.class);

registerClass(MealOrderDataPageQuery.class);
registerService(new MealOrderServiceImpl());
registerRestfulResource(new MealOrderResource());
registerRestfulResource(new MealOrderCSVResource());
. . .
Implementing the MealOrderService

We have seen that regardless of how services are exposed to clients, there is an underlying registered service
implementation that is available to all of these. Let's use our IDE to begin looking just at the MealOrderService interface
itself in the com.example.meal.business Java package.

Its has several interesting things to note:
1. It declares a MealOrderService interface. Note that it does not directly extend the framework's com.bmc.arsys.rx.
services.common.Service interface, but its implementation must. This is important so other code can use BMC
Helix Innovation Suite's ServiceLocator singleton to obtain a handle to an instance of this Service at run-time; it is
also required in order to expose methods as Service Actions, as we shall see shortly.
MealOrderService.java - Snippet
public interface MealOrderService {
/**
* Create a new MealOrder with a single consumer, based on the exact name of an existing dish.
* @param dish - exact name of a dish
* @param consumer - login id of an existing Employee
* @param requestedDate - date representation in ISO-8601 format "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"
* @return MealOrder
*/
public MealOrder createSingleConsumerOrder(
@NotBlank String dish,
@NotBlank String consumer,
@NotBlank String requestedDate);
. . .
/**
* This action cancels an open order.
* @param mealOrderId
* @return true if cancelled successfully
*/
public abstract boolean cancelMealOrder(@NotBlank String mealOrderId);
. . .
2. The GetMealOrder() method returns our domain object called MealOrder. We will take a closer look at its
implementation later on; for now, assume it is a kind of "plain old Java object" (or POJO) that can be serialized
for outside consumption.
3. Looking at the implementation class MealOrderServiceImpl, found in the com.example.meal.business.impl

package, the methods are often wrappers to functionality that is in other classes. For example, the BMC Helix
Innovation Suite SDK standard library RecordService is used to manipulate a record to implement
cancelMealOrder(). The RecordInstance is fetched and then updated. Simplifying the code somewhat:
MealOrderServiceImpl Pseudocode
RecordService recordService = ServiceLocator.getRecordService();
// Retrieve the instance object from persistence.

RecordInstance mealOrderRecordInstance =
recordService.getRecordInstance(
MealOrderConstants.MEAL_ORDER_RECORD_DEF_NAME,
mealOrderId);
// Set the Status field value in memory.

mealOrderRecordInstance.setFieldValue(
MealOrderConstants.MEAL_ORDER_STATUS_FIELD_ID,
MealOrderConstants.MEAL_ORDER_STATUS_CANCELLED);

// Persist the updated record instance.

recordService.updateRecordInstance(mealOrderRecordInstance);
You can see why the constants in MealOrderConstants have to refer to the correct ids and/or names of
definitions in the Lunch Tutorial application in order to function correctly here.
4. Note again that this implementation is registered automatically by the code called at Bundle start up time, in
MyLibrary.java:
MyLibrary.java Snippet
registerService(new MealOrderServiceImpl());
Challenge
Create a new Service Interface and Implementation within this Library called RestaurantService and
RestaurantServiceImpl. Follow the best practices on package structure.
Define at least one method - you can give it a very simple dummy method such as callKitchen() for now.
Rebuild your Library using
projects\meal-program-lib> mvn clean install
Don't worry about making it completely functional right now or even accessible from clients - we will have a
chance to do this later as we go deeper into the Meal Program Library pre-built code.
What you Learned
Services should have both and interface, implementation, and domain objects that are kept in separate Java
packages, as a best practice.
Framework services such as the RecordService and AssociationService are available to manipulate Records in
your implementation.
Service implementations need to be registered in the Bundle class (MyLibrary.java).
Using Records and Associations to load a domain object

We have glossed a bit over the getMealOrder() service interface, especially about how it is implemented.
First of all, if you want to see exactly what a MealOrder is, you would look at the members of the domain object in the
com.example.meal-order-lib.business.domain package.
MealOrder.java Snippet
public class MealOrder {
public String id;

public String cost;
public String price;
public String deliveryCharge;
public String tax;
public String restaurant;

public String dish;

public String delivered;
public ArrayList<Consumer>;
. . .
Consider where the information about Restaurant, Dish, and Consumer are coming from - they are not present in the
Order record proper. This is why callers cannot easily use the Record Service themselves to obtain this information.
What the MealOrderService does for you is combine the related information into this single object, our domain object,
MealOrder.
The implementation of the helper method buildMealOrder() shows the various parts of the object that are built by
loading up information from the Record and Association Services.
MealOrderServiceImpl.java - Snippet
. . .
public MealOrder buildMealOrder(String mealOrderId) {
// Instantiate the info object.

MealOrder mealOrder = new MealOrder(mealOrderId);
// Look up the data from the base record and its associations.
// Look up the fields from Order itself.

updateOrderInfo(mealOrder);
// Use the currency format set by administrators.

String currencyFormat = MealOrderSettings.getCurrencyFormat();
// Lookup associated Dish information.

updateDishInfo(mealOrder, currencyFormat);
// Lookup associated Restaurant information.

updateRestaurantInfo(mealOrder, currencyFormat);
// Calculated information.
updateCost(mealOrder, currencyFormat);
// Get the list of employee consumers. This has to happen after the price and delivery charge info
// is loaded.
updateConsumers(mealOrder);
return mealOrder;
}
. . .
Let's take a look at the updateOrderInfo() method, as this is just a straightforward getting of information from the Order
record itself.
MealOrderServiceImpl Snippet
private void updateOrderInfo(MealOrder mealOrder) {

RecordInstance mealOrderRecordInstance;
try {
mealOrderRecordInstance = recordService.getRecordInstance(
MealOrderConstants.MEAL_ORDER_RECORD_DEF_NAME, mealOrder.getId());
}

catch (RxException e) {
ServiceLocator.getLogger().error("No such Order " + mealOrder.getId());
throw new MealOrderException(MealOrderException.MealOrderMessage.MEAL_ORDER_NOT_FOUND, mealOrder.
getId(), e);
}
String delivered = mealOrderRecordInstance.getFieldValue(
Integer.parseInt(MealOrderConstants.MEAL_ORDER_DELIVERED_FIELD_ID_STRING));
mealOrder.setDelivered(delivered);
}
The Restaurant and Dish information have to be retrieved using the Association Service. Let's look at updateDishInfo(),
The idea here is that the price information about the Order is not actually stored in the Order - it lives in the Dish as a
double integer. We would like to return it as a formatted currency value. Note the use of the utility method
getAssociatedRecord() that we will examine next.
MealOrderInfo.java Psuedo-code
private void updateDishInfo(MealOrder mealOrder, String currencyFormat) {
// Examine the Dish associated to this order.

Map<String, Object> mappedRecord;
try {
mappedRecord = getAssociatedRecord(
MealOrderConstants.MEAL_ORDER_DISH_CAN_BE_ORDERED_ASSOCIATION, mealOrder.getId(), true);
}
ServiceLocator.getLogger().error("Problem getting dish information for Order " + mealOrder.getId());
throw new MealOrderException(MealOrderException.MealOrderMessage.MEAL_ORDER_CANT_READ_ASSOCIATION,
mealOrder.getId(), e);
}
DecimalFormat money = new DecimalFormat(currencyFormat);
if (mappedRecord == null) {
ServiceLocator.getLogger().error("No Dish associated to: " + mealOrder.getId());
mealOrder.setPrice(money.format(new BigDecimal(0.0)));
return;
}
// Format the price information.
double priceComputation = ((BigDecimal)
mappedRecord.get(MealOrderConstants.MEAL_DISH_PRICE_FIELD_ID_STRING)).doubleValue();
mealOrder.setPriceComputation(priceComputation);
mealOrder.setPrice(money.format(priceComputation));
mealOrder.setDish((String)mappedRecord.get(MealOrderConstants.MEAL_DISH_NAME_FIELD_ID_STRING));
}
Because we need to fetch an associated record in several cases, it behooves us to share this code and make it a little
more abstract. This helper method will find any single associated record, based on an association name, associated
record id, and the "direction" of the association (which side we need to fetch). This method itself is simply a wrapper to
the actual code that gets all associated records.
MealOrderInfo.java - Snippet
/**
* Utility method to fetch one associated record. Particularly useful for the "1" in a "1:1" or "1:Many"
association.
* @param associationName
* @param startingRecordId
* @param isFirstRecord
* @return
*/
@SuppressWarnings("unchecked")

private Map<String, Object> getAssociatedRecord(

String associationName,
String startingRecordId,
boolean isFirstRecord) {
DataPage result = getAssociatedRecords(associationName, startingRecordId, isFirstRecord, 1);

if (result == null || result.getData() == null || result.getData().size() != 1) {
return null;
}
return (HashMap<String, Object>)result.getData().get(0);
}
/**
* Utility method just to make the code look cleaner. Does a query for associated records.
* @param associationName
* @param startingRecordId
* @param isFirstRecord
* @param maxRecords
* @return
*/
private DataPage getAssociatedRecords(
String associationName,
String startingRecordId,
boolean isFirstRecord,
int maxRecords) {
AssociationService associationService = ServiceLocator.getAssociationService();
Map<String, QueryPredicate> queryPredicatesByName = new HashMap<String, QueryPredicate>();

queryPredicatesByName.put("associationDefinition", new QueryPredicate("associationDefinition",
associationName));
queryPredicatesByName.put("nodeToQuery", new QueryPredicate("nodeToQuery", (isFirstRecord) ? "nodeA" : "no
deB"));
queryPredicatesByName.put("associatedRecordInstanceId", new QueryPredicate("associatedRecordInstanceId",
startingRecordId));
DataPageQueryParameters params = new DataPageQueryParameters(maxRecords, 0, null, null,

queryPredicatesByName);
return associationService.getAssociationInstancesByIdDataPage(params);
}
Note that the DataPage is simply a container for a HashMap of name/value pairs.
The other interesting thing that this domain object is doing is a bit of calcuation of derived fields, such as cost. Once we
have all the other data that this calculation depends on, it is easy to implement it. In this case, the tax rate comes from
settings (we will touch on this in later part of this module).
MealOrderServiceImpl.java Psuedo-code
/**
* Update calculated information about the cost.
* @param currencyFormat
*/
private void updateCost(MealOrder mealOrder, String currencyFormat) {
Double taxComputation = mealOrder.getPriceComputation() * MealOrderSettings.getTaxRate();
Double costComputation = mealOrder.getPriceComputation() + taxComputation + mealOrder.
getDeliveryChargeComputation();
mealOrder.setTax(money.format(taxComputation));
mealOrder.setCost(money.format(costComputation));
}

It is very easy to return a list of information as well, as long as it is represented by a collection of serializable objects.
Employees here are represented by a simple public class called Consumer, that contains exactly the information that
should be serialized and returned, and nothing more. Note that there is a full domain object for Employee in the
Foundation library, but that is more than we need here.
Consumer.java
package com.example.meal.business.domain;
public class Consumer {

public Consumer(String fullName, String primaryPhone) {
super();
this.fullName = fullName;
this.primaryPhone = primaryPhone;
}
private String fullName;

private String primaryPhone;
public Consumer() {
}
public String getFullName() {

return fullName;
}
public void setFullName(String fullName) {

this.fullName = fullName;
}
public String getPrimaryPhone() {

return primaryPhone;
}
public void setPrimaryPhone(String primaryPhone) {

this.primaryPhone = primaryPhone;
}
}
Challenge
For the custom RestaurantService you created in the previous challenge, create a method that returns the
Restaurant (Name) as well as a list of Dishes (Name and Price) that it offers.
What Have you Learned
Creating your own service gives you the opportunity to easily manipulate data, including aggregating it, or
performing additional calculations, with all the power of an industry-standard programming environment.
Using a dependent service and custom settings

Sometimes, you need your code to use data that is not coming from end-users, but are more like global settings
specified by application administrators. That is what the Settings Service is for.
Rather than walk step-by-step to define a Setting and then use it, here we will start from how it is used and work
backwards to its definition in BMC Helix Innovation Studio. Of course, when creating your own Settings you will do it the
other way around; that is, start by defining it in BMC Helix Innovation Studio.

For our Meal Program Library, remember that there is a cost calculation for each Order that includes a tax rate that is
applied to all Orders. It would not be a good idea to bake in this into the code as a constant value, because that would
require recompilation and re-deployment whenever the tax rate changes; furthermore, in a multi-tenant deployment, the
tenant administrator would have no way to configure the rate differently for his or her tenancy.
Take a look again at the cost computation:
MealOrderInfo.java - Snippet
/**
* Update calculated information about the cost.
* @param currencyFormat
*/
private void updateCost(MealOrder mealOrder, String currencyFormat) {
Double taxComputation = mealOrder.getPriceComputation() * MealOrderSettings.getTaxRate();
Double costComputation = mealOrder.getPriceComputation() + taxComputation + mealOrder.
getDeliveryChargeComputation();
mealOrder.setTax(money.format(taxComputation));
mealOrder.setCost(money.format(costComputation));
}
All of this data comes from records except the tax rate. The MealOrderSettings class handles looking up settings like this
that are defined for the Library. The following pseudo-code shows the constants from MealOrderConstants in-line to
make it easier to relate to BMC Helix Innovation Studio, which we will do momentarily.
MealOrderSettings.java - Pseudo-code
// Exception handling code not shown to simplify for understanding - not meant
// as sample code...
public static float getTaxRate() {

String rateString = getUtilSettingsService().settingTextValue(
"com.example.meal-program-lib,
"MealOrders",
"TaxRate" );
if (rateString == null) {
return 0.02f;
}
return new Float(rateString);
}
The code to retrieve a setting from the SettingsService is shown here. Note that this same functionality is also available
in the util-lib bundle as a service of its own.
MealOrderSettings.java - Snippet
/**
* Utility method to get some shared setting.
* @param setting
* @return
*/
private static String getSettingTextValue(String bundle, String component, String setting) {
AdminHeader adminHeader = new AdminHeader();

adminHeader.setBundleScope(bundle);
adminHeader.setGlobalSpace(false);
AdminSettingDataContainer dataHolder = null;
try {
dataHolder = ServiceLocator.getAdminSettingsService().

getAdminSettingData(component, adminHeader);
}
catch (Exception e) {
ServiceLocator.getLogger().error("Could not access " + component + " component");
}
Map<String, AdminSettingData> dataMap = null;
try {
dataMap = dataHolder.getAdminSettingDataMap();
}
catch (Exception e) {}
if (dataMap == null) {
ServiceLocator.getLogger().error("no dataMap found for " + component + " component");
return null;
}
AdminSettingData data = null;

try {
data = dataMap.get(setting);
}
catch (Exception e) {}
if (data == null) {
ServiceLocator.getLogger().error("could not get data for '" + component + "/" + setting + "'");
return null;
}
ServiceLocator.getLogger().info(data.getSettingId() + "," + data.getSettingName() + ", " + data.
getSettingValue());
return data.getSettingValue();
}
Here is where the code will not work without defining the TaxRate Setting, within the MealOrders Component, within the
com.example.meal-program-lib Library. Defining this is quite similar to defining a Field in a Record, but it has a specialized
editor for this in BMC Helix Innovation Studio. This particular Setting is already defined when you deployed the Meal
Order Library, which you can find by going to the Configurations tab for the Meal Program Library.

Note: the MealOrders Component is known as a container of Shared Settings. It specifies that it will show up in the
Navigation Sidebar of both the Application Shell and BMC Helix Innovation Suite's Administration Tab.
Using the Administration tab in BMC Helix Innovation Studio, we can specify these Setting values in order to test it.
For more information about creating Settings, see Creating configurations for your Digital Service application (see page
505).

Challenge
Add a new Field to the MealOrders Settings Component. Use it in the code of Meal Program Library. Remember
that you will need to -Pexport as well as -Pdeploy in order for your project to capture the definitions, and to
deploy the code for testing.
Command Line
projects\meal-program-lib> mvn clean install -Pexport -Pdeploy
In your lunch catering Application, create a custom View that appears in the Settings area as In-Bundle Settings.
The Settings Service is a great way to keep adminstrative configuration managed in a central repository, and
make it available to your code to consume as well as administrators to set, without requiring a special UI or data
model be constructed for it.
/** * Utility method to get some shared setting. * @param setting * @return */ private static String getSettingTextValue
(String bundle, String component, String setting) { AdminHeader adminHeader = new AdminHeader(); adminHeader.
setBundleScope(bundle); adminHeader.setGlobalSpace(false); AdminSettingDataContainer dataHolder = null; try {
dataHolder = ServiceLocator.getAdminSettingsService(). getAdminSettingData(component, adminHeader); } catch
(Exception e) { ServiceLocator.getLogger().error("Could not access " + component + " component"); } Map<String,
AdminSettingData> dataMap = null; try { dataMap = dataHolder.getAdminSettingDataMap(); } catch (Exception e) {} if
(dataMap == null) { ServiceLocator.getLogger().error("no dataMap found for " + component + " component"); return null;
} AdminSettingData data = null; try { data = dataMap.get(setting); } catch (Exception e) {} if (data == null) { ServiceLocator.
getLogger().error("could not get data for '" + component + "/" + setting + "'"); return null; } ServiceLocator.getLogger().
info(data.getSettingId() + "," + data.getSettingName() + ", " + data.getSettingValue()); return data.getSettingValue(); }
A custom Service Action interface for the MealOrderService

The first way of exposing the MealOrderService to clients is by exposing it directly in Process Designer. This is done by
binding the Process Service to our implementation by means of certain annotations that we will show below.

Recall that during the sanity check after initially deploying our Library, we saw that there were new items showing up in
the Palette under the MEAL ORDER section.
Furthermore, if we drag one of these into the Process Designer canvas and look at the Property Inspector, we see that
the parameters are ready to be bound to some expression:

For this particular Service Action, the Output structure shown in the Expression Editor Dialog gives access to the fields
of our returned Java object, an instance of MealOrder.
This is pretty powerful. Now we can look specifically at the "magic" that made this happen.
1. As we already mentioned, the MealOrderServiceImpl was registered in the Bundle class.
2. The getMealOrder() method is annotated. The @Action annotation means that its signature will be automatically
published to Process Designer. The (scope=Scope.PUBLIC) argument allows it to be used outside of the meal-
order-lib process definitions (without this, your code-less Application would not be able to see it in the palette).
MealOrderServiceImpl.java Snippet
@Action(scope = Scope.PUBLIC)
public MealOrder getMealOrder(
@ActionParameter(name = "mealOrderId") @NotBlank String mealOrderId) {
. . .
3. As we saw above, the return value of the method is automatically made available, without any code, or even
annotation needed. This works even if the return value is a scalar, or POJO object, even if some of the members
are also POJOs. In other words, the class has to be serializable.

Challenge
Modify the Order Lifecycle Process in the Application you created earlier, so that
when it sends a notification when an Order becomes Delivered, it includes the final cost of the Order.
Hint: the Get Order Info Service Action computes that information for you.
If it is in a state of In Progress longer than some period of time (say 1 minute to make it easier to test), it
will invoke the Cancel Meal Order Service Action. Be careful about your logic when you break out of the
User Task however - where will your process flow to? If it terminates, the cancellation handling you
already implemented may not be called. Consider flowing back to the User Task so that the existing logic
can take over.
Annotate a method from your RestaurantService interface (from the previous challenge) to make it a Service
Action. Don't worry about the implementation beyond doing something so you will know it was actually invoked
by your process (either through return value, or by side-effect on a Restaurant record).
Click here for a reminder about how to deploy your updated service...
Remember that simply building your deployment package is not enough to make it available to BMC Helix
Innovation Studio or to an Application at run-time. As we did earlier, you need to use the -Pdeploy option on the
Maven command line and have the correct configuration in your project's pom.xml file.
It's very easy to build custom Java services that are accessible by code-less developers (in BMC Helix Innovation
Suite) or in code.
The way Service methods become Service Actions that can be consumed in a Process is by annotating them with
@Action and @ActionParameter.
Scope is important if you are deploying Service Actions in a Library and they need to be consumed in some other
Application or Library.
For more information, see Creating your own service in Java (see page 823).
A custom DataPageQuery for the MealOrderService

We have a useful Service now that can get information about an individual Order - but only from a Process created in
Process Designer, and only if you already know the Order ID.
What if we want to go beyond this, and provide access to this information form any HTTP client? For example, what if we
have extended the Application by writing custom Javascript components that need to get certain information using
HTTP? This is where we begin to implement our own REST access to our Service.
A custom DataPageQuery is the first of the three ways of exposing our Service using REST and HTTP. The
DataPageQuery itself is both a documented design pattern, and an easy-to-extend built-in REST Resource that is
provided by the framework, as the following diagram indicates:

The idea here is that you provide your own class that extends the framework's DataPageQuery. Callers can then provide
both standard parameters (like Page Size, Starting Index) and others that are specific to the data you are returning. The
return format of the data can be any array of JSON objects that the caller expects.
First, the constructor needs to pass up the standard DataPageQueryParameters object.
MealOrderDataPageQuery.java - Snippet
public MealOrderDataPageQuery(DataPageQueryParameters mealOrderDataPageQueryParameters) {

super(mealOrderDataPageQueryParameters);
}
The actual work is all done in the execute() method, which the framework calls back when it needs to process a GET on
the standard resource.
In this case, in order to use our MealOrderService, we need a list of Order IDs that match certain predicates (such as, "all
the Orders that are In Progress"). We will obtain these from the RecordService by calling its built in query, known as a
RecordInstanceDataPageQuery. In other words, our query is a kind of wrapper on the RecordService, but will load up
additional information for each Order.
This is a pretty complex method to take in, so it may help to consider it as pseudo-code first (the actual code has a lot of
error checking, logging, type-casting, etc).
MealOrderDataPageQuery.java - Pseudo-code
@declare it as part of a record service transaction

execute() {
// Build the predicates (like Status = X) from parameters.

Map queryPredicates = ...
// Wrap the predicates into what the RecordService expects.

DataPageQueryParameters params = ...

// Perform the query.

List records = recordService.getRecordInstancesByIdDataPage(params).getData();
// Define the list to be returned.

List resultList = new LinkedList<MealOrder>();
// We now have a list of Order record ids. We can create a list of objects, with more detail
// built for each for each one.
for (Object record : records) {
// Pull out the meal order id.

String mealOrderId = record.get(ID_FIELD);
// Call the MealOrderService to do get the extended domain object.

MealOrder mealOrder =
MealOrderServiceImpl.getMealOrderService().buildMealOrder(mealOrderId);
// Add it to our result.

resultList.add(mealOrder);
}
// Return the data, allowing Jackson to serialize it for us.

return new DataPage(resultList.size(), resultList);
}
As usual, the Resource class has to be registered in your Bundle class, or it will not be found at run-time:
MyLibrary.java - Snippet

registerClass(MealOrderDataPageQuery.class);
In order to run this code, you will need some environment that allows you to easily perform HTTP operations. You may
have your favorite tool for this. This tutorial will show examples using one called Postman.
When interacting with Innovation Suite using HTTP APIs, it is always necessary to establish a session by using a POST to
/api/rx/application/command with a body that includes credentials and the resourceType set to com.bmc.arsys.rx.
application.user.command.LoginCommand. Note the Environment variables set up here for url, username, and password
(this is a nice feature that allows you to save your commands and easily use them in multiple environments). If you are
successful you will see a token returned that looks something like the text shown on the bottom:

Let's try out the MealOrderDataPageQuery.
To do this, perform a GET on the resource api/rx/application/datapage. Provide three parameters:
dataPageType (required) - this must be com.example.meal.application.datapage.MealOrderDataPageQuery.
pageSize (required) - whatever you like
startIndex (required) - whatever you like
status (optional) - the numeric value of the Status field to use as a constraint. For example, 10 for In Progress.

Note that the JSON result includes all the data members, including the list for consumers.
Challenge
Add another data member to MealOrder and make sure it is populated and returned by the
MealOrderDataPageQuery.
Add another kind of predicate, like status, to filter the results. For example, you could filter on the Special
Instructions field.
Implement your own DataPageQuery implementation for your RestaurantService from previous challenges.
A custom DataPageQuery implemetation is simply a class that extends the framework's DataPageQuery class, and
has an execute() method that returns a HashMap wrapped in an object called DataPage.
If you are building up the DataPage from scratch, it is up to you to implement the logic for startIndex and pageSize
; if you are wrapping another DataPageQuery (such as RecordInstanceDataPageQuery), you can pass it through
and it will be honored.
You collection of responses are automatically serialized into JSON.
For more information, see Creating a DataPageQuery REST interface (see page 873).
A custom RestfulResource for the MealOrderService

There are times when we may want to expose our own complete REST Resource for integration or other purposes - this
gives a huge flexibility, and also allows us to implement any of the HTTP semantics we like (including GET, POST, PUT, or
DELETE). This will also be very easy to do on top of the MealOrderService we have already built.

Looking at the Code

In the pre-built code for the Meal Program Library, there is a simple example of exposing the MealOrderInfo Resource via
GET. The code is in the MealOrderInfoResource class. If you are familiar with the use of Apache Jackson to serialize and
de-serialize JSON then this code will be really easy to work with for you.
Note that the class is annotated with @Path that describes the URL prefix.
MealOrderInfoResource.java - Snippet
@Path("example/mealorder")
The class has to implement the com.bmc.arsys.rx.services.common.RestfulResource interface.
MealOrderInfoResource.java - Snippet
public class MealOrderInfoResource implements RestfulResource {

. . .
}
The method implementing GET is properly annotated. Again, note the @RxDefinitionTransactional annotation needed to
perform RecordService operations during execution. The continuation of the @Path to this particular method also
defines an input URL parameter expected, mapped into mealOrderId.
MealOrderInfoResource.java - Pseudo-code
@GET
@Path("/{id}")
@RxDefinitionTransactional(readOnly = true)
@AccessControlledMethod(authorization = AuthorizationLevel.ValidUser)
public String get(@PathParam("id") String mealOrderId) {
. . .
return mealOrderInfo;
}
Now we can simply find and invoke the MealOrderService method to construct the MealOrder object.
MealOrderResource.java - Snippet
MealOrder mealOrder =
MealOrderServiceImpl.getMealOrderService().getMealOrder(mealOrderId);
One more step is needed: to serialize the MealOrder object to JSON, using Jackson's API.
MealOrderResource.java - Pseudo-code
return new ObjectMapper().writeValueAsString(mealOrder);
As usual, the Resource has to be registered in your Bundle class, or it will not be found at run-time:
MyLibrary.java - Snippet
registerRestfulResource(new MealOrderResource());

Testing this using Postman is very similar to what we have seen before. To try out GET, you will need to know a valid
Order ID (you can use the Edit Data feature of BMC Helix Innovation Studio to find one).
Make sure you have performed the login command recently and therefore have a valid session token.
Let's take a look at POST.
There are several important things to note here:
Annotations that come from JAX-RS, such as @POST, and @Consumes. These are not special to BMC Helix
Innovation Suite.
The @RxInstanceTransactional annotation is needed here because this entire call needs to run within a Record
Service transaction. If any exception is thrown, all database operations are automatically rolled back.
The @AccessControlledMethod is needed to allow administrator-level operations for all valid users.
The @Context annotation causes the UriInfo object to be properly populated. This is needed to construct the
valid URI for GET that should be the Location header in the Response.
MealOrderResource.java - Snippet
. . .
@POST
@Consumes(MediaType.APPLICATION_JSON)
@RxInstanceTransactional(
readOnly = false,
isolation = Isolation.DEFAULT,
rollbackFor = { Exception.class } )
@AccessControlledMethod(
authorization = AuthorizationLevel.Administrator,
allowOperationInServerGroup = true )
public Response post(@Context UriInfo uriInfo, NewMealOrderRequest newMealOrderRequest) {
// Note that the incoming parameters are automatically serialized into a

// "DTO" (or "data transfer object"). In this case, the information provided is not technically
// part of the "domain object" which is MealOrder.
// We delegate to the MealOrderService to actually instantiate the record instance in Innovation

Suite,
// because it has to do a number of other housekeeping tasks as well, such as associating the request
// with Dish and Employee.
MealOrderService mealOrderService = MealOrderServiceImpl.getMealOrderService();
MealOrder mealOrder = mealOrderService.createSingleConsumerOrder(

newMealOrderRequest.getDish(),
newMealOrderRequest.getConsumer(),
newMealOrderRequest.getRequestedDate());
// The standard use of REST semantics with POST are that it always creates a domain object. The
// return value should be the URI to the newly-created resource. In this case, we are
// generating the URI that will work with the GET implementation below.
URI uri = uriInfo.getAbsolutePathBuilder().path(mealOrder.getId()).build();
return Response.created(uri).build();
}
. . .
Also of note is the use of NewMealOrderRequest to represent the deserialized parameters of the call. This technique is
known as a Data Transfer Object, or DTO for short. The purpose of this is to allow the REST framework to automatically
handle the parameters. We could conceivably use the domain class, MealOrder, for this purpose. However, in this case,
constructing a new MealOrder only requires a few parameters; many of the others are derived or set later on by the
application. We don't want to allow API clients to attempt to set these members of the domain object.
A perfect example of this is that the restaurant name is part of the domain object. However, the API does not allow this
to be set as part of an order; rather, it is implied by the Dish that is associated with the Order, that is in turn associated
with a Restaurant. So, rather than expose the restaurant information as part of the POST, we require a special DTO
whose only purpose is to represent the supported parameters. We don't bother with the DTO for GET because it is safer
to return all the fields of the MealOrder domain object, which itself is a POJO. That way, new fields added to the object
are automatically serialized.
NewMealOrderRequest.java - Data Transfer Object
package com.example.meal.business.domain;
public class NewMealOrderRequest {
public String dish;

public String consumer;
public String requestedDate;
public String getDish() {

return dish;
}
public void setDish(String dish) {

this.dish = dish;
}
public String getConsumer() {

return consumer;
}
public void setConsumer(String consumer) {
this.consumer = consumer;
}
public String getRequestedDate() {

return requestedDate;
}
public void setRequestedDate(String requestedDate) {

this.requestedDate = requestedDate;
}

Once again, we have pushed the "heavy lifting" of this request down to the MealOrderServiceImpl class. Of special
interest there are all the operations that are required to validate the request, and then create the desired associations
between the Order, the Dish, the Restaurant, and the Employee records involved. Here is some pseudo-code to
represent the implementation of the createSingleConsumeOrder() method:
createSingleConsumerOrder - pseudo-code
/**
* this is pseudo code!
*/
MealOrder createSingleConsumerOrder(String dishName, String consumer, String requestedDate) {
// Look up the dish and consumer specified. At this point it serves to validate these.
String dishId = lookupDishByName(dishName);
String employeeId = lookupConsumerByName(consumer);
// Create the record instance object for the order, in memory.

RecordInstance mealOrderRecordInstance = recordService.buildRecordInstance(MealOrderConstants.
MEAL_ORDER_RECORD_DEF_NAME);
// Set the requested date value.

mealOrderRecordInstance.setFieldValue(MealOrderConstants.MEAL_ORDER_REQUESTED_DATE_FIELD_ID,
convertedEpochValueOf(requestedDate));
// Persist the Order using the Record Service.

recordService.createRecordInstance(mealOrderRecordInstance);
// Now for the associations.
// First, associate the Dish to the Order.

associationService.associate(
MealOrderConstants.MEAL_ORDER_DISH_CAN_BE_ORDERED_ASSOCIATION,
dishId,
mealOrderRecordInstance.getId() );
// Get the Restaurant associated to this Dish. We need to look this up because
// the API client did not specify it (it is implied by the dish).
Map<String, Object> restaurantRecord = getAssociatedRecord(
MealOrderConstants.MEAL_ORDER_RESTAURANT_PROVIDES_DISHES_ASSOCIATION,
dishId,
true);
// Now associate the Restaurant directly to the Order

MealOrderConstants.MEAL_ORDER_RESTAURANT_FULFILLS_ORDERS_ASSOCIATION,
(String)restaurantRecord.get(guidFieldId),
mealOrderRecordInstance.getId());
// Associate the consuming Employee to the Order.

MealOrderConstants.MEAL_ORDER_ORDERS_ON_BEHALF_OF_EMPLOYEES_ASSOCIATION,
mealOrderRecordInstance.getId(),
employeeId );
// Rebuild the meal order domain object (to populate the computed values)
MealOrder mealOrder = buildMealOrder(mealOrderRecordInstance.getId());
return mealOrder;
}
To try out POST, be sure to set the following header to some value (it does not matter what you set it to):
Header required for POST

x-requested-by: x
Also note the format required fo the requestedDate.
The body looks something like this. Note that, if successful, you will find a header in the response that is a valid URI to
perform the reciprocal GET operation.
Another Implementation for CSV

A very similar class creates a MealOrderCSV resource that serialzes an MealOrder differently. The big difference is that
the serialization is done "manually" without using Jackson, so you would have to update this code if new data members
were added to the MealOrder domain object and you wished to return them.
Challenge
Create your own RestfuResource to expose a Restaurant in a custom way, and test it with Postman.
You are not limited in what kinds of in-bound HTTP API interactions you want to create.
The BMC Helix Innovation Suite SDK comes ready to create your own RestfuResources by using some standard
annotations.
Following proper REST "semantics" is a best-practice but is left up to you.
For more information, see Creating a custom REST resource (see page 875).

A custom Command for the MealOrderService

Sometimes the canonical REST semantics just do not cover the behavior you want in an API. Let's say that you want to
perform some operation that will have a side-effect on the system, de-commissioning some asset, or invoking some
other API to create an account. If you are a computer science purist when it comes to the idea of REST (RE
presentational State Transfer), you know that such operations are not really "resources" in the expected sense of a
"REST-ful API". For example, you can't really logically GET a Command, and if you could PUT one, it would not be the
same resource that you would GET or DELETE. The solution is to implement a special Resource that itself represents an
invocation of a particular operation; so, it only supports POST. The operation to be performed, and its arguments, are all
simply parameters to the POST.
The BMC Helix Innovation Suite SDK already provides just such a Resource, called /api/rx/application/command. You have
already encountered it in the form of a System Command - com.bmc.arsys.rx.application.user.command.LoginCommand.
The nice thing is that you can easily write your own Command class and POST to it as well.
Obviously, like DataPageQuery, a Command is a built-in resource, mapped to your custom class.. It's purpose is simply to
execute some code using parameters supplied with the POST operation.
As we saw earlier, the MealOrderService includes the cancelMealOrder() method, so most of the work is already done.
We just need to wrap it in the CancelMealOrderCommand class that extends com.bmc.arsys.rx.services.common.
Command and overrides its execute() method. Here is the pseudo-code for the implementation.
CancelMealOrderCommand.java - snippet
public class CancelMealOrderCommand extends Command {
private String id;
public String getId() {

return id;
}
public void setId(String mealOrderId) {

this.id = mealOrderId;

@Override
@RxDefinitionTransactional(readOnly = true, isolation = Isolation.DEFAULT, rollbackFor = Exception.class)
@AccessControlledMethod(
authorization = AuthorizationLevel.SubAdministrator,
licensing = LicensingLevel.Application,
checkSchemaForSpecialAccess = true,
promoteStructAdmin = true )
public URI execute(UriInfo arg0) {
ServiceLocator.getLogger().info("CancelMealOrderCommand called for meal order " + getId());
MealOrderServiceImpl.getMealOrderService().cancelMealOrder(getId());
return null;
}
}
A few things to note:
Parameters (such as the mealOrderId in this case) are passed using a standard setPARAMETER() method that is
discovered by reflection, where PARAMETER is your parameter name. You do not need to do anything special to
pass parameters in, other than use the correct name. Thus, the mealOrderId URL parameter becomes accessible
as a data member during execute().
The transaction management annotations are there since the Record Service will be used to manipulate data.
Access control annotations are applied so that this command can run in the security context of an admin,
regardless of the permission level of the session. In other words, this Command will work for any authorized user
in this case.
Testing our command is very simple using Postman:
As is typical with POST, instead of query parameters, information is passed in the Body of the Resource:
resourceType (required): your class name of com.example.meal.application.command.

CancelMealOrderCommand.
id - happens to be needed for the operation to work, as implied by the setId() method in the class.
Invoke POST.
As shown here, the url and id variables are defined in the current Postman Environment.

Try executing this using the ID of an Order that is not in Cancelled state, and confirm that the code did run and change it
to Cancelled.
Challenge
As part of an earlier challenge, you implemented a method in a RestaurantService that is appropriate to be

invoked as a custom Command class (if not, you can create one now). Create a Command implementation and
test it with Postman.
The built-in resource Command makes it very easy to create and deploy your own Command class
implementation.
For more information, see Creating a command REST resource (see page 874).
Logging and Error Handling for the MealOrderService

When building "real" code it is important to consider how users, or other developers on your team, will be able to
support it, including troubleshoot problems that arise. We have already used the Manage Processes screen to see what is
happening in business processes. When writing custom code, as we have in the Meal Program Library, you have all the
standard ways of tracing and debugging the code using standard tools.
Debugging
If your instance allows remote connections, you can use your IDE to connect to your instance, place breakpoints, single-
step through code, as described in the documentation. Note: most cloud-based development sandboxes currently do not
allow these connections.
Error Handling
In many cases, when errors occur it is best handled by catching an exception in the form of the RxException class. If iit is
indicating an error on the server, by default it will be propagated back to the client, and will be logged in the relevant
service log, such as process.log that is accessible in the same fashion as your own custom logs.
You may want to do some special handling of errors. You can actually implement a custom class that extends
RxException. In the sample code, you can see this in the class MealOrderException. In this class, we do several things:
We extend RxException, the exception thrown by the framework itself. This causes it to be properly
communicated back to the client.
Define our own constants for the different situations. We have elected to use a Java enum here called
MealOrderMessage, but we could have used static final int constants as well.
Because RxException uses integer error codes, we need to provide a constructor for MealOrderMessage that
converts from int, and an IntValue() method to convert the other way. Note: this code uses underscore
characters in the numeric literals for readability, as in 600_100 for 600100 - this may look strange, but the
underscores are ignored by the compiler and this is perfectly valid Java code.
We need to overload at least one of the constructors for RxException. For a simple message with appended text,
that wraps the original Exception, we use that particular constructor.
We pass the bundle-id to the framework so it can handle messages from different bundles properly.
MealOrderException.java

package com.example.meal.business.impl;
import com.bmc.arsys.rx.services.RxException;
public class MealOrderException extends RxException {
private static final long serialVersionUID = -1801158764215645524L;
public enum MealOrderMessage {

MEAL_ORDER_NOT_FOUND(600_100),
MEAL_ORDER_INVALID(600_101),
MEAL_ORDER_CANT_MODIFY(600_102),
MEAL_ORDER_CANT_READ_ASSOCIATION(600_103),
MEAL_ORDER_CANT_CREATE(600_104),
MEAL_ORDER_NO_SUCH_DISH(600_105),
MEAL_ORDER_NO_SUCH_EMPLOYEE(600_106),
MEAL_ORDER_BAD_DATE_FORMAT(600_107),
MEAL_ORDER_CANT_FORMAT(600_108),
MEAL_ORDER_CANT_LOAD_ORDER_INFO(600_109);
private final int intValue;
MealOrderMessage(int intValue) {
this.intValue= intValue;
}
public int intValue() {

return intValue;
}
}
public MealOrderException(MealOrderMessage errorMessage, String appendedText, RxException e) {

super(errorMessage.intValue(), MealOrderConstants.MEAL_PROGRAM_BUNDLE_ID, appendedText, e);
}
public MealOrderException(MealOrderMessage errorMessage, Exception e) {

super(errorMessage.intValue(), MealOrderConstants.MEAL_PROGRAM_BUNDLE_ID, e.getLocalizedMessage(), null)
;
}
public MealOrderException(MealOrderMessage errorMessage, String appendedText) {

super(errorMessage.intValue(), MealOrderConstants.MEAL_PROGRAM_BUNDLE_ID, appendedText, null);
}
}
You will note that there is no text provided for the error codes. That is because text must be provided in the localizable
properties file for this bundle, found in src/main/resources/localized-strings.properties.
resources/localized-strings.properties - default text for messages
600100=No such Order

600101=The Order is Invalid
600102=The Order cold not be modified
600103=Could not read data associated to Order
600104=Could not create order
600105=No such dish
600106=No such employee
600107=Not a valid date format
600108=Cannot format response
600109=Cannot load order information

In order to test this, as a developer, it is not enough to simply but the strings in this file. You will also need to run the
"localization" maven profile at least once. This causes these strings to be loaded into the string catalog of BMC Helix
Innovation Suite.
projects\meal-program-lib> mvn clean install -Plocalization
Here's an example where we wrap an RxException into a MealOrderException with our own error message. This code
also logs a different message directly into the configured log for this bundle.
MealOrderInfo.java Snippet
try {
MealOrderConstants.MEAL_ORDER_RECORD_DEF_NAME, getId());
}
ServiceLocator.getLogger().error("No such Order " + getId());
throw new MealOrderException(
MealOrderException.MealOrderMessage.MEAL_ORDER_NOT_FOUND,
getId(),
e );
}
This can be tested by invoking Get Order Info using an invalid Order ID.
Logging
As you may have noticed in the previous snippet, it is also possible to log various events at various levels. The Logging
Service provides a uniform way to format filterable information into a configured server-side log file that can be
managed and retrieved to trace through code execution. Your code can emit logging statements using the Logging
Service. For example, note the beginning of the MealOrderInfoDataPageQuery's execute() method:
MealOrderInfoDataPageQuery.java Snippet
ServiceLocator.getLogger().trace("Executing meal order data page query ");
To configure where this output goes, and the level of logging, find the com.example.meal-program-lib bundle
configuration in the Administration tab of BMC Helix Innovation Studio.

Here's an example of testing and examining the log (and also shows the use of exception wrapping). Consider the
following logging statements found in the cancelMealOrder() implementation.
MealOrderServiceImpl.java Snippet
/**
* Set an Order into the status Cancelled.
* @param mealOrderId
* @return
*/
@Override
@Action(scope = Scope.PUBLIC)
public boolean cancelMealOrder(
@ActionParameter(name = "mealOrderId") @NotBlank String mealOrderId) {
ServiceLocator.getLogger().trace("cancelMealOrder(" + mealOrderId + ")");
try {
MealOrderConstants.MEAL_ORDER_RECORD_DEF_NAME, mealOrderId);
}
ServiceLocator.getLogger().error("Cannot cancel - no such Order " + mealOrderId);
throw new MealOrderException(MealOrderException.MealOrderMessage.MEAL_ORDER_NOT_FOUND, mealOrderId, e);
}
if (ServiceLocator.getLogger().isInfoEnabled()) {
// Don't pay performance penalty for this operation unless this level is enabled.
ServiceLocator.getLogger().info("previous status was: "
+ mealOrderRecordInstance.getFieldValue(MealOrderConstants.MEAL_ORDER_STATUS_FIELD_ID));
}
ServiceLocator.getLogger().trace("cancelMealOrder updating status for "
+ mealOrderId + " to Cancelled ("
+ MealOrderConstants.MEAL_ORDER_STATUS_CANCELLED
+ ")");
// Update the meal order itself to be Cancelled.

try {
mealOrderRecordInstance.setFieldValue(MealOrderConstants.MEAL_ORDER_STATUS_FIELD_ID,

MealOrderConstants.MEAL_ORDER_STATUS_CANCELLED);
recordService.updateRecordInstance(mealOrderRecordInstance);
}
ServiceLocator.getLogger().error("Cannot set Order " + mealOrderId + " to Cancelled" + mealOrderId);
throw new MealOrderException(MealOrderException.MealOrderMessage.MEAL_ORDER_CANT_MODIFY, mealOrderId,
e);
}
ServiceLocator.getLogger().trace("END - cancelMealOrder(" + mealOrderId + ")");
return true;
}
Let's run this method to see the log output.
1. Create an Order - it will now be in Submitted state - and capture the ID using the Edit Data screen.
2. Using Postman to send the command:
a. Be sure to include the default-bundle-scope header. Otherwise, logging will only occur in the context of a
calling Application.
b. Pass the ID of the Order as the required parameter of the command.

3. Use the Mid-Tier to retrieve the mealprogramlibrary.log file that was configured earlier.
4. You can see the trace statements appearing in the log.
mealprogramlibrary.log - Snippet
INFO START - cancelMealOrder(AGGA4D22JRZ70AOWLJ0BOVPAFKA09O)

INFO previous status was: 0
INFO cancelMealOrder updating status for AGGA4D22JRZ70AOWLJ0BOVPAFKA09O to Cancelled
INFO END - cancelMealOrder(AGGA4D22JRZ70AOWLJ0BOVPAFKA09O)
5. Try a bad ID to test error handling:
a. Change the body of the POST.

b. Note the response shows the custom Exception text.
c. The log shows both trace and error statements.
mealprogramlibrary.log - Snippet
INFO CancelMealOrderCommand called for meal order bad-id

TRACE cancelMealOrder(bad-id)
ERROR Cannot cancel - no such Order bad-id
Challenge
Add your own logging, re-deploy the Library, and test it using Postman
Add your own error handling:
Add a new constant to MealOrderMessage.
Be sure to add English text for it in localized-strings.properties, and localize it using the -Plocalization
command.
Throw it under some circumstance in your code.
Test it with Postman to be sure it returns the right error.

To create maintainable code, make sure you are logging important events or adding appropriate tracing.
The Logging Service can be used to send logs to a retrievable file, or to view messages in the Browser (for
synchronous processes)
You can extend RxException in order to wrap it with more meaningful error messages.
For more information, see Handling exceptions (see page 877).
Using Custom JavaScript in your solution

It is always possible to create any kind of custom client, or integration, using any programming language or framework
you like, as long as it supports HTTP and REST-based interactions with services.
In addition to that, the BMC Helix Innovation Suite SDK provides a tight integration to custom View Components that are
built using the AngularJS framework. These will appear in View Designer and can easily be integrated with an application
at run-time, using the same techniques we have used for the standard components that we have been using all along in
this tutorial. For more information about this, please see Creating a custom user interface with AngularJS (see page 826).
The remainder of this tutorial will show an extremely simple "hello-world" type of component that is already included in
the Meal Program Library sample source code.
Creating a simple view component

Another powerful capability of BMC Helix Innovation Suite is the ability to code a custom visual component that can be
dragged into a View using View Designer, as described in Creating a custom user interface with AngularJS (see page 826).
A quick note here is not to confuse the AngularJS framework with another framework that is somewhat confusingly
called just plain Angular , which is not supported at this time. Currently, BMC Helix Innovation Studio's View Designer
supports Angular JS .
There is a very simple example of this in the Meal Program Library project, that you may have noticed appearing in the
Palette of View Designer, after you deployed the Library and refreshed your BMC Helix Innovation Studio browser. It's
only function is to take a parameter and format it into a heading (style H3) followed by the word " Restaurant:". Of course
this example is very trivial and in fact you would simply use the Rich Text Component to do this, but using this
component will help to understand how the code for any custom View Component works.
Overview
Let's check out how the View Component looks at design-time and run-time, after which we will study the code that
implements it. Open the View Designer for the Restaurants View you created earlier. Note the Meal Program component
called Restaurant Label. This comes from the custom code in the Meal Program Library. Drag it into the View - a good
spot would be just above the + New Dish Button. In the Property Inspector, use the Expression Editor dialog to bind the
First Selected Row's Name field as its input parameter.

Now when you Preview this View (or refresh the Application) you will see the currently-selected Restaurant Name
appearing as the content of the View Component.
Let's examine the code, which resides within the meal-program-lib project - you can find it under the
bundle\src\main\webapp folder.
First we'll notice the overall structure. Like most View Components, the project has at least these source files.

As you will discover here, a View Component is really nothing more than a pair of AngularJS Directives with some
additional declarations so it will work with the View Designer in BMC Helix Innovation Studio. At any point during this
explanation, remember that you can always reference documentation from the AngularJS website .
For this tutorial we will just note a few things about the sample code. If you are not very familiar with the AngularJS
framework, this code may be difficult to understand.
The AngularJS Module

A great place to start is the AngularJS Module that is declared as a container for all of this code. Note that we name-
space it with both the bundle-id and the component name; this will minimize conflicts with other JavaScript that may be
deployed in the same space. We also declare dependencies on some functionality in the standard library.
Hint: if you are working with retrieving Records and Associations some component of your own, you will need to add
additional dependencies here.
restaurant-label-module.js
(function () {
'use strict';
angular.module('com.example.meal-program-lib.view-components.restaurant-label', [
'com.bmc.arsys.rx.standardlib.security',
'com.bmc.arsys.rx.standardlib.view-component'
]);
})();
The Meal Program Library already has an AngularJS Module that is generated by the Maven Archetype when this project
was created. However, you are adding new code that must be compiled and loaded, so this built-in Module must have a
dependency on your new Module. For Libraries, this is where all custom View Components need to be listed so they can
be compiled and loaded correctly.
com.example.meal-program-lib.module.js
(function () {
'use strict';
angular.module('com.example.meal-program-lib', [
'ngSanitize',
'com.bmc.arsys.rx.standardlib.error-handling',

'com.example.meal-program-lib.view-components.restaurant-label'
]);
})();
The BMC Helix Innovation Suite View Configuration

The configuration of the Directive is placed in restaurant-label.config.js. This is a key big of logic that binds together the
component's Module with the various ways it is rendered (design-time and run-time), and declares the Properties of the
component that will be exposed to the View Designer once it is deployed. Consider the source code:
restaurant-label.config.js
(function () {
'use strict';
angular.module('com.example.meal-program-lib.view-components.restaurant-label')
.config(function (rxViewComponentProvider) {
rxViewComponentProvider.registerComponent([
{
name: 'Restaurant Label',
group: 'Meal Program',
icon: 'area_text',
type: 'com-example-meal-program-lib-restaurant-label',
designType: 'com-example-meal-program-lib-restaurant-label-design',
bundleId: 'com.example.meal-program-lib',
propertiesByName: [
{
name: 'label',
type: 'string',
isConfig: true,
isProperty: true,
isRequired: true,
enableExpressionEvaluation: true
}
]
}
]);
});
})();
There are some important things to note here so we will cover them one by one:
1. The component is registered with the rxViewComponentProvider resource, so it can show up in the Palette of
View Designer.
2. Basic attributes are declared here, such as:
name - text that appears in the Palette
group - will add to this section of the Palette or create a new section
icon - short name of a built-in icon from the Standard Library
type - this binds the component to a run-time rendering Directive, determined by converting the
"hypenated" name to "camelCase".

In this case, the directive referred to here as com-example-meal-program-lib-restaurant-label must be

actually named comExampleMealProgramLibRestaurantLabel. It will be declared, by convention, in the file
restaurant-label.directive.js and we will be examining this code a bit later on. This transformation is
required due to one of the quirks of AngularJS.
designType - similar to the "type" attribute, but refers to the design-time rendering Directive that will be
used in the View Designer canvas itself.
Similarly to the type attribute, com-example-meal-program-lib-restaurant-label-design implies the actual

Directive is named comExampleMealProgramLibRestaurantLabelDesign, and it will be placed by
convention in the file restaurant-label-design.directive.js.
bundle-id is self-explanatory
3. The propertiesByName attribute declares Properties (in this case, there is only one needed) that will be
accessible to the View Designer. The attributes are used as follows:
name: how this will appear in the Property Inspector and/or Edit Expression dialog's Available Values tree.
type: this is the data type. You can plug in custom design-time experiences but string is the simplest one
to use.
isConfig - because this is set to true, it will appear in the Property Inspector, so it's value can be bound to
other components (such as the First Selected Row of a Record Grid).
isProperty - because this is set to true, it will appear in the Edit Expression dialog's Available Values tree,
so it's value can be used by other components.
isRequired - the View Designer will not allow the value to not be set.
enableExpressionEvaluation - because this is set to true, the Edit Expression dialog can be used to build an
expression for the value. Otherwise, it has to be a constant value set by the user of the View Designer.
Run-Time Rendering
Since we have seen that the config calls for rendering Directives let's look at the code for them. As mentioned above, the
run-time rendering has to be done by comExampleMealProgramLibRestaurantLabel in the file restaurant-label.directive.js.
restaurant-label.directive.js
(function () {
'use strict';
.directive('comExampleMealProgramLibRestaurantLabel',
function ($q,
$filter,
rxSession) {
return {
restrict: 'E',
templateUrl: 'scripts/view-components/restaurant-label/com-example-meal-program-lib-
restaurant-label.directive.html',
scope: {
rxConfiguration: '='
},
link: function ($scope) {

var _config;
var init = function () {

_config = $scope.rxConfiguration.propertiesByName;
$scope.restaurantLabel = _config.label;
};
$scope.$watch('rxConfiguration.propertiesByName.label', init);
}
};
});
})();
Much of this code is very standard for creating a Directive in AngularJS and won't be explained here. Some important
points particular to BMC Helix Innovation Suite and this component are:
1. The camelCase Directive name of comExampleMealProgramLibRestaurantLabel was already explained above, as a

transformation of com-example-meal-program-lib-restaurant-label. It is not an aribtrary name, and it's worth
noting again that this naming convention is crucial to avoiding conflicts with unknown JavaScript that may be
deployed in the same environment.
2. The templateUrl attribute binds the html template that will be evaluated using the scope information - in this case
the scope object restaurantLabel - that is maintained by this Directive's code. It needs to have the fully-qualified
file name of com-example-meal-program-lib-restaurant-label.html to avoid collisions because this resource will be
compiled together with all View Components deployed to BMC Helix Innovation Suite.
com-example-meal-program-lib-restaurant-label.html
<div>
<h3><b>Restaurant: {{restaurantLabel}}</h3>
</div>
3. The link function populates and maintains the scope. When the Directive is initialized it pulls the label expression
from the _config, which is populated by the Standard Library through its binding to the run-time of the View. By
assigning it to the scope's restaurantLabel, this enables the use of the expression {{restaurantLabel}} in the
AngularJS template above, so it can render information coming from other components at run-time.
4. Finally, because we did configure this component with enableExpressionEvaluation set to true, it is not enough to
evaluate the expression just once at initialization time. We need to set up a listener so that there will be a call-
back of the init() function whenever the expression on which it is based is re-evaluated, so that the component
can be re-rendered. That is exactly the purpose of the $scope.$watch() call.
Design-Time Rendering
We have looked at all the code that configures and renders the component at run-time. However, recall that the config
specified a different Directive would be used at design-time. This is needed for the restaurant-label component because
it has dynamic data (namely, the label expression) which is only known at run-time. In fact, most components will have a
different design-time rendering than that which is used at run-time.

The design-time Directive is pretty simple, especially since it is static content. Although you can get very fance with the
design-time rendering, we are simply going to emit the label "Restaurant:". Remember that the name must be this
particular name in camelCase, comExampleMealProgramLibRestaurantLabelDesign, in order to be mapped back to the
hyphenated name com-example-meal-program-lib-restaurant-label-design in the config.
restaurant-label-design.directive.js
(function () {
'use strict';
.directive('comExampleMealProgramLibRestaurantLabelDesign', function () {
return {
restrict: 'E',
templateUrl: 'scripts/view-components/restaurant-label/com-example-meal-program-lib-restaurant-
label-design.directive.html',
scope: {
}
};
});
})();
There is not much else to note here, other than the html template snippet, which does not contain any references to the
scope or anything else that is dynamic.
com-example-meal-program-lib-restaurant-label-design.directive.html
<h3>Restaurant:</h3>
Challenge
Modify the design-time and run-time templates. Rebuild and deploy the project using the following command,
refresh the browser, and try out your changes.
Updating the Meal Program Library
projects\meal-program-lib> mvn clean install -Pexport -Pdeploy
If you have some experience with building JavaScript with AngularJS, and some time on your hands, this project is
completely open for you to change any aspect of this custom code. Create your own custom component for
Meal Program Library and deploy and test it. As always, to learn more, please consult the documentation; this
particular topic is found at Creating a custom UI with AngularJS (see page 826), and more information about the
framework is available in many places. A good starting place is from the AngularJS website .
Create some useful, common component in a brand-new library that you build using the Maven Archetype, as
described in Creating a project using Maven and the Archetype (see page 806).
Custom View Components are created using standard AngularJS technology. This is not the same framework as
the one known simply as Angular.
Certain naming conventions are important for scoping.

Registration of your Module is required.
You can create custom design-time as well as run-time experiences in your own code, and users can bind values
from other components in the View by declaring Properties.
Recap of Module 2
Congratulations! You have worked through many examples of how custom Java and JavaScript code can augment a
code-less Application. If you have taken the challenges along the way, you have had practice implementing many of these
same services and interfaces yourself.
As a recap, here are some of the topics you learned about in the context of our Lunch Catering solution:
Building and deploying a coded Library
Building a custom Service in Java, including:
Logging and Troubleshooting
Error handling
Annotating it to create Service Actions for integration with BMC Helix Innovation Studio
Implementing a custom Data Page Query for easy access through HTTP
Implementing a custom REST Resource.
Implementing a custom Command that is easy to invoke using HTTP.
Custom JavaScript UI components to dress-up your Views using AngularJS.
With development of the "1.0" version completed, we can now turn our attention into getting the bundle into a
releasable state by doing versioning, testing, and packaging, as well as creating an updated version.
Module 3 - Packaging, releasing, and upgrading your solution

In this module, you will get your application ready for release, and learn how to go about creating an update for it.Before
you begin this module, you should have completed at least Module 1 - Developing a full solution.
This module will cover a variety of topics around getting the Lunch Catering solution ready to deliver to users. We will
also show an example of beginning to develop the next update to such an application.
Testing your solution

This section provides you the information about how to test your application logic, such as the services, and use of
framework services (including any Rule or Business Process that you have created).

Creating automated tests for the Lunch Catering Process (see page 255)

Creating automated tests for the Lunch Catering Process

While still developing version 1.0 of your bundles, it is important to identify the important user stories to test.
Furthermore, you should write automated tests for these cases so that others can execute the tests you wrote, and in
fact you can deliver your test suite along with the packaged bundle. Luckily, the BMC Helix Innovation Suite SDK includes
an automation framework designed for exactly this purpose. It can be used to test your application logic: services, and
use of framework services (including any Rule or Business Process that you have created).
This framework is documented as part of the SDK documentation in Testing application logic with the automation
framework (see page 918). It itself based on another framework called JGiven which you can read about here. You
should also check out the sample automation code provided with the sample Task Manager application.
As the documentation describes, with JGiven, each test includes a Given state (the precondition of the test), and at least
one When state (the input for the test case), and Then state (the assertions of expected behavior). It may even have
multiple pairs of When and Then to follow a long running execution, for example, of an asynchronous business process
with multiple blocking operations. Using method names that read as English helps to make the test use case easily
understandable; adding parameters in the right places makes it easy to re-use these methods for slightly different use
cases. Also, by avoiding return values in these methods (which may require the use of injected variables as is explained in
the documentation), we essentially turn Java into a kind of scripting language for describing and executing tests. The
Then state methods will typically contain the Assert statements that will compare expected and actual results and issue
the errors at runtime (and stop that particular test).
Let's consider the pseudo-code for a test that verifies one use case for the Order Lifecycle process we created in Module
2. In terms of code, your tests will be methods of MealOrderTest that extends the framework's BaseTest class. The
methods for each phase live in the respective class for that test state, such as MealOrderGivenState,
MealOrderWhenState, and MealOrderThenState. Let's consider a method of MealOrderTest called
testNormalOrderAutoClosed() and how the use case is functionally described. Note that UI behavior is simulated by
methods that use the REST API with the server.

Taking each state we can turn the "English" explanation into pseudo code. By the way, this could be used as a template
for designing your test code at a high level before starting to implement it.
Use Case: Normal Auto-Closed Pseudocode
Given that... given()
A non-admin user logs in. .login_non_admin();
When... when()
The order status becomes "In Progress"... .the_meal_order_status_changed_to_$("In Progress")
and waits for a few minutes to give the process a change to resume... .and().wait_$(2);
Then we expect... then()
Notification was sent .expect_notification("in progress);
When... when()
The order status becomes "Delivered"... .the_meal_order_status_changed_to_$("Delivered")
and waits for a few minutes to give the process a change to resume... .and().wait_$(2);
Then we expect... then()
Notifications are sent to submitter .expect_notification("delivered")
Notifications are sent to consumer .and().expect_consumer_notifications("delivered")
Delivery date and time is within 10 minutes of submission time .and().expect_delivery_time_within_ten_minutes()
We would then need to implement the following methods in the respective classes. Note that including a _$ in the
method name automatically causes the first parameter to be echoed as part of the test output.

Note that when one method needs to share information with another (such as the work order id in this case), this
member variable can be injected automatically into methods, rather than using static variables.
@ProvidedScenarioState(resolution = Resolution.NAME)
String mealOrderId;
Also, to help with the REST-based communication with the server, a helper class can be extended from the BMC Helix
Innovation Suite framework's RecordInstance class in order to work more easily with the REST calls that the automation
framework needs to make to simulate user interaction.
We can imagine creating other tests to handle different use cases with the Work Management application created in this
tutorial. Note that it is perfectly appropriate to include negative cases to test error handling.
testtMealOrderCancelBeforeDelivery()
testtMealOrderCancelAfterDelivery()
. . .and so on.
The number and depth of the tests should be clear enough by examining the overall test method code, and the output,
so that someone other than the developer can have some confidence that the tests are meaningful.
Eventually when you package the application zip, it will include your automation test jar that others can run against your
deployed application.
Releasing version 1.0 of your solution
Getting ready
This is about creating the final artifacts for installation of your solution, and preparing your development environment
for working on the next release (let's call it 1.1).
Create the Install Package for your codeless Application

This is simple enough and is fully documented in Deploying codeless applications (see page 763). The quick steps
relevant to the tutorial are shown below.
Note that by default, the version will be set to 1.0.0, and this is usually what you want for your first release.
From the Application main page, use the Create Install Package command in the Actions menu to start the wizard.

Mostly clicking Next to get through the wizard, click Create Package.
After the package is created, you can download it.

This usually into your local machine's Downloads area.
Important
You must use the 7-Zip utility to extract the contents of the ZIP file, and view the install package components.
The contents of the install ZIP file cannot be extracted by using the Windows Zip utility or Mac archive utility.
If you unzip the package, you will find each type of definition object has its own .def file. This can be placed into source
code control, or kept somewhere else as a backup.

Note: you can update the version number displayed in BMC Helix Innovation Studio at any time, by re-packaging the
application with that version (and don't forget to refresh your browser afterward). You do not need to actually download
the package.
Create the Install Package for your Coded Library

Assuming you have done Module 3 and have the Meal Order Library to distribute as well, you need to package that as
well. Since you built this with command-line tools and other IDEs, you should be comfortable using that approach to
package it as well. This step ensures that you have the latest files (both definitions, and code) in one place, so that you
can manage these with a Source Code Repository or any other means of handling files. It also allows you to resume
development of a new version.
The maven Archetype generated your original POM.XML file for your project, and by default, the version was set to 1.0-
SNAPSHOT. This is appropriate to use during development, but you will need to change this at least twice: once to set
the packaged version to 1.0.0, and again to reset it to 1.1-SNAPSHOT to resume development of the new version. Let's
walk through the steps:
1. Update the version in the POM.XML file.
pom.xml snippet
<groupId>com.example</groupId>
<artifactId>meal-program-lib-all</artifactId>
<version>1.0.0</version>
<packaging>pom</packaging>
2. Create the Install Package, which will be available as com.example.meal-program-lib-1.0-SNAPSHOT.zip.
Export and Package
projects\meal-order-lib> mvn -Pexport package
3. In order to resume development, you could decide to update the version again so it shows up correctly in BMC
Helix Innovation Studio.
pom.xml snippet
<groupId>com.example</groupId>
<artifactId>meal-program-lib-all</artifactId>
<version>1.1-SNAPSHOT</version>
<packaging>pom</packaging>

Now deploy it back to your BMC Helix Innovation Suite instance. The correct version should show up now in BMC
Helix Innovation Studio.
Export and Package
projects\meal-order-lib> mvn clean install -Pdeploy
What you Learned
Codeless applications and libraries are versioned at the time of packaging, using BMC Helix Innovation Suite.
Coded applications and libraries are also versioned at this time, by performing a manual adjustment to the POM.
xml.
In either case, the developer is responsible for tracking and managing the source files of the application.
Creating consumable changes for version 1.1

Imagine that we want to add some kinds of improvements in the next version of the Lunch Catering application. Before
beginning work on this, it's important to understand what kinds of changes can be safely consumed by customers after
upgrade.There is a thorough discussion of this Guidelines for Digital Service application definitions customization (see
page 313).
As the article mentions, there are three categories of how features can be consumed:
They are automatically in force after upgrade
Admins can Opt-In to enable them
The application can be customized to use them
Let's consider some examples of each of these kinds of changes.
Example of an automatically consumed change

When you improve your implementation in a way that does not adversely impact any users, and no steps are required to
benefit from them, then those changes fall into this category. Some examples that could apply to the Lunch Catering
system we have built would be:
Improve the implementation of the Meal Order Service to make it more efficient. For example, it could probably
obtain the same information with fewer queries.
Refactor of code to improve clarity or maintainability. Take caution with the renaming of object definitions,
however. If you refactor any Service API interfaces, be sure to provide a wrapper to maintain backward-
compatibility with the older interfaces.
Fix a defect - but only if the customer could not have been taking advantage of the "defect" to create supported
value in the offering.
Improve the implementation of non-customizable Processes (especially "Technical Processes" that are part of the
"behind the scenes" implementation), or other objects, that were set to be not customizable in the earlier
version, as long as there is no apparent behavior change, and this has no other side effects on the system that
customers may have been relying on
This is not a complete list but gives the general idea.

Example of an opt-In change

The Java-based Meal Order service that was introduced in version 1.0 calculates the cost of a Meal Order using a
configurable tax rate. Now a requirement has come in that the tax rate needs to reflect the state or region where the
Employee is based. Clearly this requires a revision to the code that computes Order cost, so that it can obtain the
Employee's home state, and look up the relevant tax rate. However, it might also disrupt existing customers who have not
yet configured the rate information from each region.
One way to make this kind of change "opt-in" would be:
1. Introduce a new Setting of type Boolean called Use Regional Tax Rates, with the default value False.
2. Build out the configuration model for tax rates for different regions.
3. Integrate this in the code, but be sure that without turning on the new Setting, the previous computation delivers
the same results when GetOrderInfo is invoked.
4. Document the use of the new Setting and how to configure regional tax rate data.
Example of a change consumable by customization

These kinds of changes are made by providing purely additive value and then instructions on how to consume them. We
will dive into an example of this in the next topic.
Consume by customization: enabling safe process customization points
Overview
From the previous topics, we know that some kinds of enhancements will not fit the simple model of "automatic" or "opt-
in". Sometimes, there will be more substantive changes that will require the customer to perform more involved
customization in order to consume the new capability.
This topic actually attempts to "kill two birds with one stone" in a sense. It not only provides an example of feature
consumed by customization; it also shows one technique for making the application itself inherently more customizable
going forward without even requiring any kind of upgrade!
Applications are Not Customizable by Default

In order to encourage developers to carefully consider the potential for customization up front, all of the definitions you
have been creating have used a setting called Application Scope by default. This means that they will be completely
locked-down for customization purposes. This is often a good thing, because it means that:
As a developer, you have control over what happens with the application at run-time.
You will be able to safely modify any of your definitions when releasing an Update Package, so that your
consumers don't need to worry about having their customization overwritten, or have the application suddenly
stop working.
Of course, the downside of this is that the application has become somewhat less flexible. Essentially, the only kinds of
customization that can happen now are:
Configuration / Settings types of changes (whether using the Settings Service or just by using Record-based
configurations of your own)

Additive changes, such as creating new Records, new Views, new Rules, and so on.
Skinning / Branding of the color scheme.
One area that customers should have access to is the Business Process (in the case of this tutorial, this is represented
mostly by the Order Lifecycle). One strategy here is to make this process completely Public Scoped and Customizable.
This is a valid way to go, as long as you understand the implication of this decision.
As a developer, you can never change this process in a later version of the application, or if you do, be aware that
your changes may be "hidden" by customization. You will also need to make sure there is nothing in the process
that is essential for the integrity of the application. In the case of Order Lifecycle, since the behavior of the
process is mostly about state changes and notifications, you might get away with this approach.
Another way of handling this is provide a new version of the process (such as Order Lifecycle v2), and instruct
the customers on how to consume this. The downside of this is that the workspace becomes cluttered with
different versions of the same process; also, it may make it difficult to know which processes rely on the
interfaces of other processes.
Allowing Customization through Extension

There is actually another way of handling this, that allows some measure of control but still allows important
customization to occur. In this approach, you build in anticipated customization points into your non-customizable
process. To do this:
1. Identify an aspect of behavior that you would like to be completely customizable. Often these have to do with
customer specific workflows (such as approvals), or integrations. It's best if this kind of behavior is "additive" to
the essential functioning of the application.
2. Create a default, Public Scoped, Customizable stub process that represents this additive behavior.
3. Modify the master process so that it invokes the stub. Leave it as Application Scoped (implicitly Not
Customizable).
4. Don't forget to document your new customization point.
Let's say that you have heard that an influential minority of customers would really like to include an invoice-generation
feature as part of the application. However, you feel that a) you want to go ahead and release the first version without
this functionality, b) every customer will probably want to do invoicing differently from every other customer, and c)
Process Designer and BMC Helix Innovation Studio will be a great way to allow customers to extend the application into
this area themselves.
Add an Invoicing Customization Point

Let's quickly build the customization point.
1. The customization point will be called Prepare Custom Invoice. It will operate on an Order, and be invoked as part
of the Order Lifecycle, whenever an Order goes into a Closed state.

2. Before implementing the stub, you must change the Order Record Definition to be Public Scope (but leave it as
not Customizable). This is because consumers will not be allowed to tailor the Prepare Custom Invoice process if
it refers to an Application Scoped definition.
3. Create the new Prepare Custom Invoice stub process. Since this is a simple default, it should do nothing when it
runs.

Make sure that the Scope / Customization Options are set to allow customization, and that it takes an Order Input
Parameter.
4. Update the Order Lifecycle process to perform a Call Activity on the stub process. Make sure it accepts an Order
Record as its Input Parameter. All other data associated with the Order, such as cost, department, and so on, can
be obtained later using associations of Order.

5. Create some documentation about this customization point, so that consumers will know that they can easily
define their own "child process" about invoicing and plug it in here.
That's it! We have now created a great customization point that opens up our application for customization in a specific
area, will leaving the bulk of the logic, that relies on Status changes for the UI to work correctly, safely locked-down.
Challenge
Dream up your own customization point. A great one would be Approve Order. You could consider having your default
Approve Order process have an Output Parameter that is always indicating approval. Your customers could override
(Customize) the Approve Order process, either by using the out-of-the-box Approval Service, or by doing something else
that makes sense to them. The nice thing here is that your master Order Lifecycle process can remain untouched.
What you Learned
You can provide means for customers to consume new functionality by means of customization; that is, using
BMC Helix Innovation Studio to create their own Records, Views, and Process.
One especially good way to combine Non Customizable definitions (that are evolved by the developer) and Public
Scoped / Customizable definitions (that essentially belong to the customer) is this concept of a customization
point. This is really just a best practice around having clearly defined interfaces.
Consider that you could actually build most of the logic of your application this way: ready to be customized safely. All it
takes is some care in designing how the different parts of the business process fit together, and which ones are safe to
modify.
Packaging up a new release as 1.1 for install and upgrade

Let's say that our version 1.1 of the application has been fully tested and is ready for release. How should it be packaged
now?
Considering that we may want to treat new customers (starting with 1.1) differently from existing ones (who have already
consumed 1.0 and may already have configuration data, and so on) we need to create different packages for each case.
Luckily, BMC Helix Innovation Suite has a concept of an Update Package, that contains just those definitions and data to
be deployed to upgrade it to the new version. While not mandatory to be used (you can always ask customers to install
the full Install Package instead), there is some efficiency in only updating those objects that have been modified,
especially for very small "patch" releases.
Consider three releases and customers installing them at different times. The package names we ultimately will need
could have the following suffixes:
New Customer as of: To Consume 1.0 To Consume 1.1 To Consume 1.2
1.0 -1.0.0-INSTALL.zip -1.0.0-1.1.0-UPDATE.zip -1.1.0-1.2.0-UPDATE.zip
1.1 -1.1.0-INSTALL.zip -1.1.0-1.2.0-UPDATE.zip
1.2 -1.2.0-INSTALL.zip
You can find out how to create an Update Package at Creating update packages to deploy incremental updates to
applications (see page 769).
For our Lunch Catering application you would use the Create Update Package command.
When selecting definitions to include, think carefully about what is needed to implement your new features. For example,
to implement the Prepare Custom Invoice customization point from the last tutorial topic, your selection of definitions
might look like this:

A few things to pay special attention to:
Get the version identifier correct
Take great care in picking out definitions that have been changed to support the release.
Be aware that you can see all the definitions that have been deleted, and can have this deletion propagate to
customers when they install the Update Package. Be very careful with this.
Data can be ordered because sometimes there are dependencies between the data.
Note that you will need to use this same technique on both the codeless application, and coded library, in your solution.
There is no command-line support at this time for creating an Update Package.
What have you Learned
BMC Helix Innovation Studio supports creating Update Packages as well as Install Packages.
You can choose to use Update Packages for existing customers, especially useful for very small "patch" releases.
But care must be taken to deploy a consistent set of definitions. When in doubt, it is always possible to ask even
existing customers to use the Install Package, and this will potentially update all the definitions.
The Update Package can be used as a way to clean up old definitions that should be removed. Again, great care
must be taken that these are Application Scoped or otherwise Not Customizable, or else removing them could
cause a serious problem after applying the upgrade.
Cleaning up
When preparing BMC Helix Innovation Studio for a new project, or after completing a project, you can reset the
environment to remove bundles from a server so that they no longer appear.
Preserve your work

If you have not already created the Install Packages and otherwise captured your source files, as described earlier, it is a
good idea to do that now before removing your projects from BMC Helix Innovation Suite. There is no way to recover
your projects once they are removed .

Uninstall the Lunch Catering application

Use the Uninstall Application command from BMC Helix Innovation Studio.
Undeploy the Meal Order Library

You can easily remove the bundle from BMC Helix Innovation Suite by using maven.
Undeploy
projects\meal-order-lib> mvn com.bmc.arsys:rx-sdk-maven-plugin:undeploy -N
Once you refresh the browser workspace, it will no longer appear.
Hands-on Lab Exercises

Welcome to the BMC Helix Innovation Suite hands-on lab exercises. This is divided into three separate sessions. The labs
make heavy use of the tutorial content, but are designed for 1 hour sessions in a group setting. Sessions 2 and 3 have a
install package available to "catch up" to where you need to be in each case.
The starting point for each session is as follows:
LAB: Create an Application in BMC Helix Innovation Suite - Getting Started (Session 1 of 3) (see page 269)
LAB: Create an Application in BMC Helix Innovation Suite - Create Powerful Views (Session 2 of 3) (see page 270)
LAB: Create an Application in BMC Helix Innovation Suite - Deep Dive on Process Designer (Session 3 of 3) (see
page 273)
LAB: Create an Application in BMC Helix Innovation Suite - Getting Started (Session 1 of 3)
Welcome to the Hands-On Lab series for BMC Helix Innovation Suite! These exercises are based on the learning tutorial
content that are part of the BMC Helix Innovation Suite documentation.
Prerequisite
A developer sandbox running BMC Helix Innovation Suite. If you don't already have this, please request one from
developer.bmc.com.

Supporting Public Documentation

It is recommended that you have read the introductory information, such as the orientation found in the published BMC
Helix Innovation Suite documentation (see page 30). Note that in the tutorial content itself, some links to
documentation may not work correctly because the tutorial content is not yet part of public documentation. In this case,
always refer to the currently published documentation at the preceding link.
Scope of this lab

This session is designed to build a complete, minimal, working application in one sitting. It touches briefly on each of the
major elements of code-less application development with BMC Helix Innovation Studio - Record, View, Process, and
Rule.
Lab guide
This lab follows the steps laid out in Quick start: creating a simple app to order some lunch (see page 68) tutorial for
BMC Helix Innovation Suite.
Upon completion
If you are already somewhat experienced with BMC Helix Innovation Studio, this will go very quickly. If you have extra
time, you can assist others around you (this is a great way to cement your own learning). Also, especially if you plan on
attending the follow-on lab session, Create an Application in BMC Helix Innovation Suite - Create Powerful Views, you can
get started creating the data model for that lab This will allow you to use your own application as a starting point.
Otherwise, you will be using that lab's 2.0.0 Install Package to get a quick start and it will come with a full data model for
that lab. If you are enrolled in the second session you can jump to LAB: Create an Application in BMC Helix Innovation
Suite - Create Powerful Views (Session 2 of 3) (see page 270).
LAB: Create an Application in BMC Helix Innovation Suite - Create Powerful Views (Session 2 of 3)
Welcome to, or welcome back to, the Hands-On Lab series for BMC Helix Innovation Suite! These exercises are based on
the learning tutorial content that are part of the BMC Helix Innovation Suite documentation.
Prerequisite
A developer sandbox running BMC Helix Innovation Suite. If you don't already have this, please quickly request
one from developer.bmc.com.
Install the tutorial application, with full name com.example.lunchtutorial, version 2.0.0. Note that if you were in
the earlier lab session, you probably created your own similar application using your own application id. Installing
this one will not affect your previous work. The reason to install this one is to make sure the lab instructions
match your starting point exactly.
1. If, for some reason, you happen to already have an your instance with the exact id com.example.
lunchtutorial, it is best to remove it by using the Uninstall command from the Actions menu on the
application page. Otherwise, you will be potentially updating some of the definitions and data but leaving
other older ones in place.

2. Download the zip file: Lunch Tutorial 2.0.0 Installation Package ("Complete Data Model").
Important
To download the ZIP file, right-click the URL > Save link as. The ZIP file will get downloaded to
the default download location of your web browser. You must use the 7-Zip utility to extract
the contents of the ZIP file, and view the install package components. The contents of the
install ZIP file cannot be extracted by using the Windows Zip utility or Mac archive utility.
Note that certain versions of Windows Explorer will report a format problem with the zip file, because of
a difference in the format of Java's zip library. You can ignore these errors.
3. In BMC Helix Innovation Studio, go to the Workspace area and click the Install button to load the zip onto
your BMC Helix Innovation Suite instance.
4. As a quick sanity check, you should now see this application as Lunch Tutorial in BMC Helix Innovation
Studio, including 3 Record definitions and 4 Association definitions.

If you have extra time, read through the application requirements analysis found in Analysis and design for a
solution to the lunch ordering problem (see page 90). For this lab setting we will be skipping right to
implementation, but if you are confused about the application's personas and requirements you can always refer
to this document.
Supporting public documentation

It is recommended that you have read the introductory information, such as the orientation found in the published BMC
Helix Innovation Suite documentation (see page 30). Note that in the tutorial content itself, some links to
documentation may not work correctly because the tutorial content is not yet part of public documentation. In this case,
always refer to the currently published documentation at the preceding link.
Scope of this lab

In this session, we will build three Views that demonstrate powerful techniques for working the record editors, grids,
action buttons, and containers, as are covered in Module 1 of the lunch application tutorial.
Before starting the implementation steps, if you loaded the installation package, take a minute to check out, in BMC Helix
Innovation Studio, the records and associations that were pre-created for you.
Dive in
Now, follow along the topics in the tutorial that introduce the three views, and go as far as you can.
1. Overview - Creating views for restaurants and orders (see page 110).
2. Creating a sliding panel view (see page 112)
3. Enhancing our New Order view to use associations (see page 126)
4.
4. Defining a view for managing orders (see page 134)
Upon completion
Nice job! If you are already somewhat experienced with BMC Helix Innovation Studio, this could have gone quickly. If you
have extra time, you can assist others around you (this is a great way to cement your own learning). Also, especially if you
plan on attending the follow-on lab session, Create an Application in BMC Helix Innovation Suite - Deep Dive on Process
Designer , feel free to get started on the Module 1 content that is all about adding business processes to your application.
If you have fallen behind, don't worry, because you will have the opportunity to install a solution to this lab so you will be
ready to start the next lab (see page 273).
LAB: Create an Application in BMC Helix Innovation Suite - Deep Dive on Process Designer (Session 3 of 3)
This is Part 3 of the Hands-On Lab series for BMC Helix Innovation Suite! As with the earlier labs, these exercises are
based on the learning tutorial content that are part of the BMC Helix Innovation Suite documentation.
Prerequisite
A developer sandbox running BMC Helix Innovation Suite. If you don't already have this, please request one from
developer.bmc.com.
Install the tutorial application, with full name com.example.lunchtutorial, version 3.0.0. Note that if you were in
Lab 1, you probably created your own similar application using your own application id. Installing this one will not
affect your previous work. The reason to install this one is to make sure the lab instructions match your starting
point exactly.
1. If you were already in Lab 2, you may have already started work on com.example.lunchtutorial based on
version 2.0.0. For this lab, you should install version 3.0.0 by following these steps:
a. Use the Create Install Package command to create a backup of your earlier work with com.
example.lunchtutorial (you could call it 2.1.0 for example).
b. Use the Uninstall command to remove it from your instance.
2. Download the Lunch Tutorial 3.0.0 Installation Package (Basic Views).
Note that certain versions of Windows Explorer will report a format problem with the zip file, because of
a difference in the format of Java's zip library. You can ignore these errors.
a.
2.
a. On the Workspace page, use the Install button to load the 3.0.0 Lunch Tutorial application and go
to the Application page.
3. Your BMC Helix Innovation Studio should look like this - note the Views that are already there.
If you have not already done so, and you have additional time, you could read through the application
requirements analysis found in Analysis and design for a solution to the lunch ordering problem (see page 90).
For this lab setting we will be skipping right to implementation due to time constraints, but it is a great idea to
have some idea of the personas and requirements and you can refer to this document for that purpose.
Supporting public documentation

It is recommended that you have previously read the introductory information, such as the orientation found in the
published BMC Helix Innovation Suite documentation (see page 30). Note that in the tutorial content itself, some links
to documentation may not work correctly because the tutorial content is not yet part of public documentation. In this
case, always refer to the currently published documentation at the preceding link.
Scope of this Lab

In this session, we will work toward building a complete business process for the lifecycle of a lunch order. Along the way,
we will use key process designer techniques including User Task, User Message, Timer, Exclusive Gateway, Multi-Instance
Loop, and Error Boundary. There is quite a bit of material here, and the expectation is that it is not likely to be finished
within one session, so the lab can be completed using your own sandbox after the session ends.
If you did not attend the earlier lab, take a minute to check out the user interface of the application by launching it, and
/or noting the definitions of the views. You will need to use this while testing the application logic in your process.

Lab Guide
Now, follow along the topics in the tutorial that introduce the process enhancements described in the section of the
tutorial:
1. Overview of building the Order Lifecycle process (see page 173)
2. Adding additional states to the order lifecycle (see page 176)
3. Implementing Order completion using a Timer (see page 183)
4. Using a Multi-Instance Loop for Employee notifications (see page 186)
5. Order cancellation with conditional gateways and exception handling (see page 192)
Upon Completion
As mentioned earlier, you may not have had enough time to complete all the process building techniques in this session,
but you can plan on continuing the lab after the session ends. If you are very experienced at BMC Helix Innovation Studio
and somehow do finish it, please assist others who may be struggling. Remember that there are many powerful
capabilities in BMC Helix Innovation Suite that were not touched on here, especially the ability to add native code to the
application. These are described in later modules of the tutorial.
If you would like to install the solution to all three of these lab exercises, you can uninstall whatever you have for this
application, then install the Lunch Tutorial 4.0.0 - Module 2 solution.
You can also install an even more elaborate version as Lunch Tutorial 5.0.0 - advanced menu view - this includes a set of
sample data and an enhanced view for ordering from a photo-based menu.
Happy Innovating!
User goals and features

The following table lists the BMC Helix Innovation Suite users, describes their goals, and explains how these users can
achieve their goals by using BMC Helix Innovation Suite.
Role Goals How BMC Helix Innovation Suite helps Documentation
Administrator Creating or modifying

Add and manage users and their Create and manage users and access
Foundation data (see page
information. permissions.
661)
Add and manage application business Set foundation data.
analyst users and their information.
Load foundation data in bulk.
Authorize users to use groups and access one or more

Manage permissions for users. Creating Functional
applications to perform various tasks in those
roles (see page 744)
applications.
Creating and
modifying
application roles
(see page 749)
Create and deploy codeless applications.

Role Goals How BMC Helix Innovation Suite helps Documentation
Intuitive UI and codeless application Developing codeless

customization, which has less dependency on a applications (see page 794)
developer.
Ability to create deployment packages to deploy

codeless applications in development, test, or
production environments.
Application Creating the definitions for

Deliver tailored applications and process Customize applications, for which you have
business a tailorable Digital Service
automation that improve the quality of access, without any programming skills or tools
analyst application (see page 323)
services delivered to stakeholders. training.
However, you cannot modify the Foundation
Provide improvements in business
data or deploy applications to other
processes.
environments.
Modify application definitions within an
Create applications that consist of multiple
application for which you have access.
business processes by modifying out-of-the-box
processes or creating the process from scratch.
Options to either publish the application as is or

with modified process configurations to meet
the organization's requirements.
Options to update the applications and

workflows without any dependency on the
developer; for example, drag-and-drop
configuration changes to the logic, flow, fields,
and layout.
Developer Developing and deploying

Build applications to meet the Create new applications by defining new data
code-based applications
requirements of different business model with role or license restrictions, and field
(see page 798)
stakeholders, such as product manager, level or client level security features.
business owner, and development lead.
Create new components for external service by
Define those features of an application or importing supporting library files to the
library that are open to customization, development environment.
while minimizing opportunities for
Define new package of component, libraries,
consumer customization to interfere with
abstractions, and related configuration and
the correct functioning of the application.
code.
Leverage existing code as much as
Create new components from platform services.
possible.
The developer defines new component and
Incorporate latest market trends and leverages platform features for scheduling,
technology to provide more value to the monitoring, metering, and security.
applications.
Integrate the application or platform with

other applications, systems, and
processes to meet the organization's
requirements.

Action Reference
To understand the responsibilities for the roles. Roles and permissions (see page 743)
To understand the concepts related to Digital Service applications, how to start with application development, Key concepts (see page 36)
and the recommended process to develop applications.

Use cases
Consult the following use cases for information on how to achieve value with BMC Helix Innovation Suite.
Use case Business value Products used
Empowering non- Helps an application business analyst to create codeless applications in a

BMC Helix Innovation Studio
developers to develop few clicks with minimal dependency on developers or development
codeless applications environment, and to promote codeless applications from a development to
(see page 277) test or production environments.
Leveraging Remedy Helps administrators to load and synchronize Foundation data from
Remedy ITSM
ITSM Foundation data Remedy IT Service Management (Remedy ITSM) Suite to BMC Helix
(see page 278) Innovation Suite. BMC Helix Innovation Suite
Atrium Integrator Spoon client
Leveraging cognitive Helps a developer to automate the manual tasks, such as data
BMC Helix Innovation Suite
capabilities in your categorization and task assignment, by using machine learning in their
application (see page Digital Service applications. IBM Watson Assistant
281)
Upgrading to a new Helps an administrator to reduce the downtime in production environment

version of an when upgrading to a new version of an applications. The administrator can
application with zero validate the new version in the test environment before exporting and
downtime (see page deploying it in the production environment.
286)
Leveraging full-text Helps an application business analyst to enable fields and record definitions
search capabilities in for a full text search.
your application (see
page 287)
Automating tasks Helps an application business analyst to use an incoming mailbox to

though emails (see automate certain tasks and to use an outgoing mailbox to send email
page 289) notifications.
Extendable application Helps a developer to create extendable definitions. Extendable definitions

definitions to allow ensure that the out-of-the-box objects remain unchanged, but developers
additive changes (see can add or remove new objects.
page 290)
Empowering non-developers to develop codeless applications

The goal of this use case is to enable an administrator to build an application without going through all the burdensome
work of setting up an IDE and learning coding skills.
Scenario
Consider a scenario of a large-scale organization, wherein an administrator wants to create a simple Lunch Order
application. The organization's employees can use this application to order lunch from a vendor's set menu.
To create an application within a few clicks from the user interface, and with minimal programming knowledge or
dependency on developers, administrator creates a codeless application Lunch Order. Codeless applications are created
without using BMC Helix Innovation Suite SDK or Maven archetype. These applications consist of definitions and data
only, and do not include libraries.
The following illustration compares the process of creating code-based applications and creating codeless applications:

Benefits
Creating codeless applications enables the administrator to perform the following tasks:
Quickly create applications from the user interface.
Develop applications with minimal programming knowledge or dependency on developers.
Reduce errors that might arise when developing code-based applications.
Reduce the turnaround time for creating applications that require less customization and are not complex.
Share the codeless application with developers to add complex customizations.
Workflow
Task Action Reference
1 Create an application quickly from the user interface without using Java or Javascript knowledge, by Developing codeless applications (see page
creating codeless application Lunch Order. 794)
2 Store the lunch orders created by employees, by creating record definitions. Defining record definitions to store and
manage data (see page 324)
3 Design a user interface from where employees can submit their lunch orders, by creating a view. Defining the user interface through view
definitions (see page 376)
4 Track the delivery time of the lunch orders, by creating a process. Defining the application business logic
through processes (see page 421)
5 Enable employees to access the Lunch Order application, by deploying the application to production Deploying codeless applications (see page
environment. 763)
Leveraging Remedy ITSM Foundation data

As a Remedy IT Service Management (Remedy ITSM) Suite and BMC Helix Innovation Suite customer, you can leverage
Foundation data from Remedy ITSM in BMC Helix Innovation Suite. The BMC Helix Innovation Suite Foundation library is
the source of information about people and their attributes such as organization, geography, location, and other shared
characteristics. To ensure faster onboarding and engagement of users in your organization, you can load existing
Foundation data from Remedy ITSM to BMC Helix Innovation Suite in bulk.

Benefits of leveraging Remedy ITSM Foundation data in BMC Helix Innovation Suite
Following are the benefits of leveraging Remedy ITSM Foundation data in BMC Helix Innovation Suite Foundation library:
The Foundation library now has more parity with Remedy ITSM Foundation data structure to ensure data
accuracy and consistency.
Easier transition of data semantics between Remedy ITSM and BMC Helix Innovation Suite.
Easier conversion between types of Organization and Person.
Reduced restrictions on Organization and Person so that customers have more control on Organization and
Person data.
Unrestricted Access person permission.
Company visibility for other Remedy ITSM companies.
Support Organization in the support hierarchy.
Supported scenarios to load Foundation data from Remedy ITSM to BMC Helix Innovation Suite
Customers can load Foundation data from Remedy ITSM in the following scenarios:
Scenario of loading Foundation data from Remedy ITSM for the first time
You are a customer of Remedy ITSM and have purchased applications developed on BMC Helix Innovation Suite, such as
BMC Helix Chatbot. You want to use Foundation data from Remedy ITSM in BMC Helix Chatbot to ensure faster
onboarding of users in your organization as well as to maintain data integrity. The administrator loads the out-of-the-box
and custom Foundation data from Remedy ITSM to BMC Helix Innovation Suite for the first time.
Scenario of continuously synchronizing updates to Foundation data from Remedy ITSM

Continuing with the above example, after loading Foundation data for the first time, you want to continuously
synchronize the following types of Foundation data to maintain data integrity between Remedy ITSM and BMC Helix
Innovation Suite:
Changes to existing custom Foundation data.
Newly-added custom Foundation data.

Changes to out-of-the-box Foundation data are automatically synchronized. You are not required to perform any
additional configurations.
Note
The sample Foundation data (seed data) is not synchronized from Remedy ITSM.
Before you begin
Download the Remedy Deployment Application (D2P package) containing the files required for loading and
synchronizing Foundation data from Remedy ITSM.

If BMC Remedy Action Request System (Remedy AR System) and Remedy ITSM are deployed in virtual
machines, see Installing the BMC Helix Innovation Suite sync utility for Remedy ITSM (see page 700).
Note: Check whether the D2P package for Foundation data load is downloaded as part of your activation.
Review the Foundation data load and synchronization considerations (see page 692)
Review the Limitations and upgrade considerations (see page 24)
Workflow to load Foundation data from Remedy ITSM

The workflow to load Foundation data from Remedy ITSM to BMC Helix Innovation Suite can be divided in three
phases—Preparing Remedy ITSM and BMC Helix Innovation Suite to load data, loading and verifying Foundation data for
the first time, and continuously synchronizing updates from Remedy ITSM.
The following table describes the tasks that you must perform in the specified sequence, the product in which you must
perform the task, the description of the action that you must perform, and the reference to the procedure:
Task Action Product Reference
Phase 1: Preparing to load data from Remedy ITSM
1 (Applicable only if you want to load custom Remedy ITSM Identifying fields added to view overlays
Foundation data)
Identify if there are any custom Foundation data

fields in supported Remedy ITSM data such as
People, Company, and so on. Also identify any
existing out-of-the-box Remedy ITSM fields that
are not currently loaded to BMC Helix Innovation
Suite.
2 (Applicable only if you want to load custom BMC Helix Innovation Suite Extending BMC Helix Innovation Suite
Foundation data) Foundation definitions (see page 704)
Extend the Foundation definitions in BMC Helix

Innovation Suite to include the custom
Foundation data fields in Remedy ITSM.
3 (Applicable only if you want to load custom Remedy ITSM Creating a Pentaho job for custom
Foundation data) Foundation data (see page 710)
Create a Pentaho job and transformation in

Remedy ITSM, so that the custom overlaid
Foundation data is identified, read, and loaded to
BMC Helix Innovation Suite for processing.
4 (Applicable only if you want to load custom Synchronizing custom Foundation data
Remedy ITSM
Foundation data) changes to BMC Helix Innovation Suite
BMC Helix Innovation Suite (see page 721)
Configure the synchronization of custom
Foundation data changes, so that these changes
are automatically synchronized to BMC Helix
Innovation Suite.
5 Connect the Foundation data repositories, so Remedy ITSM Connecting the Foundation data
that Foundation data can be loaded from repositories (see page 725)
Remedy ITSM to BMC Helix Innovation Suite.
Phase 2: Loading data from Remedy ITSM for the first time
6 Load Foundation data to BMC Helix Innovation Loading and verifying Remedy ITSM
Remedy ITSM
Studio for the first time. Foundation data (see page 727)

Task Action Product Reference
Phase 1: Preparing to load data from Remedy ITSM
7 Load Foundation associations to BMC Helix Loading and verifying Remedy ITSM
Remedy ITSM
Innovation Studio for the first time. Foundation associations (see page 731)
8 (Applicable only if you want to load custom Loading and verifying custom Remedy
Remedy ITSM
Foundation data) ITSM Foundation data (see page 735)
Load custom Foundation data to BMC Helix
Innovation Studio for the first time.
Phase 3: Verifying data from Remedy ITSM
9 View and monitor the Foundation data changes Remedy ITSM Viewing the synchronized Foundation data
that are automatically synchronized to BMC Helix (see page 737)
Innovation Suite.
Related topics
Foundation field mappings in Remedy ITSM and BMC Helix Innovation Suite (see page 696)
Leveraging cognitive capabilities in your application

As a developer or an administrator, you can automate manual tasks in a Digital Service application by using the BMC Helix
Innovation Suite Cognitive Service. Examples of manual tasks that you might automate include the categorization of data
and the assignment of tasks.
Auto-categorization and auto-assignment use the IBM Watson machine learning capability. You can use these capabilities
to automate manual tasks in your Digital Service application workflow. Auto-categorization and auto-assignment are
available as elements in the process designer and rule designer of BMC Helix Innovation Studio.
Scenario
Consider a scenario where in a support organization of a company, when an end user reports of an issue with a service, a
help desk agent creates a ticket, and based on the information provided by the user, classifies the ticket, and assigns it to
a support group. For example, a user reports that they are unable to send or receive emails, so the agent identifies this
problem as a network issue, creates a ticket based on the issue description, and assigns the ticket to a support group
that has expertise in resolving network issues. This process is manual and can be error prone.

To overcome the challenges posed by the manual process, the CTO of the organization decides to automate the process
of categorizing and assigning of tickets by using the BMC Helix Innovation Suite Cognitive Service. A developer then
develops a digital service application that includes the BMC Helix Innovation Suite Cognitive Service. The application now
includes the built-in cognition required to classify an issue based on the end user's natural language and assign that issue
to the right support group.
Roles involved in this use case

The following roles are involved in this use case:
Developer
Administrator

Adding cognitive capabilities to a custom application (see page 552)
Related topics
Leveraging conversation capabilities in your application (see page 282)
Leveraging machine learning metrics to improve cognitive service data sets (see page 283)
Leveraging conversation capabilities in your application

The goal of this use case is to enable a user to leverage conversation capabilities in an application by using the BMC Helix
Innovation Suite chatbot framework.
Scenario
In a support organization of a company, when a user wants to report an issue. To report an issue, usually a help desk
agent needs to know how to use an application to create a ticket, to classify the issue, assign the issue to a support
group, and so on. The support organization has a large number of issues that need to be reported daily and the help desk
agents perform the issue reporting task. The process of reporting issues is manual, involves learning, requires resources,
and can be error prone.
To overcome the challenges, the head of the organization decides to use an application that has conversation capability.
A developer then builds a BMC Helix Innovation Suite application that uses the chatbot framework. The chatbot
framework allows the application to include the built-in cognition required to report an issue based on a conversation
with the end user. The users now directly interact with the application chatbot in natural language and the chatbot
reports the issue on the behalf of the user. In this way, the organization saves resources and perform tasks accurately
without any human intervention.

Developer
Administrator
Capabilities
The chatbot framework provides the following capabilities to develop chatbot applications:

Integrates with chatbot collaboration service (such as Slack)
Provides open architecture to integrate with third-party collaboration services (such as Facebook Messenger)
Integrates collaboration service users with BMC Helix Innovation Suite users
Performs chat with users, updates response message and chat context with chat action results
Manages chat context
Persists chat context
Makes chat context available to all the nodes in a cluster (server group environment)
Performs efficiently in high load conditions by using horizontal scaling

Event mechanism is used to integrate the chatbot provider and BMC Helix Innovation Suite so that each node in a
cluster can handle chat events. When load increases, new nodes can be added to the cluster and the newly added
nodes can immediately join a conversation even in an ongoing chat session.

Adding a chatbot and conversational capabilities to your application (see page 576)
Related topics
Leveraging cognitive capabilities in your application (see page 281)
Leveraging machine learning metrics to improve cognitive service data sets

BMC Helix Innovation Suite Cognitive Service provides auto-categorization, auto-assignment, and chatbot capabilities for
an application. To utilize these capabilities, you must train IBM Watson Assistant to work with your data by creating data
sets. You can create a CSV file of the data set or select application data, and test the accuracy of the data sets to ensure
that the cognitive service and chatbot application correctly auto-categorizes service requests raised by end users.
After testing the Cognitive Service data sets, the test results provide the exact problem area when the data sets do not
predict the appropriate categories, so that you can rectify the data sets. The tests are particularly important when you
are implementing a new training data set or if you have made major changes to the data sets.
Benefits of testing the cognitive service

BMC Helix Innovation Suite provides a tool to test the cogniitive service. These tests are particularly important when you
are implementing a new training data set or if you have made major changes to the data sets. Testing the Cognitive
Service and chatbot has the following benefits:
You do not require prior knowledge of data science to use this tool.
Helps to evaluate the cognitive service on the basis of standard machine learning algorithms.
Helps identify the exact area of problem so that you can rectify the data sets to improve the performance of the
cognitive service.
Provides a history of the test results.

Test metrics derived after testing the cognitive service data sets
You can test the BMC Helix Innovation Suite Cognitive Service to get the following test metrics:
Accuracy—Accuracy is the ratio of number of correct predictions to the total number of input samples.
For example, if the test results indicate that 9 out of 10 variations of increase RAM request are correctly
predicted, the accuracy is 9/10 = 0.9.
Recall—Recall is the number of correct positive results divided by the number of positive results predicted by the
cognitive service.
For example, for a search query that contains increase RAM, if the system returns 10 results that contain both
both increase and RAM and 8 of those results include the phrase increase RAM, the precision is 8 out of 10. If 20
more instances are related to increase RAM, the recall is 8 out of 30.
Higher recall indicates higher viability of the data sets.
Precision—Precision is the number of correct positive results divided by the total number of relevant samples.
For example, f or a search query that contains increase RAM , the system returns 10 results that contain both
increase and RAM and 8 of those results include the phrase increase RAM. In this case, the precision is 8/ 10 = 0.8.
Higher pr ecision indicates higher viability of the data sets.
F-score—F-score is the harmonic average of precision and recall. F-score reaches its best value at 1 (indicating
perfect precision and recall) and worst at 0.
Traditionally, F-score is calculated as F = 2 × (Precision × Recall) / (Precision + Recall)
Higher precision and recall indicate higher viability of the data sets. For more information about how test metrics are
calculated, see FAQs and additional resources (see page 1012).
Additional information about machine learning metrics
The following blogs provide more information about machine learning metrics and macro versus micro
average of precision. BMC does not endorse the information in these external links. This information provided
in these links should be used for reference purposes only.
GreyAtom Blog, Performance Metrics for Classification problems in Machine Learning. https://medium.
com/greyatom/
Text Mining, Analystics, & More Blog, Computing Precision and Recall for Multi-Class Classification
Problems. http://text-analytics101.rxnlp.com
Data Science Stack Exchange Question and Answer Site, Micro Average vs Macro average Performance
in a Multiclass classification setting. https://datascience.stackexchange.com
Rushdi Shams Blog, Micro and Macro-average of Precision, Recall and F-Score. http://rushdishams.
blogspot.com

Scenario of testing the cognitive service data sets by using CSV file
Scenario: An organization uses BMC Helix Innovation Suite Cognitive Service to automatically route end user service
requests for increasing RAM as Hardware | Component | Memory. As an administrator, you create a CSV data set to train
the cognitive service to auto-categorize this service request to the correct support group. Before implementing, you also
test whether the data set correctly categorizes the service requests.
Example of training data: According to the training data, when an end user requests for increasing RAM, the ticket is
categorized as Hardware | Component | Memory. You want to test the data set to check whether variations of the
request such as increase laptop RAM and increase RAM on network file server are also categorized as Hardware |
Component | Memory. You also specify the percentage of data that must be used for training the cognitive service, for
example, 70%. The CSV file is randomly split into training data and test data according to the specified percentage.
Example of test results: The test results CSV file show that the variation Increase RAM on network file server is
categorized incorrectly as Network | Router | Remote Access Server. The administrator adds more examples of this
variation in the data set so that cognitive service categorizes it correctly.
Maximum amount of test data in a CSV file: After the system automatically splits the CSV file into training data set and
test data set, the limit of the test data is 10,000 rows.
Scenario of testing the cognitive service data sets by using application data
Scenario: Continuing with the above example, an organization uses BMC Helix Innovation Suite Cognitive Service to
automatically categorize the end user requests for increasing RAM as Hardware | Component | Memory. As an
administrator, you want to use application data to train the cognitive service. The Request Service record definition in
your application is used to raise service requests.
Example of training data: The administrator selects the Request Service record definition and the Requester, Summary,
Description, Categorization Tier 1, Categorization Tier 2, and Categorization Tier 3 fields in the record definition from
which data is used to train and test the cognitive service. You also specify the percentage data that must be used for
training the cognitive service, for example, 70%. The application data is randomly split into training data and test data
according to the specified percentage. After testing the application data, a CSV file of the test results is generated.
Example of test results: The test results CSV file show that the variation Increase RAM on network file server is
categorized incorrectly as Network | Router | Remote Access Server. The administrator adds more examples of this
variation in the data set so that the cognitive service categorizes it correctly.
Related topics
Leveraging machine learning metrics to improve chatbot predictability
Types of data sets used to train and test the cognitive service (see page 559)
Training and testing the cognitive service for a custom application (see page 562)
Evaluating the cognitive service test results (see page 567)

Upgrading to a new version of an application with zero downtime

The goal of this use case is to ensure that an application is upgraded to a new version with no impact on the production
environment.
Scenario
Consider a scenario, wherein a customer uses a lunch scheduler application to approve and schedule lunch with clients.
The current version of the application provides only approvals for scheduling lunch.
A developer enhances the application to include the following improvements:
Option for employees to submit lunch expenses.
Ability to Increase the requestor's lunch cost limit.
The developer releases a new version of the application, which the SaaS administrator deploys and activates on the
tenant's production environment. Upgrading to the new version may cause a downtime in the tenant's production
environment, which affects the work while the upgrade continues.
To overcome the challenges posed by the application upgrade, BMC Helix Innovation Suite provides zero downtime
support while upgrading to a new version of an application in the production environment. To test the new version,
administrators can opt in for the new version in their test environment.
By default, only two versions of an application can be deployed on a system. If two versions already exist, the SaaS
administrator undeploys the oldest version (that is not used by any tenants).
The upgrade process

The following video (2:15) gives an overview of the process of upgrading to a new version of an application with zero
downtime:
https://youtu.be/d-Ae2JkKIUE
The following table describes the actions performed by administrators for upgrading to a new version of an application:
Upgrade SaaS Administrator actions Administrator actions Application business

analyst action
Test
(Optional) If two versions of an application are Opts in for the new version. Tests and
environment
deployed, undeploys the version that is not used by validates the
Creates an export package of the
any tenants. updates in the
validated version to copy the changes
new version.
Deploys and activates the new version of an made during tailoring to the production
application. environment.
Production
(Optional) If two versions of an application are Creates an update package of all the None
environment
deployed, undeploys the version that is not used by existing tailoring changes.
any tenants.
Deploys the update package to copy the
Deploys the new version and informs the tenant tailoring changes to the new version
administrator to export all the tailoring changes by before the new version is activated.
creating an export package.

Upgrade SaaS Administrator actions Administrator actions Application business

analyst action
Activates the new version of the application after

allowing sufficient time for the administrators to
create an update package.

SaaS administrator
Administrator
Application business analyst
Benefits
The zero downtime upgrade of an application version ensures t hat there is a minimal disruption to the production
environment. The tasks in the production environment can continue while upgrade continues in the background.

1 As a developer, create and release a new version for a code-based application. Releasing a new version (see page 965)
Or Creating install packages to deploy entire applications (see

page 766)
As a developer, create and release a new version for a codeless application.
2 The SaaS administrator performs the following tasks:
If two versions of an application are deployed on the system, undeploys the oldest version (see page 975).
Activates the new version of an application to make it available for all the tenants.
4 As an administrator, consume the new version of an application. Consuming a new version of an application (see page 779)
5 As an administrator, copy the tailoring changes created on the existing version of the Creating export packages to deploy tailoring changes of
application by creating an update package. applications (see page 775)
Related topic
Guidelines for versioning and undeploying an application (see page 320)
Leveraging full-text search capabilities in your application

BMC Helix Innovation Suite provides the capability to enable full-text search (FTS) in an application. FTS involves indexing
before searching, so that when a user performs a search, only the index is searched instead of the entire text.

The following roles are involved in enabling FTS and performing additional configurations related to FTS:
Application business analyst—Enables FTS on fields in the record definitions so that data in those fields is
searchable by using FTS. Also defines the relevancy of the FTS-enabled fields.
Administrator—Performs additional configurations to enhance the search results.

Benefits of enabling FTS in an application

Enabling FTS in an application has the following benefits that are not present in a standard database search:
Recognizes stem words

FTS can identify stem words and can return the results accordingly. For example, when you search for fire, the
search results will include words such as firewall, backfire, firefighter, firecracker, and so on.
Weighs results
FTS can weigh words according to their relevancy depending on where they appear—in a title, keyword, or the
text that is being searched. Results that match the title can be weighted as more relevant and can be displayed
among the top search results.
Features of full-text search
Full-text search is a keyword-based search.
Fields must be enabled for FTS so that the data in those fields is searchable during FTS.
Supported attachments for FTS:
Adobe PDF
Microsoft Word
HTML
XML
OpenDocument
Electronic publication format (digital books)
RTF
Compression and packaging formation (.zip, .bzip2, .tar, .ar, .cpio)
Unicode
Java class filed and archives (extracts class names and method signatures from Java class files and the .jar
files containing them)
mbox (extracts email messages from the mbox format used by many email archives and UNIX mailboxes)
Image formats (extracts metadata from image formats supported by the java platform)
Audio formats (extracts the lyrics, if present, and any metadata from MP3, MIDI and other simple audio
formats)
Video formats (supports only Flash video format using a simple parsing algorithm)

Enabling full-text search in an application (see page 335)

Automating tasks through emails

BMC Helix Innovation Suite provides the capability to automate certain tasks when an email is received, or send
notifications about certain events by automating outgoing emails This capability eliminates the need for manual
intervention to create tasks after receiving an email, or to manually send an email notification when the task is created or
updated.

Administrator—Configures the incoming or outgoing mailboxes.
Application Business Analyst—Uses the incoming or outgoing mailbox configuration in a rule or a process
according to the business logic.
Process of using incoming mailbox configuration

The incoming mailbox configuration can be used to trigger a rule when an email is received in the configured incoming
mailbox. The rule can be used to run a process, such creating a case.
The following image gives an example of how an incoming mailbox configuration can be used to create a ticket:
The following table describes the tasks that the administrator and application business analyst perform:
Role Task Reference
Administrator Configure the incoming mailbox. Configuring incoming and outgoing email (see
page 750)
This email is shared with the end-users who send their service requests via email.
Application Create a process by using the relevant incoming email fields. Defining the application business logic through
business analyst processes (see page 421)
To map the configured incoming email addresses with the process, the fields from the
configured email can be used in a process. Expression Editor (see page 499)
Application Create a rule by using the System Event type of trigger. Defining a trigger for a rule (see page 495)
Business Analyst
To initiate a rule on receiving an email, the rule must be created by using the Email
Receive Event of the System Event type of trigger.

Process of using outgoing mailbox configuration

The outgoing mailbox configuration can be used to automatically send an email notification or reply to recipients by
email. The outgoing mailbox configuration is used to run a process that contains the Send Message element. For
example, you can use the outgoing mailbox to send an email notification when a case is created.
The following image gives an example of how an outgoing mailbox configuration can be used to send email notification:
The following table describes the tasks that the administrator and application business analyst perform to automate
outgoing emails:
Role Task Reference
Administrator Configure the outgoing mailbox. Configuring incoming and outgoing email
(see page 750)
Emails are sent by using this mailbox.
Administrator (Optional) Create an outgoing email profile for the outgoing mailbox. Configure the outgoing profiles (see page
753)
Administrator Configure the total attachment size and total number of attachments that can be Centralized Tenant Configuration settings
added to the outgoing mail. (see page 757)
Application Business Create a process by configuring the Send Message element with the default outgoing Sending a user message from a process (see
Analyst mailbox details. page 470)
Extendable application definitions to allow additive changes
When you develop an application, you can decide whether you want to allow other developers to customize your
application definitions such as record, view, and association. You can create definitions that can be customizable, non-
customizable, or extendable.

Customizable—Developers can use the customization layer to modify the out-of-the-box definitions in their
application. For more information, see Customization layer (see page 45).
Not customizable—All definitions in the application are locked for customizations.
Extendable—The out-of-the-box definitions are locked for customizations. However, developers can enable them
for extension so that you can add or remove fields in the definitions. Developers can create the following
extension definitions in an extendable application:
Extension record definition—A regular record definition with fields that you want to add to the record
definitions and view definitions that are not customizable.
Extension view definition — A view definition that displays the fields added in the extension record
definition and the fields in view that is not customizable (view that is being extended).
Extension association definition —A direct association between the extension record definition and the
record definition that is not customizable (record definition that is being extended).
Scenario: Enabling extension of definitions

As a developer, you want to create an extendable lunch order application on BMC Helix Innovation Suite so that the out-
of-the-box record definitions and view definitions are not customizable, but can be extended to add or remove objects
such as fields.
You create the following record definitions and view definitions in the lunch order application:
Record Definitions—Restaurant Information and Order Information
View Definitions—Restaurant Information Create, Restaurant Information Edit, Order Information Create, and
Order Information Edit
To make these definitions extendable, you add the Extension Container view component (see page 415) in the view
definitions.
Note
BMC Helix Innovation Suite Foundation view definitions are enabled for extension out-of-the-box.
Scenario: Extending definitions to add or remove objects

Continuing with the earlier scenario, Calbro Services buys the lunch order application. As a developer of Calbro Services,
you want to extend the following record definition and view definitions to add new fields:
Record Definitions—Restaurant Information
View Definitions—Restaurant Information Create, Restaurant Information Edit
New fields—Restaurant Specialty and Restaurant Timings
Process of extending an application

The following figure explains the process of extending an application:

Developers must perform the process of enabling extension and extending the definitions.
Benefits of creating extendable definitions
The out-of-the-box definitions remain unchanged so that the customizations to the application are not lost when
your application or server is upgraded.
Provides capability to make additional changes to the out-of-the-box definitions.
Can easily move the customizations to other environments by creating install packages (see page 766) and
deploying the install packages to other environments (see page 773).

Action Reference
If you want to create extendable definitions in your application Enabling extension of application definitions (see page 415)
If you want to extend the definitions that are enabled for extension Extending BMC Helix Innovation Suite Foundation definitions (see page 704)
Designing a Digital Service Application

When you are preparing to develop a Digital Service application using the BMC Helix Innovation Suite SDK, follow the
best practices and techniques used by development organizations to build any type of application. For example, a user-
centered design, deep understanding of user stories, agile development methodology, use of configuration management
and collaborative requirements and source code management tools.
There are some distinctive aspects of the BMC Helix Innovation Suite SDK that are helpful to understand before
application development. BMC Helix Innovation Suite provides the following powerful built-in capabilities that you can be
use to match the functional requirements:
Business Process Orchestration and Automation
Configurable rule engine
Flexible data model
Codeless UI tailoring
Powerful built-in services
Custom services
Modular deployment

Requirements Analysis
You can use any methodology and tools to identify the requirements. The best practices typically include a complete
understanding of the user requirements and the problems. You can map the user requirements to the business goals of
the application. This can be achieved by a mature design process, informed by research and testing with actual target
users at every phase of the application development.
Identify the following design requirements:
Business process needs and the rules required for the business process
Data entities required to build the application

For example: Number of record definitions and fields required in the records
Users
Number of bundles required
Application bundles
Library bundles
Dependency of bundles
Bundles that need to be deployed together in a package
API design
Transactions
Performance
Sketching solution
The common elements of a solution usually involve identifying user experiences, key data to be tracked, behavior of the
system as the data changes, and tailoring the solution without code changes.
These can be captured as a set of the following design artifacts:
Flow diagrams
A business process flow is a graphical way of representing the behavior of the system, users, and external entities. There
is usually a primary object that is the focus of any business process.
For example:
Process for resolving a request - Depending on the type of request, and different scenarios, the process can involve
notifications, assignments, approvals, manual steps, automated steps, integrations, conditional branching, calling other
processes, and so on.
You can use a flow diagram to describe the process. You may not require to use industry standard notation like BPMN,
but using standard notations can help in defining the process clearly and implementing it using the BMC Helix Innovation
Suite built-in process engine.

Important record and fields

You can make a list of the following points:
Important objects identified (like requests, assets, locations) and their attributes for the process
Common patterns in the data model.
Constraints
You can make a note of the constraints and conditions required for the data model and process.
For example:
Employees below grade 20 should not be assigned an office when they are on-boarded.
HR data is only accessible to employees in the HR organization
You can decide the constraints that you need to allow the users to modify as part of tailoring of the application.
Key user experience

You should identify the user interface elements required for the user interaction, type of interactions, and tailorable
views required for the UI.
Modularity
When you divide the application design in modules, you consider the following points:
Deployment packages in BMC Helix Innovation Suite can contain their own namespaced code, data, and
definitions, and can describe all their dependencies.
If the application design is much complex or contains different functional areas over time, then it is critical to
organize the solution elements so they can be maintained separately over time and the entire solution is as
robust as possible.
To create new solutions with minimal coding, create reusable modules.
Identifying inventory of functionality required

You should have a list of the required functional modules and the types of artifacts that modules describe. You may
prepare a worksheet that includes the functionalities for specific deployment packages and determine if any existing
libraries meet the requirements.
For example:
Package Functional area Leverage existing Custom services New record New business New user interface
libraries definitions logic
Task Management Track task Approval, Outlook connector Task, Task Tracking Custom Task Submit
Library resolution Task Note, Process Client
Notification, Custom @Action for Task Task Part
Routing Task Validation Task Console View,
Assignment, Rules Task Update View
Foundation

Package Functional area Leverage existing Custom services New record New business New user interface
libraries definitions logic
Task API Library REST API for Task Management Task Domain Object
Tasking
Mapping new design objects to the application

Using the inventory, you can decide on the tools required for coding and developing definitions.
For example:
New design object BMC Helix Innovation Suite SDK artifact type Tool
Task Management Library Deployment package and library bundle project Maven archetype
Outlook connector Custom service Eclipse
Custom @Action for Task Routing Custom service
Task, Record definition BMC Helix Innovation Studio
Task Note,
Task Part
Task Tracking Process Process definition BMC Helix Innovation Studio
Task Validation Rules Rule definition BMC Helix Innovation Studio
Custom Task Submit Client Client code Eclipse or favorite IDE for JavaScript. Grunt for debugging
Custom Task Map View Component Client code Eclipse or favorite IDE for JavaScript. Grunt for debugging
Task Console View, View definition BMC Helix Innovation Studio
Task Update View
Task API Library Deployment package and library bundle project Maven archetype
Task REST Domain Object Custom service Eclipse IDE
End-to-end process for developing your Digital Service application

Before you begin with the development of Digital Service application make sure that you install all the components
required to develop an application. BMC Helix Innovation Suite and database are installed in the Amazon Web Services
(AWS) instance.
BMC Helix Innovation Suite provides you the flexibility to develop your application via code based development and
definition based development.
Using BMC Helix Innovation Suite SDK and Maven archetype you can create the project for your application.
Using BMC Helix Innovation Studio, you can create data, business logic and user interface required for your
application.
Using Java and JavaScript you can extend the service objects and customize the behavior of service objects using
Java and JavaScript.

After you complete the application development you can deploy your application to an external environment where the
users can tailor and use the application. The following image describes the recommended end-to-end process for
developing an application:
Navigation tip
Click the steps in the image to go to the detailed topics.
Development of an application comprises of the following tasks:
Task Action Tool
1 Setting up the development environment
2 Creating project and deploying the project for the first time Maven
3 Designing data and creating the data model (creating the data definitions) BMC Helix Innovation
Studio
4 Creating business processes (you can start creating process and rules using BMC Helix Innovation Studio in parallel with BMC Helix Innovation
creating data definitions) Studio

Task Action Tool
5 Creating rules BMC Helix Innovation

Studio
7 Creating the UI for the application (creating views) BMC Helix Innovation
Studio
8 Configuring shell to create the header and navigation for your application BMC Helix Innovation
Studio
9 If required, create custom view components Eclipse
10 If required, add custom service actions (@ Action), custom Data Page Query, custom command, and custom REST Eclipse
resources.
11 Creating development package for the application Maven
Comparison between Developer Studio and BMC Helix Innovation Studio

capabilities
Use this topic to know the comparison of terminologies in Developer Studio and BMC Helix Innovation Studio, and the
details about the capabilities provided in BMC Helix Innovation Studio.
Capability comparison
Capability in Developer Studio Capability in BMC Helix Innovation Studio
Regular Form Record definition
For more information, see 833532273 (see page 297).
Join Form Record definition. Also note that Regular Record Definitions can use inheritance which is an alternative to Joins for
some cases.
Vendor Form No direct equivalent. However, custom Java code can easily be integrated with business logic.
SQL Form No direct equivalent. Use of direct SQL is not supported.
Display Only Form View definition
Form View Record Editor Component within a View. For more information, see 833532273 (see page 297).
Table Field Grid Component within a View
Client Workflow (Active Links, Guides)

Built-in View Behaviors
Action Button Components (open view, refresh, set property, delete record, and more)
Built-in configurable behaviors (Select Group, Conditional Hide, Conditional Disable)
Record Editor value expressions to set initial values
Custom View Components
Can use expressions to bind behavior to other component's values
Server Workflow (Filters, Escalations,

Rule definitions
Guides)
Process definitions

Capability in Developer Studio Capability in BMC Helix Innovation Studio
Associations (mainly for archiving) Association
Search Menu Named list
Setting Form Configuration
Capabilities of record definitions

Following are the capabilities provided by record definitions in BMC Helix Innovation Studio:
Provides a cleaner implementation of records. The fields defined as part of the record definition are truly part of
the record
as defined by the business process and not used to store workflow variables or other information.
Provides easy-to-use interface
Recommends using GUID for Record ID.
Inherit or extend a record definition with and without shared data.
Supports overlays.
Supports export of record data. You can export all or no data to the application bundle.
Inheriting record definitions

BMC Helix Innovation Studio lets you inherit or extend a record definition, and provides the following capabilities:
Lets you inherit record fields, rules, permissions, and associations with or without the shared data.

Shares a single database T table with the shared data.
Structures the record definitions as a class model.
The following illustration provides an example of the fields available in a base record definition, and the fields available in
an inherited or extended record definition. Consider the following items:
The 'Vehicle' record definition is the base record definition, and 'Transport' and 'Automobile' record definitions
are the inherited or extended record definitions.
For shared data, you must always use your own specified field IDs so that they do not clash with the base T table.
In the example, the Vehicle T table.
Although Automobile and Transport are inherited record definitions, the inherited record definitions can have
their own set of unique fields. You can create views, rules, processes, and association definitions that reference
these record definitions.

Packaging data of record definitions

BMC Helix Innovation Studio lets you package data of record definitions by providing the following capabilities:
Lets you package data with an application bundle automatically. The supporting record definitions, such as the
record definitions used in Named Lists, can automatically have all their data included with the Application bundle
deployment process.
Lets you export all or no data to the application bundle.

Applying security labels to record definitions

BMC Helix Innovation Studio lets you apply security labels to record definitions. The security labels make permissions
much easier for all users to understand. Groups are automatically created and assigned to Field ID 1 for row-level
security. This dynamic permission can then be applied to other objects.

Capabilities of view definitions

Following are the capabilities provided by view definitions:
Separates view definition from record definition. The view definition represents the view in Model–view–
controller (MVC) model.
Provides easily-built user interfaces that can present data from multiple record definitions.
Supports creation of view components for any functions or user interface that is required by your business
process.
Supports different modal types, such as centered dialog and fly out blades.
Overlays view to support tailoring.
Replaces the active link workflow with view components and their respective properties.

Components in view definitions

Following are a few of the view components that you can use for building Digital Service application UIs:
View component Function
Action Button Add buttons with actions to your view definitions.
Record editor Edit record data where you pick and choose fields to be displayed
Record grid Display record fields in a tabular format on UI
Containers Control visibility and styling. This is equivalent to panels but not a page holder.
Rich text Add styled text to the view definition.
Associations Display associated data in a grid format based on your defined Association definitions
Extending view components

The application developer can create new or extend existing view components for any advanced UI requirements for
your business process. The view component palette in View designer is designed to be extensible for this purpose.
Capabilities of rule definitions

Following are the capabilities of rule definitions:
Executes the rules by using a variety of triggers that run actions similar to AR workflow.
For example, you can execute the rules after Create, Update, Delete, Merge and Timer Event
Creates the rules for validating and for calling process definitions.
Extends the custom rule actions by creating your own pallet actions
For example, you want to use all the custom data functions available with Oracle DB today. Earlier, the Remedy developer
had to create Select * from Dual type of SQL filter, which was very complex for an application business analyst. In BMC
Helix Innovation Studio, the application developer can create a custom action allowing this function to provide to a
business user.

Capabilities of process definitions

Following are the capabilities of process definitions:
Provides graphical implementation, which makes it easy to build and maintain workflows
Defines process models by using Business Process Model and Notation (BPMN) 2.0 standards.
Provides clean delineation of business process workflow versus other workflows. In contrast, the AR Filter
workflow used to perform process workflow and implement other non-process rules such as validations.
Defines and uses process variables within a process flow. You are not required to create display only fields on
record definitions.
Lets you monitor the processes to track the system health.
Extends process actions by providing simple drag and drop interface for creating easy-to-follow business logic.
You can also create extensible custom process actions for additional features to suit your business requirements.
Insert process variables for inputs and outputs of process actions that can be used by subsequent actions. No
more clutter of the data model with display only fields

Capabilities of associations
Following are the capabilities of associations:
Provides direct and indirect linking of record definitions
Associates records easily using process actions.
Creates associations with descriptors, such as parent of, child of, consists of, part of, and so on.
Automatically create a foreign key on secondary record definition for direct associations.
Automatically capture indirect association data in system record definition.
If a parent record with the Cascade Delete flag set to True is deleted, the child records are automatically deleted.
If a parent record with the Cascade Delete flag set to False is deleted, the child records are not deleted; however,
the foreign key in child records is set to NULL.
Use associations for archival purposes.

Capabilities of named lists

Following are the capabilities of named lists:
Lets you easily design and extend the list.
Provides modern UI for items such as a multi-select menu.
Capabilities of configurations
Following are the capabilities of configurations in BMC Helix Innovation Studio:
Defines a common registry of settings for an application that will be stored in a central key or value repository
with a common user interface so that all settings look and function the same way. This definition of settings
metadata will get bundled with the application so that it can be deployed with the application.

Lets the application developer obtain the settings metadata from AppLocalStorage for consuming the settings.
The metadata can be used as a setting to drive Process workflow and custom client workflow as desired.
Related topic
Navigating BMC Helix Innovation Studio (see page 59)
Best practices
Goal Instructions
Review and understand best practices when developing code of your application Guidelines for code development (see page 307)
Review and understand best practices when customizing your application Guidelines for Digital Service application definitions
customization (see page 313)
Review and understand best practices when specifying scope for the definitions Guidelines to define scope for the definitions (see page 319)
Review and understand best practices when creating custom view components that are Guidelines to create custom view components that are
accessible by the visually impaired accessible (see page 320)
Guidelines for code development

For a shared system, the objective is to write clean service implementation code for BMC Helix Innovation Suite. Once
the application code is developed, the developer can then upload the Digital Service application in a central repository,
called Marketplace, from where other developers can download them for reuse. While the application code is being
uploaded, BMC Helix Innovation Suite verifies whether the application code complies with the development rules and
uploads only the compliant application codes to the Marketplace. The noncompliant application codes are rejected and
are not uploaded to the Marketplace.
This topic lists the rules required for writing Java-based services that are secure, performant, and safe for use on a
shared system. Refer the rules while developing your application code and ensure that the application code complies
with the development rules. The examples provide references to the BMC Helix Innovation Suite API in a few cases.

For example, the BMC Helix Innovation Suite Services must possess the following attributes:
Manage the resources effectively
Avoid being stateful
Avoid blocking
Avoid performing an end-run around the platform architecture
The application rules are defined for the following categories:
Architecture and Design (see page 308)
Supportability (see page 309)
Persistence (see page 309)
Threads and Concurrency (see page 309)
Memory Management (see page 310)
HTTP (see page 312)
Security (see page )
Architecture and Design

Dos Don'ts
Use the core platform services and extend them if needed by using Java Do not introduce new elements to the BMC Helix Innovation Suite container
code that is deployed in a bundle or by using connectors. technology stack that run out of processor start threads, such as the following
elements:
another database
job scheduler
caching framework
Use the standard platform technology stack Do not affect the configuration of the technology stack, such as the Jersey,
Spring, OSGi or Jetty configuration.
Use platform services which are safe for shared systems. Do not write the code in a tenant-agnostic manner. The code does not need to
be aware of the tenant or reference any Tenant ID.
Not available
Do not create any code which would affect other code in some cross-
cutting transparent manner.
Do not use aspects.
Do not write your own servlets, servlet filters, or Jersey filters or

interceptors.
Use HTTP integration to access services that use third-party libraries. Do not include any third party libraries for Java. Use only documented approved
third-party libraries for JavaScript that are already provided with the SDK.
Enhancement requests for the platform to include new functionality.
Can use provided dependencies, without version dependencies, at own

risk
Use Rx APIs to access data on BMC Helix Innovation Suite. It is OK to use

theAR RESTAPI to access data on other Remedy servers as an integration.

Dos Don'ts
Do not use Core AR-API or API-Clients (other than Mid-Tier for

configuration cases). That is, do not use Developer Studio to create
Forms and Workflow.
Do not install or use an older version, to attempt to connect to BMC Helix

Innovation Suite.
Supportability
Dos Don'ts
Code should log all errors appropriately. Debug level logging

Do not handle error conditions without logging them.
should be implemented to
provide sufficient information to troubleshoot problems. Do not log to error level anything which is not an error.
For example, Do not log to info level anything which will cause a large amount of logging and
negatively impact performance.
catch RxException (e) {

ServiceLocator.getLogger().error
("Could not calculate
service values
with " + paramA + ", " + paramB + ":
failed because of " + e.
getLocalizedMessage());
// Handle the error.
}
Persistence
Dos Don'ts
Use the Record Service, including Attachment Fields, or HTTP-based Do not use the file system
integration
Example:
Do not read or write from File I/O streams, for resources, configuration, or any other
purpose.
// DON'T DO THIS
BufferedReader br = new BufferedReader(new FileReader
(FILENAME));
while ((sCurrentLine = br.readLine()) != null) {
// do something with sCurrentLine
}
Threads and Concurrency

Dos Don'ts
Use Time-Based Rules to trigger workflow in the background. Do not start threads.
For example, do not implement Runnable to start in a thread
(new Thread(new MyRunnable())).start();

Dos Don'ts
Also do not extend the thread as follows:
public class HelloThread extends Thread { .. .

. }
Consider how using the Process Service can help synchronize activities without Do not use thread synchronization mechanisms, such as sleep or the
writing this as Java code. synchronized keyword. In fact, do not interact with threading APIs for
any other reason.
Do not use the synchronized keyword, or sleep() your current thread.
public class SynchronizedCounter {

private int c = 0;
public synchronized void increment() {
c++;
}
public int getCount() { return c; }
}
Avoid code that can take a long time to execute. Instead, break long background Do not block threads on any long-running operation.
processing into smaller actions or processes. Each one can be started by a time-
As some examples, avoid nested loops where the number of iterations is
based rule, so they can be configured to run in parallel.
unknown in advance. Additionally, do not block a thread waiting a long
time on a response from a network resource.
solveTravellingSalesmanProblem();
Use BMC Integration Service to integrate with any third-party systems outside of Do not make any network calls.
Memory Management
Dos Dont's
Store tenant-specific information persistently by using Records and Associations or use the platform- Do not allow information to be shared across
provided Cache Service. threads or client requests. The code should be
written such that it is stateless.
For example:
Do store data in static variables.
Do not create a data caching mechanism.
Do not create member variables for services

or JAX-RS resources.
Do not store information in members of your Service

or JAX-RS resource as displayed in the following
example:
public class MyService implements

Service {
// DO NOT do this - static

variable may leak across tenants

Dos Dont's
private static int lastRate =

0;
// DO NOT do this - A member

variable which implements a cache.
private Map rateCache;
public MyService() {
rateCache = new HashMap();
}
/**
* A service action
*/
@Action
public Integer computeCost(
@ActionParameter(name = "i
d") @NotBlank @NotNull String id,
@ActionParameter(name = "h
ours") @NotBlank @NotNull int
hours,
@ActionParameter(name = "r
ate") @NotBlank @NotNull int
rate ) {
if (lastRate != rate) {
// DO NOT do this -
this can leak between tenants
lastRate = rate;
ServiceLocator.
getLogger().info("rate has
changed from " + lastRate + " to "
+ rate);
}
// DO NOT do this -
information may leak across
tenants
Integer cost = rateCache.
get(id);
if (cost == null) {
cost = hours * rate;
rateCache.put(id,
cost);
}
return cost;
}
}
Use DataPageQuery pattern Do not minimize the loading of large amounts of data
into memory.
Requests for data should be chunked using the DataPageQuery pattern (or some other pattern that
supports pagination). Furthermore, the processing of data in preparing the response should use
RecordInstanceDataPageQuery. Avoid processing an arbitrary amount of data in a single request.
// Get a chunk of data (error handling not shown here)

DataPageQueryParameters params = new DataPageQueryParameters(50,
0, propertySelections, null, queryPredicatesByName);
DataPage result = ServiceLocator.getRecordService().
getRecordInstancesByIdDataPage(params);

Dos Dont's
// Process the chunk

List<?> records = result.getData();
List<ResultInfo> resultList = new LinkedList<ResultInfo>();
for (Object record : records){
// Construct the object to be returned.
String id = (String)mappedRecord.get(ID);
resultList.add(new ResultInfo( (HashMap<String, Object>)
record );
}
// Return the chunk of data

return new DataPage(resultList.size(), resultList);
Use the Record Service to persist data between calls Do not interact with thread local storage.
Thread local storage is just as bad as using a static

variable. That is because threads are not allocated to
a particular tenant and must not share any state.
public class MyService implements

Service {
// DO NOT use ThreadLocal.

private ThreadLocal someData;
public MyService() {
someData = new
ThreadLocal();
}
// Something that updates

thread storage.
// DO NOT do this. Can
interfere with other tenants.
@Action
public void setData(@ActionPar
ameter(name = "data") @NotBlank @N
otNull String data) {
someData.set(data);
// Something that accesses

thread storage.
// DO NOT do this. Can expose
data from other tenants.
@Action
public String getData() {
return (String) someData.
get();
}
}
HTTP
Dos Dont's
Use standard, supported JAX/RS techniques for custom REST interfaces

Dos Dont's
Follow the standard syntax as shown in the samples

and tutorial.
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import com.bmc.arsys.rx.services.
common.RestfulResource;
@Path("example/myresource")
public class MyResource implements
RestfulResource {
@GET
@Path("/{id}")
public String get(@PathParam("i
d") String id) {
// Do some processing with

id.
String result =
something();
return result;
}
}
Deploy services as application or library bundles Do not include additional servlet containers or legacy Mid-tier HTTP services, by configuration
changes or any other method.
Security
Dos Dont's
Use the platform permissions constructs Do not create your own permission enforcement mechanism.
For example, do not attempt to parse group lists and implement a new model.
Use the security context provided by the platform Do not attempt authorization impersonation or any other changes to any security context.
Guidelines for Digital Service application definitions customization

This topic lists the guidelines for making the definitions available for customization. You must follow these rules when
you develop a new Digital Service application or when upgrade your existing application (for example, upgrade of
application version 1.0 to application version 1.1).
The users of your application may want to customize the application definitions as per their requirements. You can make
your application definitions available for customization for the users.
By default, record definitions, view definitions, process definitions, rule definitions, named list definitions, and
association definitions are not customizable. However, you can configure these elements and make them
available for customization.
Your application users can only customize the definitions that you enable for customization.

You can enable the customization of definitions through designers in BMC Helix Innovation Studio, by using the
Scope/Customization options. For example, you can make the record definition available for customization by
using the record designer. For more information, see Making definitions available for customization (see page 515
).
Configuration settings and the data exported or deployed with the application (bundle data) are always
customizable. There is no option available in BMC Helix Innovation Studio to disable the customization of these
definitions.
Guidelines to allow customization of definitions

The information in the following table helps you decide when to allow or not allow customization of definitions, when
you are developing a new application.
Definition Allow customization of definitions when... Do not allow customization of definitions when...
Record You want to allow users to add fields.

You do not want your users to modify the record
definition
definitions. For example, record definitions that are not
user facing.
You do not want your users to modify the record

definitions or you need to modify the definitions in the
later versions of the application.
Field You want to allow users to modify properties of the field such as Label, Use You do not want your users to modify the fields. For example,
in Global Search, and so on. the fields of a record definition that are not user facing.
View
Users need to modify a view definition. For example, to allow the You do not want your users to modify the view
definition
users to add fields and display the fields in an existing view definitions or you need to modify the definitions in the
definition. later versions of the application. For more information,
see 834635850 (see page 313).
You do not want to modify the view definition in the later versions
of the application. For more information, see 834635850 (see page
313)
Process A process definition that helps users to get started and the users want to
You do not want your users to modify the process
definition modify the process. You must consider the business logic factors of the
definitions
process definition and decide if you can provide the process definition for
customization. You need to modify the definitions in later versions of
the application. For more information, see 834635850
(see page 313).
The process definitions are complex and updating the

definitions may affect the functionality of the
application.
The process definition organizes other processes.
Rule A rule definition that enforces a business constraint or triggers a process.

A rule definition is used to implement the execution of
definition
your application logic
Named List User can always customize the named list definitions.
definition
Configuration User can always customize the configuration settings. x

Setting
Association User can always customize the named list definitions.

definition

Definition Allow customization of definitions when... Do not allow customization of definitions when...
Bundle data User can always customize the named list definitions. x
Guidelines to handle the upgrade of customizable definitions

The following table provides information on how to handle the upgrade of customizable definitions, when you are
upgrading your application to a new version:
Definition Handling upgrade of a customizable definition Handling upgrade of a non customizable

definition
Record You must avoid updating a customizable record definition. If you update a customizable You can modify a non customizable
definition definition, ensure that you follow the following guidelines: record definition. Ensure that you follow
the following guidelines:
Do not delete fields in the record definition.
Do not delete fields in the record
Do not modify the record definition properties that affect other definitions.
definition.
Do not modify the record definitions in such a way that the functionality of the
Do not modify the record
application is affected.
definition properties that affect
Ensure that your application works with the earlier definitions and the modified other definitions.
definitions. If the users customize the definitions, your changes are hidden.
Field You must avoid updating a customizable field. If you update a customizable field, ensure that You can modify a non customizable field.
you follow the following guidelines: Ensure that you follow the following
guidelines:
Do not delete fields.
Do not delete fields.
Do not modify the field properties that affect other definitions.
Do not modify the field properties
Ensure that your application works with the earlier definitions and the modified
that affect other definitions.
definitions. If the users customize the definitions, your changes are hidden.
View You must avoid updating a customizable view definition. Instead of updating a customizable You can modify a non customizable view
definition view definition, you can provide new definitions. definition. Ensure that you do not modify
the required input parameters and output
parameters.
Process You must avoid updating a customizable process definition. Instead of updating a customizable You can modify a non customizable
definition process definition, you can create a new process definition. If you modify a process definition process definition. Ensure that you do not
and the definition is customized by the users, your changes are hidden and can affect the modify the required input parameters and
working of the application. output parameters.
Rule You must avoid updating a customizable rule definition. Instead of updating a customizable rule You can modify a non customizable rule.
definition definition, you can create a new rule definition. If you modify a rule definition and the definition
is customized by the users, your changes are hidden and can affect the working of the
application.
Named List You must avoid updating a named list definition. Instead of updating a named list definition, you
definition can create a new named list definition. If you modify a named list definition and the definition is
customized by the users, your changes are hidden and can affect the working of the application.
Configuration You must not update the existing configuration settings. Instead of updating the existing x
setting configuration settings, you can create new configuration settings.
If you modify a configuration setting, the configuration setting used by the users are also
overwritten.
Association You must not update the existing association definitions.

definition
You can only modify the description of an association definition.

Definition Handling upgrade of a customizable definition Handling upgrade of a non customizable

definition
Instead of updating an association definition, you can create a new association

definition and disable the definition. The users can enable the definition when they want
to use the definition.
If you modify an association definition and the users customize the definitions, your
changes are hidden. This can affect the working of the application.
Bundle data You must not modify the data that is deployed with your bundle other than sample data. If you x
modify the bundle data, the bundle data used by the users is also overwritten.
Guidelines to upgrade an application

When you upgrade your application to a new version, ensure that the modifications to the application do not affect the
functionalities of the existing application version. The following table lists the guidelines to follow:
Guideline Description
Add new functionality that is implemented using You can create a new functionality for your application by creating the following new definitions and
new definitions new code modules:
Record definitions and record definitions that extend Foundation record definitions
View definitions and view components
Process definitions
Java based services, data page queries, commands, and REST resources
Specific rule definitions
Roles
Configuration settings
Bundle data
Exception
You must not create new rule definitions.
Your application code changes must be backward When you update your application code, ensure that you follow the following guidelines:
compatible
View components
You can add new properties that are not mandatory.
You must not change any JavaScript method that is user facing.
You must provide opt in consumption of the UI changes by adding configuration settings in
your application.
Java based services
You must not delete the existing interfaces.
You must not add new mandatory parameters.
You must not modify a service that can affect the application configuration.
You must not modify customizable definitions You must not modify the customizable definitions because you do not know the changes made by the
users and you cannot merge the definition changes made by the users .
Exception

You can make the following changes in a customizable record definition:
Add new custom fields
Add permissions to roles
Add new custom indexes
Modify the Should Export Data option
Modify the Global Search Title field
Add new security labels
Modify the Allow Non Admins to Delete Records setting
Change the description text of the definition
Ensure that you do not delete permissions, indexes, and security labels of a customizable
record definition.
You can make the following changes in a customizable field:
Add permissions to roles
Modify field name
Modify a text field to add a named list definition
Enable or disable Full Text Search
Add new options to selection fields
Modify the field description
Ensure that you do not make the following changes to a field:
Delete permissions
Change optional field to required field
Disable Allow any user to submit property
Modify the Encrypted property
Modify the Store Hashed property
Delete selection field options or modify the numeric values of the selection field
Your existing non customizable definitions changes When you update the non customizable definitions of your application, ensure that you follow the
must be backward compatible following guidelines:
Record definitions
Do not delete record definition or fields
Do not change the field ID values
View definitions
You can add parameters
You can add or delete view components
You modify the view component properties
You modify the visual interface
Process definitions
You add optional parameters
Before you delete process activities, ensure that the activities are not used process instances.
Before you modify properties of a process activity, ensure that are dependent on other
definitions such as rule definition and process definitions.

You must not delete a User Task or a Receive Task.
If you add new activities, your process logic should must consider the activity results as
optional.
Rule definitions
You must not add new rule definitions
You must not modify the existing rule definitions that directly interact with business logic.
You can modify the rule definitions that are independent on other definitions and do not affect
application data and definitions.
You must not modify the existing definitions and Ensure that you follow the following guideline when you update the definitions and data that can be
data that can be customized all the times customized all the times:
You must not delete or modify the existing named list definitions
You modify specific named list definitions that do not affect the users
Do not modify or delete the existing association definitions
Roles
Do not modify or delete the existing roles
Configuration settings
Do not modify or delete the existing configuration settings
Bundle data
Before you delete bundle data, ensure that the bundle data is independent on the customizable
definitions.
Guidelines to make a new version of an application available for user

When you develop a new version of your application, you should consider the effort level required to consume the
features. You can make the users of your application to consume the new features or the changes in your application in
the following ways:
Automatic consumption
You may enhance your application in such a way that the users do not need to perform any steps to enable the new
features.
Opt in consumption
You can add a configuration setting to enable a new feature in your application and by default, disable the setting. When
a user wants to use the new feature, the user can enable the setting by using the Administration tab in BMC Helix
Innovation Studio. Typically, such a setting is enabled by an administrator and then the setting is visible to the users. For
example, changes in the behavior of view components.
Customization consumption
When you cannot add a configuration setting to enable a new feature in your application, you can provide instructions to
the users about how to consume features. The users such as application business analysts or administrators can follow
your instructions and the developer users can consume the new feature by the means of code changes.

For example, your new feature may consist of the following new objects:
New view components or properties of view components.
New view definitions that can be enabled by configuring the shell.
New @Action interfaces that can be used in configurable processes.
Guidelines to define scope for the definitions

This topic lists the guidelines for defining scope (see page 43) for the definitions available in BMC Helix Innovation
Suite. You must follow these guidelines when you create or modify a definition in a Digital Service application or library.
Guidelines to define scope for definitions

The information in the following table helps you to decide when to define the scope for the definitions.
Definition To be used when...

Scope
Application
You want to limit the usage of your definitions within an application or library.
/Library
You need to modify the definitions in the later versions of the BMC Helix Innovation Suite application without affecting any other
applications.
You do not want users to customize the definitions.
Public
You want other applications or libraries to use these definitions.
You do not need to modify the definitions in the later versions of the BMC Helix Innovation Suite application.
You want users to customize the definitions.

Note: BMC recommends that if you allow customizations for the definitions, ensure that you do not modify the definitions in the
future versions.
Guidelines to change the scope of the definition

The information in the following section helps you to decide when to change the scope of the definition:
You can always change the scope of the definition from Application/Library to Public.
After you release your application or library, ensure that you do not change the scope of the released Public
definitions in the next version of your application or library.
If you have not released your application or library, you can change the scope of a definition from Public to
Application/Library. However, in this case you must export and redeploy the application (or library) and any other
dependent application (or library) after the development to ensure:
No other definitions outside the deployed application or library have used the Application/Library scoped
definitions. The deployment fails, if the Application/Library scoped definitions are used by definitions
outside the deployed application/library.
Customization option is set to "Not allowed" for all the Public scope definitions that used definitions for
which you changed the scope from Public to Application/Library.

Guidelines for versioning and undeploying an application

This topic lists the guidelines for creating, consuming, and undeploying specific versions of an application. Before you
create and release a new version for your application, ensure that you follow the guidelines for creating a new version.
By default only two versions of an application can be deployed on a system. If you deploy a third version, the
following error is generated:
9164: Maximum number of allowed versions exceeded. The SaaS administrator must undeploy the oldest
version. If the latest version is undeployed, all versions of the application are undeployed from the system.
The application versions are distinguished by the bundle project version provided during creation of the Maven
project.
New versions of an application are created by using the Maven archetype. The application version is specified by
using the following format:
<major version>.<minor version>.<incremental version>-<qualifier>
For example, 17.11.0, 17.11.0-SNAPSHOT, 1.0-SNAPSHOT, 1.0.0.RELEASE
BMC Helix Innovation Suite uses major version, minor version, and incremental version parameters for
versioning an application.
When you change the major version or minor version parameter in an application version, a new version of
your application is created.
When you change the incremental version parameter in an application version, the existing version of your
application is updated.
Related topic
Releasing a version of your bundle (see page 965)
Guidelines to create accessible custom view components

You must follow the following best practices for creating custom view components that are accessible by the visually
impaired and are Section 508 compliant :
Ensure that every interactive element in a view component is focusable and accessible from the keyboard.
To comply with WAI-ARIA 1.1 specifications to improve interoperability with assistive technologies, perform the
following actions:
Add proper ARIA labels to elements that do not have text representation. For example, a button with
an X symbol that closes a dialog box or a calendar icon.
Add appropriate ARIA and role attributes while creating your own interactive form elements, such as
checkboxes, selects, and so on.
Add descriptive labels to all form inputs and placeholders.

Avoid using any HTML tags except for <a> with correct ng-href attribute for creating navigation links and for
<button> for creating interactive button elements .
However, if you are adding HTML tags , add proper ARIA and role attributes to allow screen readers to identify
such elements. Add descriptive alt attributes for <img> tags.
Avoid hover events in your event listeners as those are triggered only by using a mouse.
Avoid using only color for identifying interactive elements.
Related topics
Creating a custom user interface with AngularJS (see page 826)
Onboarding
After you subscribe to BMC Helix Innovation Suite, BMC sends you the details of the systems configured for you through
an email.
The out-of-the-box setup does not include any data, and therefore administrators must perform a few steps to set up
their BMC Helix Innovation Suite environment. You can tailor the environment according to your organizational
requirements.
The following figure provides an overview of the process:
The following table provides a logical sequence to set up your BMC Helix Innovation Suite environment:
BMC - Configure product activation
1 Share system access details and user credentials. BMC sends you an activation email that contains environment details and system
information like login URL and administrator credentials. You are provided with three
separate setup environments as follows:
Tailoring environment—Used to customize the out-of-the-box applications.
QA environment—Used to test the custom applications before they are

released to production environment.
Production environment—Used to deploy the application to the

environment, such that it is available to all users in the organization.
Note

Out-of-the-box Remedy Single Sign-On is configured to use the user

accounts within a BMC Remedy AR System server for authentication.
However, if you are using SAML-based authentication within your

organization and want to configure Remedy SSO to use that for
authentication, you must submit a request to BMC Support for the
Remedy SSO configuration with SAML.
Administrator - Perform basic configurations
1 Configure Remedy Single Sign-On to authenticate BMC Helix Enabling Remedy SSO OAuth 2.0 authentication for your application (see page 976)
Innovation Suite users through a SAML authentication.
2 Set up Foundation data by using any of the following Setting up Foundation data for custom applications (see page 641)
methods:
Create Foundation data one at a time
Load the Foundation data in bulk quantities
Load existing Foundation data from BMC Remedy IT

Service Management to BMC Helix Innovation Suite
3 Set up user accounts and grant access to manage and Managing user access and permissions (see page 742)
maintain the system.
Developer - Develop the applications
1 Create a code-based application by using BMC Helix

Developing and deploying code-based applications (see page 798)
Innovation Suite SDK, BMC Helix Innovation Studio, and
Maven archetypes. Alternatively, you can create a codeless Developing codeless applications (see page 794)
application by using BMC Helix Innovation Studio.
Related topics
Getting started (see page 29)
Developing applications (see page 794)
Tailoring applications (see page 322)
Administering (see page 632)
Tailoring applications
As an application business analyst, you can tailor a Digital Service application that is deployed in BMC Helix Innovation
Studio. For example, a developer deployed an application to onboard new hires that requires employee details such as
first name, last name, employee ID, and so on. The application mostly meets your requirements; however, your
organization wants to start tracking employee assets and employee skills as part of the onboarding process. In BMC Helix
Innovation Studio, by using the same development tool, an application business analyst can customize the onboarding
application record definitions and add the fields to the employee details.
Perform the following tasks to tailor an application:

Action Reference
Modify the application data model by creating, editing, or deleting the record definitions and named list Defining record definitions to store and manage
definitions in the Record designer and Named list designer. data (see page 324)
Change the application interface by modifying the view definition elements in the View designer. Defining the user interface through view
definitions (see page 376)
Modify the business process model (application business logic) in the Process designer. Defining the application business logic through
processes (see page 421)
Change the business rules (interactions with business processes) by editing the business rules in the Rule Adding rules to validate data or trigger events in
designer. a process (see page 490)
Design a special configurable view by using BMC Modern Shell. Creating and customizing application views by
using Shell (see page 519)
Related topic
Navigating BMC Helix Innovation Studio (see page 59)
Creating the definitions for a tailorable Digital Service application

In BMC Helix Innovation Studio you can create definitions (data, user interface, and business logic) required for
applications using the various available designers.
Definitions play an important role in making your application tailorable. Using definitions, you can develop an application
that can be customized without coding. After a developer develops and deploys an application, a persona like an
application business analyst can customize the application by modifying definitions of the application using BMC Helix
Innovation Studio.
You must consider the following points when you create definitions for your application:
As a developer, you must decide whether you want to create customizable, non customizable, or extendable
definitions in the your applications.
The following video (6:52) helps you to customize the application by modifying the definitions on the application using
BMC Helix Innovation Studio.
https://youtu.be/bVvcC6IKaLA
Application business analysts can customize the objects developed in their own applications, if the objects are
marked as customizable by the developer. Application business analysts cannot customize the objects developed
in com.bmc.arsys. For example, objects in core BMC applications like Foundation, Approval, and Assignment
cannot be customized.
This section provides information about how you can create definitions and use them in your application.
Action Reference
Create or modify a record definition for an application. Defining record definitions to store and manage data (see
page 324)
Create or modify a view definition for an application. Defining the user interface through view definitions (see page
376)

Action Reference
Create or modify a named list for an application. Facilitating data entry through named lists (see page 417)
Create or modify a process for an application. Defining the application business logic through processes (see
page 421)
Create or modify a rule for an application. Adding rules to validate data or trigger events in a process (see
page 490)
Understand the Expression Editor available in the View designer, Process designer, and Rule Expression Editor (see page 499)
designer.
Design a special configurable view for an application. Creating and customizing application views by using Shell (see
page 519)
Create or modify a configuration or setting for an application. Creating configurations for your Digital Service application
(see page 505)
Make a definition available for customization so that an application business analyst can Making definitions available for customization (see page 515)
customize the definition.
Switch from one customization layer to the other customization layer from the BMC Helix Accessing customization layers from BMC Helix Innovation
Innovation Studio. Studio
Defining record definitions to store and manage data

A record definition is a collection of the data required for building the application for your business process. A record
definition is made up of specific record fields. For example, a task can be stored as a record definition.
Note
Business analysts can customize the objects developed in their own applications and that are marked
customizable by the developers, but cannot customize the objects developed in com.bmc.arsys. For example,
objects in core BMC applications like Foundation, Approval, and Assignment cannot be customized.

Goal Instruction
Understand the concepts related to a record definition and a record field, and types of record Record definition concepts (see page 325)
definitions.
Create a regular record definition. Creating or modifying regular record definitions

(see page 329)
Create a join record definition. Creating join record definitions (see page 340)
Inherit or extend an existing record definition to a new record definition. Inheriting an existing record definition to a new
record definition (see page 338)
Modify record definitions to add or update record fields, permissions, or record indexes or include Modifying record definitions (see page 329)
record data with the bundle.
Define a relationship between the record definitions. Creating record associations (see page 342)
Encrypt or hide the field data. Securing text fields (see page 373)
Create record instances. Creating record instances (see page 346)

Goal Instruction
Enable auditing of record definitions. Enabling record auditing (see page 351)
Create hierarchical groups by using security labels. Creating hierarchical groups through security labels
(see page 360)
Customize the record definitions, view definitions, process definitions, rule definitions, named list Customizing definitions
definitions, and association definitions created for an application.
Use shell to: Creating and customizing application views by using

Shell (see page 519)
create the application UI having navigation bar without writing code
customize the list of navigational links and the list of actions
provide permissions to views
Record definition concepts

This topic provides information about the concepts related to a record definition and a record field, and types of record
definitions.
Record definition concepts

The following table lists the concepts in a record definition:
Term Description Example
Record or A record definition is a collection of the data required for building the A task can be stored as a record definition.
record application for your business process. A record definition is made up of
definition specific record fields.
Record field A unit of information that collectively forms a record definition. A single The task record definition can consist of the following fields:
record definition consists of multiple fields, and each field has one or
Task ID
multiple attributes.
Assignee
Description
Submitter
Status
Due date
Record The data created by the application for which the structure of the data is The task fields can consist of the following record instances:
instance specified by the record definition.
Assigned to: Seth
Priority: Critical
Index In a record definition, an index is a list of record fields that are frequently A record definition for a task can consist of the following index
searched. Indexes reduce the database search time and optimize the entries:
performance of your Digital Service application by returning search
Status
results faster.
You can index the fields that users frequently search for. However, you Created Date
should use indexes carefully because adding too many indexes to a single
record definition may lead to performance degradation.
Customization As is the case with most kinds of Definitions, a developer can control The developer only allows Status and Description to be
whether the record definition is customizable after it is deployed to a customized. Permissions can be customized for all fields.
production environment. This is controlled at the level of the entire
record definition, or if desired, for individual fields. Also the developer
can permit only permissions to be customized but nothing else.

Term Description Example
Permissions Access to the record definition itself, or individual fields, can be The developer restricts access to a Salary field to users whose
restricted to a list of Roles (these are created in the Administration tab group is mapped to the HR role.
of BMC Helix Innovation Studio). There is also a special group called
Public that be assigned if the field is open to anyone.
Administrators map these Roles into actual Groups of real users after
deployment.
Security This is another kind of permission control, but works on individual record There is a Cost field. It is given a Security Label called
Labels instances so they are dynamically assigned at runtime. The Security Label AccountingSensitive. At runtime, this Security Label is applied
implies a relationship with one or more Groups or Roles. Only users who only if this particular record meets guidelines that make it
have that relationship will be able to view or modify the record instances. significant to the Accounting Department. At runtime, only such
records are visible to members of the Accounting Department.
Specifying the Security Label in the record definition is not enough to
give access. Rules must be created to set or remove the labels from
specific record instances at runtime.
Inherit from a If desired, the record definition can automatically inherit all the fields Request inherits from Ticket. All the fields from Ticket are
Record from another record definition. You can then choose whether to also implicitly there as part of Request. If a new field is later added to
Definition inherit core fields, Rule bindings, Field Permissions, and Associations. Ticket, it automatically shows up as part of Request.
Share Data If selected, this option means that any other record definitions that Location is set to "share data with inheritors". Site, inherits from
with inherit from this one will store their data in the same database table as Location but adds the field SiteID. Therefore if you query
Inheritors this one. This means that a query for these Records will return the Location you will see all the Locations including all the Sites, but
inheriting records also (though not their particular fields, just the you will not see any site-specific data such as SiteID.
common ones).
If this is not set, then the fields are inherited but the data is stored in a
separate database table and there is no way to query them together.
Abstract This means that the record definition only exists for purposes of Ticket is an abstraction to define the shared fields of Incident,
inheritance. Actual record instances should never be created. Problem, and Change. We don't want actual Ticket record
instances created so we make it Abstract.
Final This means that new record definitions cannot inherit from this one. The extended business logic requires that there be no further
extension of the Change record definition, so we lock out
further inheritance here.
Exporting This means that when a developer exports the bundle definitions in order We create a record definition to store the names of processes
Data to create a Deployment Package, all record instances of this definition to be invoked from a Named List. Since we ship these processes
are exported along with it. When it is deployed to a production with the application, we should specify that the data be included
environment, the records are imported and replicated for all tenants with the Deployment Package as well.
currently existing on the production environment.
Typically this is NOT used for operational data, such as Incidents or

Tasks. It is generally used for data which is used for configuration
purposes, such as data used for Named Lists.
Allowing Typically, only administrators should actually delete data. This setting There is some frequently generated data that users can
Users to enforces this globally for all records of this definition. completely clean up if they choose to, so we set this option to
Delete be True.
Record field concepts

Term Description
Type Fields come in different types, and some of the properties of the types vary. For example, number fields have a min and max value. Character
fields can have a Named List assigned to them, and can be encrypted. Selection fields have a list of enumerated values. The Record designer
UI indicates which properties are appropriate for each type.
Customization If the record definition itself is customizable (see above), then the developer can further specify which fields are. Also the developer can
permit only permissions to be customized but nothing else.

Types of record definitions

A record definition can be of two types: regular record and join record.
Regular record (see page 327)
Join record (see page 327)
Inner join record (see page 327)
Outer join record (see page 328)
Regular record
A regular record is a record definition that is not a combination of multiple record definitions.
Join record
A join record definition is a combination of data that is retrieved from multiple record definitions. Join record definitions
are similar to database joins.
With join records, you can perform the following operations:
Retrieve data from multiple record definitions.
Specify the criteria for retrieving data from multiple record definitions.
View or edit record fields of multiple record definitions at the same time.
Join records are further divided into inner join records and outer join records.
Inner join record

This type of join record combines only the matching data from multiple record definitions. An inner join searches for
fields that have corresponding values in the multiple records and then combines the matching data to form a join record.
If a field does not have a corresponding value in any of the records, that field is omitted from the join record.
Example of an inner join:
The following image illustrates the concept of an inner join. In the example, the Library Catalog form is the primary
record, and the Customer Checkout form is the secondary record. The join criteria is the International Standard
Book Number (ISBN).

An inner join creates a record that contains only the entries in which the join criteria exists in both the primary and
secondary records. The join record produces a report that shows only the titles that are checked out.
Outer join record

This type of join record combines all the fields from a record definition that is marked as primary, even if the fields do
not have a corresponding value in a record definition that is marked as secondary. To see all submitted help requests,
including those that have no specific employee information connected with them, you can create an outer join.
Example of an outer join:
The following image illustrates the concept of an outer join. In the example, the Library Catalog form is the primary
record, and the Customer Checkout form is the secondary record. The join criteria is the International Standard
Book Number (ISBN).
An outer join creates a record that includes a comprehensive listing of all the catalog items from the primary
record even if there is no corresponding data in the secondary record.

Creating or modifying regular record definitions

A regular record definition is an entity that can store the information for your business processes. For example, if you
have an on-boarding process for new hires, you require employee details such as first name, last name, employee ID, and
so on in the process. These details are stores a regular record definition.
You can create a new record definition or edit an existing record definition.
Before you begin

Ensure that you have created a project and deployed it in BMC Helix Innovation Studio. For more information, see
Creating a Project using Maven and the Archetype (see page 806).
Note
Application business analysts can customize the objects developed in their own applications and that are
marked customizable by the developers, but cannot customize the objects developed in com.bmc.arsys. For
example, objects in core BMC applications like Foundation, Approval, and Assignment cannot be customized.
To create a regular record definition
The following video helps you to create a record definition:
https://youtu.be/-QWpuvC4hNs
2. Select the application for which you want to create a record definition.
3. Select Records > New > Regular Record.

An empty record with default fields is displayed. To create a join record, see Creating join records (see page 340).
4. In the Details section, in General Properties, enter the record definition name.
The record definition name must start with an alphanumeric character. Only alphanumeric characters, hyphens,
dashes and spaces are allowed in the record definition name.
5. Perform any of the following tasks:

Task Description
Add fields (see page 330) to a (Mandatory) Add fields to the record definition according to the organization's requirement.
record definition
Update the existing fields (see Modify the details of the existing record fields.
page 331) of a record definition
Add permissions (see page 331) By default, a record definition is visible only to the administrators. To provide access to a record definition for
to a record definition other users, you must add permissions to a specific group or a role.
Add an index (see page 332) to a Add indexes to the most important fields in the record definition. The indexes return the search results faster
record definition for the fields, and optimize the performance of your application.
Define a scope (see page 329) Limit the use of the record definition within the same application or library, or enable the record definition to
for the record definition be used by all the applications or libraries.

Task Description
Export record data (see page 333 Enable automatic export of the record data when the library or application is packed in a bundle for
) with a bundle deployment.
Associate fields (see page 333) Associate fields to record definitions, so that during runtime the associated field values are displayed instead of
for a record definition GUID values.
Copy fields (see page 334) in a Copy custom fields from a regular record to the same record.
record definition
6. Click Save to create the record definition.
To add fields to a record definition
1. Add fields to a record definition, by performing the following steps:
a. Click New field and select the required datatype for the field.
b. In the Details section, enter the field name and provide additional details for the field, such as the
following information:
Name: Enter the name of the record field.
Description: Provide the description for the record field.
Required: Select to mark the field as required for the record definition.
Allow anyone to submit: Select to allow any user to submit new requests.
Notes
When you add a text field, you must provide the field length in characters and
not in bytes. The default length is 254 characters.
Text fields with more than 1000 characters in a record definition are converted
into Character Large Object (CLOB) field after saving the record definition for
Oracle.
In BMC Helix Innovation Studio, all field lengths for record definitions have the
same magnitude but with character units instead of byte units, except for the
following fields which remain byte semantics:
1 = field ID CORE_ENTRY_ID
179 = GUID
379 = RECORD_ID
Field ID range specifies the limit for values that you can assign (or is assigned
automatically if you do not assign any value) to the Field ID. You can assign the
value to Field ID within the Field ID range. You cannot assign the lower limit
value of the Field ID Range to a field. For example, if Field ID Range is 1000:
2000, the minimum value that you can assign to a Field ID is 1001.

c. Save the field.
Important
The Option Name parameter used in the Selection field is no longer supported. The Selection
field only supports Option Value parameter. If your record definition uses the Option Name
parameter and you upgrade your application to BMC Helix Innovation Suite SDK 17.8.0, ensure
that you change the Option Name to Option Value.
To update the record fields
1. Select the field in the record definition.
2. In the Details section, modify the field details.
3. Save the changes.
To add permissions to a record definition
The following video describes the procedure to add permissions

to access a record definition or a view definition:
https://youtu.be/y0UEfO4PKJU
By default, a record definition is visible only to the administrator users. To make a record available for other users, you
must provide the permissions to a specific group or a role to access the record. You can also restrict any field in a record
by assigning permissions to the record field.
1. To add permission for a record, perform the following steps:
a. In the Details section, click Edit beside the Permissions field.

The Edit Permissions for <record name> window is displayed.
b. Click Add Permission.
c. From the Type list, select whether you want to provide permission to a specific group or to a specific
role.
d. From the Group (or Role) list, select the group to which you want to provide permission.
The field will be displayed only to those users who belong to that group or role.
e. Click Save to save the permission settings.
2. To add permission for a specific record field, perform the following steps:
a. Select the record field to which you want to add permission.
b. From the Details section, click Edit beside the Permissions field.

b.
The Edit Permissions for <record name> window is displayed.
c. Click Add Permission.
d. From the Type list, select whether you want to provide permission to a specific group or to a specific
role.
e. From the Group (or Role) list, select the group to which you want to provide permission.
The field will be displayed only to those users who belong to that group (or role).
f. To assign view-only permission, select the View check box or select the Change check box to assign
permission to modify the record.
g. Click Save to save the permission settings.
3. Save the record definition.
To add indexes for record definitions
1. In the Indexes section, click Add Index.
2. If you want each index to return only a unique search result, select the Each index to resolve a unique result
check box.
3. From the Available Fields list, select the fields that you want to index and then click the Move side button.
4. To arrange the fields in decreasing priority order, use the Move Up or Move Down buttons and click Save.
If a composite index exists on fields F1 and F2, the record are sorted first by F1 and then by F2.

By default, a record contains an index for the GUID field and you cannot modify or delete the index. You can modify the
indexes for the other fields.
To define the scope for a record definition
1. In the Details section, click Scope/Customization Options.
2. From Definition Scope, select the scope for a record definition.

You can select any of the following options:
Application/Library (default)—Limits the use of the record definition within the same application or
library.
Public—Enables the record definition to be used by all the applications or libraries. Additionally, users can
customize the record definition properties, such as properties, fields, permissions, and search indexes.
To enable users to customize the record definition, perform the following tasks:
a. From the Customization Options area, select the Allow future customization to this record
definition check box.
b. In the Allow future customizations to: section, select whether you want to enable users to
customize the record definition's properties, fields, permissions, or search indexes.
c. From the list of available record definition fields, select whether you want to enable users to
customize the field's properties or permissions or both.
3. Click Save.
To export record data with a bundle

You can automatically export the record data when the library or application is packed in a bundle for deployment.
2. Select the application for which you want to export record data.
3. On the Records tab, click the record name you want to use.
4. In the Details section, click
5. Select the Should Export Data check box.
To associate and display field values for record definitions

Associate fields to record definitions, so that during runtime the associated field values are displayed instead of GUID
values. This configuration enables you to make the record definitions readable, as it is difficult to read and understand
the information just from the GUID values.
To associate fields to record definitions, perform the following steps:
1. Select the record definition.

The record definition details are displayed.
2. In the Display Value section, click Associated Display Value list and select the field that you want to associate with
the record definition.
Note
You can configure only a direct association between the record definitions. For more information about direct
associations for record definitions, see Creating record associations (see page 342).
If you do not associate any field value for a record definition, the record definition displays GUID values for the field. For
example, in a Approval application, the Leave Request record definition displays the Requester as GUID value
AGGAA5V0FMWPEAOZPNJAOYTJICQIRY.
If you associate field value with a record definition, the record definition displays the associated field value and not the
GUID value. For example, in a Approval application, the Leave Request record definition displays the Requester as Britney.
To copy fields in a record definition

You can copy custom fields from a regular record to the same record.
1. Log in to BMC Helix Innovation Studio, navigate to t he Workspace tab, and select the application.
2. On the Records tab, click the Regular type record name in which you want to copy fields.
3. Select the custom field on the record definition that you want to copy.
4. Select Copy.
Note
The Copy button is enabled when you select one custom field.
The Copy button is disabled if you select multiple custom fields or core fields.
5. A copy of the selected field is created as Copy of <selected field name>.
For example, you have a person record definition that has a field Official email address. You want to add another field for
an alternate email address. You can copy the Official email address field and rename it to Alternate email address.
Copying fields is not applicable for the following fields and record definitions:
Core fields
Inherited fields
Join records
Audit records
The following properties of the field are not copied:

id
name
customId
developerId
lastChangedBy
lastUpdateTime
optionLabelsById
overlayDescriptor
overlayGroupId
owner
version
Enabling full-text search in an application

Digital service applications that are developed by using BMC Helix Innovation Suite can enable full-text search (FTS) to
enhance search results in the application. FTS involves indexing before searching, so that when a user performs a search,
only the index is searched instead of the entire text. For more information about the benefits of FTS and file types that
can be searched in FTS, see Leveraging full-text search capabilities in your application. (see page 287)
The process of using full-text search (FTS) in an application includes the following stages:
Enabling FTS on the fields
Configuring FTS settings to refine the search results.
FTS can be enabled on the following types of fields:
Text fields
Attachment fields
This topic provides and overview and the steps to enable FTS on the required fields in an application.
Process of enabling and configuring FTS in an application

The following image explains the steps to be performed by the application business analyst and the administrator:

Role Task Reference
Application Enable FTS on text or attachment fields. 834635878 (see page 335)
business
analyst (Optional) Define the search category for text FTS fields. 834635878 (see page 335)
When a full-text search is triggered, the search engine references the search category
name along with the FTS index.
(Optional) Define the search relevancy of FTS-enabled fields. 834635878 (see page 335)
Defining the search relevancy helps in sorting the search results so that the results
with the most occurrences of the relevant word or phrase appear at the top.
Administrator (Optional) Configure additional FTS settings, such as a list of synonyms or a list of Configuring full-text search to refine the search
ignored words. results (see page 754)
Before you begin

Ensure that you have created a record definition (see page 329) and added the fields (see page 330) for which you want
to enable FTS in that record definition.
Note
Full-text search configuration is not carried forward in a Join record definition (see page 340).
FTS-enabled fields and their category names are carried forward in an inherited record definition (see page
338). The application business analyst must define the relevancy of FTS-enabled fields in the inherited record
definition.
To enable FTS on fields
2. Select the application for which you want to use FTS.
3. On the Records tab, click the record definition that contains fields for which you want to enable FTS.
4.
4. Select the field for which you want to enable FTS. You can enable FTS on only one field at a time.
5. On the Field Properties tab, in the DETAILS section, enable Full Text Search.
6. Click Save.
To add a search category name to FTS-enabled fields (Optional)

You can add the search category name only to text fields that are FTS-enabled.
2. On the Records tab, select the record definition in which you have enabled FTS on the fields.
3. Select the FTS-enabled field for which you want to add the search category name.
4. On the Field Properties tab, in the DETAILS section, in Search Category Name, type the search term for
the selected field.
For example, If you have selected the Description field, you can add issue as the search category name.
5. Click Save.
How search relevancy works for FTS enabled-fields

After you have enabled FTS on the required fields, you can define the relevancy of the FTS-enabled fields.
You can add the fields that represent the title, system environment, or keyword in the record definition. The default
relevancy by the number of occurrences starts with record definition title field (highest), followed by keyword fields, and
then environment.
For example, w hen the end-user performs a search, the search results display the records with the most occurrence of
the word or phrase entered in the Title Field (that has the most relevancy), followed by the Keywords Field and the
Environment Field.
(Optional) To add the search relevancy for FTS-enabled fields
2. Select the application for which you want to use FTS.
3. On the Records tab, click the record definition that has the FTS-enabled fields.
4. Navigate to the Record properties > Search.
5. In the Title Field list, select the field that represents the title of the record definition.
For example, you can select Case Summary because the text entered in this field is more likely to represent the
title.
6. In the Environment Field list, select the field that represents the computer enironment.
For example, y ou can select Operating System because the text entered in this field is morely likely to represent
the environment.

7. In the Keywords Field list, select the field that represents the search keywords.
For example, y ou can select Description because the text entered in this field is more likely to contain search
keywords.
Notes
You cannot add the same field in more than one relevancy—title, keyword, or environment.
If you are unable to see the FTS-enabled fields in the Title, Environment, or Keywords fields, ensure
that you have saved the record definition after 834635878 (see page 335).
8. Click Save.
Inheriting an existing record definition to a new record definition

You can create a record definition by extending or inheriting the details from an existing record definition.
Following are the advantages of inheriting from an existing record:
Prevents you from creating all the properties from the beginning.
Makes the record definition process faster.
Lets you inherit all the properties and behaviors of the super record definition.
Lets you modify properties such as fields and rules in the subrecord definition.
Records are defined as follows:
Super record definition: Is the existing record from which the properties and behaviors are extended or inherited.
Subrecord definition: Is the new record definition that inherits the properties and behaviors of the super record
definition.
Although you can simply modify the inherited properties from the super record definition, the permissions of the super
record definition do not get copied to the subrecord definition.You must separately add the permissions to the
subrecord definition.
For example, if you have an existing record definition called Ticket, and you inherit this record definition to create a new
record definition called Incident, then Ticket is the super record definition and Incident is a subrecord definition.
Before you begin

Before you create and manage record definitions, ensure that you have created a project and deployed it in BMC Helix
Innovation Studio. For more information, see Creating a Project using Maven and the Archetype (see page 806).
Note

To inherit an existing record definition to a new record definition
The following video helps you to inherit a record definition:
https://youtu.be/WE7xvdsepaA
2. Select the application or library to which you want to inherit a record definition.

The record with default fields is displayed.
4. In the Details section, click .
5. From Record Inheritance section, click Inherit from a Record Definition.
6. From the Record to Inherit drop-down list, select the record definition from which you want to inherit the
preferences.
Note
The Application/Library scoped definitions are marked with an asterisk ( * ). Ensure that you follow the
guidelines listed in Guidelines to define scope for the definitions (see page 319) before you select
these definitions.
The following table provides information about the properties:

Item Description
Core Fields Inherits all the core fields from the super record definition to the subrecord definitions.
If you select the Shared data with inheritors check box, the core fields of the super record definition are inherited by default.
Note: You cannot remove any core fields from being inherited to the new record definition.
Rules Inherits all the rules that are associated with the super record definition.
Field Permissions Inherits all the permissions that are associated with the fields of the super record definition.
Associations Inherits all the associations that are applied to the super record definition.
Audit Field Inherits all the field-level auditing properties that are configured for the super record definition.
Properties
7. (Optional) Specify the inheritance properties for the record definition.

UI Item Description
Shared data with Shares a common database with all the subrecord definitions that are inherited from this record definition.
inheritors You can search the database of super record definition and retrieve all the instances of super record definition and its
subrecord definitions.
When you select this check box, by default the core fields of the super record definition are inherited and cannot be
modified.
Make Abstract Prohibits the user from creating instances of that record definition.

UI Item Description
For example if Shape is abstract record definition and Circle is inherited record definition then you cannot create instance
of Shape record definition.
Make Final Prohibits the user from inheriting this record definition.
Limitations for inheriting existing record definitions

When you inherit or extend an existing record definition to a new record definition, you might encounter the following
limitations:
The subrecord definition cannot modify or delete the fields of the super record definition.
You can inherit only one record definition at a time.
You can stop extending or break the inheritance at any time if you have not selected the Share data with
inheritors option.
You c annot customize th e fields that you inherit in subrecord definitions. If you need to customize the inherited
fields, you must customize the fields in super record definition and then inherit the record definition.
Related topic
Creating or modifying regular record definitions (see page 329)
Creating join record definitions

You create a join record definition to combine data that is retrieved from multiple record definitions. The join record
definitions are similar to database joins.
Before you begin

Before you create and manage record definitions, ensure that you have created a project and deployed it in BMC Helix
Innovation Studio. For more information, see Creating a Project using Maven and the Archetype (see page 806).
Note
To create a join record definition
1. Log in to the BMC Helix Innovation Studio and navigate to the Workspace tab.
2. Select the application for which you need to create the join record.
3. On the Records tab, click New and select Join Record.

The Create New Join Record window appears.

3.
4. On the Record Definitions tab, specify the properties for the record definition.
Note
The Application/Library scoped definitions are marked with an asterisk ( * ). Ensure that you follow the
guidelines listed in Guidelines to define scope for the definitions (see page 319) before you select
these definitions.

Field Description
Primary The main record for combining the data.

record
Secondary The secondary record for combining the data.

record
Join type The type of join for the record definition. You can select either of the join record types:
Inner join—Selects entries only when corresponding values exist in both records.
Outer join—Includes all of the entries from the record that you select as primary, even entries for which there are no
matching entries in the secondary record.
5. On the Join Criteria tab, specify the expression for joining the records, and click Next.
The query for joining the records is restricted to the conditions specified in the expression.
6. On the Field Selection tab, select the fields from the primary and secondary records that you need to include in
the join record, and click Save.

7. Save the record.
Related topic
Creating record associations

You create a n association to define a relationship between the record definitions. While creating a record association,
you specify the cardinality and the constraint for the association.
The following table provides information about the parameters of a record association:
Parameter Description
Cardinality Type of relation between the records within the association, such as, one-to-one, one-to-many, and many-to-many.
Constraint Limitation for an association, such as, automatic deletion of the associated records. If record1 is associated to record2, and you delete record 2,
then record1 is also deleted automatically.
Note
Types of associations
An association can be either of the following types:
Type of Description
association
Direct Defines a direct relationship between the two records in the association, such as, one-to-one and one-to-many relationships. Multiple fields of one record and multiple
association be a part of the association.
Entries in two forms contains direct references to each other. For example, see the following illustration:

Type of Description
association
Indirect Defines an indirect relationship between the two records in the association; the records can be related to each other using a third record, such as many-to-many relati
association
Entries in two related forms do not have reference to each other. For example, see the following illustration:
Self Defines a relationship in which a self record definition is associated to itself through a direct relationship. For example, employee Manager association. A manager belo
association a manager also belongs to an employee role.
To create a record association
The following video helps you to create a record association:
https://youtu.be/9bOObkK2Kx8
2. Select the application or the library for which you want to create an association.
3. Select Associations > New.

The Create Association window is displayed.

4. Specify the properties for the association. The following properties are available:
UI item Task description
Association Type a unique name that identifies the association.

Name The association name must start with an alphanumeric character. Only alphanumeric characters, hyphens, underscore, and spaces are allowed in the
association name.
(Optional) Provide a short description of the association.

Description
First Record Select the source entity or the starting point of your association. Note: The Application/Library scoped definitions are marked with an asterisk ( * ). Ensu
you follow the guidelines listed in Guidelines to define scope for the definitions (see page 319) before you select these definitions.
(Optional) Provide a description for the first record, which explains the record in the context of the association.
Role of First
Record
Cardinality Select any one of the following relationship among the record definitions:
If you want to create a direct record association, select the cardinality as Has One or Has Many.
If you want to create an indirect record association, select the cardinality as Many To Many.
Second Record Select the target entity or the ending point of your association. Note: The Application/Library scoped definitions are marked with an asterisk ( * ). Ensure
you follow the guidelines listed in Guidelines to define scope for the definitions (see page 319) before you select these definitions.
(Optional) Provide a description for the second record, which explains the record in the context of the association.
Role of
Second Record

Add To create a direct association, select any of the following constraints:

Constraints
If record is deleted, automatically delete all associated records: Deletes all the associated records if the first record is deleted. This constraint add
Cascade Delete flag to the record association.
See the following image:
Require a record to be associated in order to create a new record: Creates the second record only when the first record is created. This constrai
available only when you specify to delete all the associated records if the first record is deleted.
Note: A direct association is automatically created when you select any of the constraints.
Scope Option to define the scope for association definition. This option further contains the following options:
/Customization
Application/Library (default)—To limit the use of the definition within the same Digital Service application or library.
Options
Public—To enable the definition to be used by all the applications or library and allow customizations for this definition.
Enable Select this item to validate and implement the association in the two records.
Association
5. Save the association.
To inherit an existing record association to a new record association

You can create a record association by extending or inheriting the details from an existing record association while you
are inheriting an existing record definition.
2. Select the application or library to which you want to inherit a record definition.

The record with default fields is displayed.
4. In the Details section, click .
5. From Record Inheritance section, click Inherit from a Record Definition.
6. From the Record to Inherit drop-down list, select the record definition from which you want to inherit the
preferences.

6.
Item Description
Core Fields Inherits all the core fields from the super record definition to the subrecord definitions.
If you select the Shared data with inheritors check box, the core fields of the super record definition are inherited by
default.
Note: You cannot remove any core fields from being inherited to the new record definition.
Rules Inherits all the rules that are associated with the super record definition.
Field Permissions Inherits all the permissions that are associated with the fields of the super record definition.
Associations Inherits all the associations that are applied to the super record definition.
7. (Optional) Specify the inheritance properties for the record definition.

UI Item Description
Shared data with inheritors Shares a common database with all the subrecord definitions that are inherited from this record definition.
You can search the database of super record definition and retrieve all the instances of super record definition
and its subrecord definitions.
When you select this check box, by default the core fields of the super record definition are inherited and cannot
be modified.
Make Abstract Prohibits the user from adding properties to the super record definition. In such case, you must use the default
inherited properties of the super record definition.
Make Final Prohibits the user from inheriting this record definition.

Goal Instruction
Create a new record definition or modify an existing record definition by using Record Creating or modifying regular record definitions (see page 329)
designer.
Create a record instance. Creating record instances (see page 346)
Enable row level security. Enabling row level security by defining security labels (see page
348)
Creating record instances

A record instance is the data created by the application for which the structure of the data is specified by the record
definition. You can create a record instance by using any of the following methods:
Data editor available on the Records tab
Use the Record Service via the Record Instance Resource with a REST client such as POSTMAN. Typically only
developers will do it this way.
Using an application itself. For example, there could be a View with a Record Editor component in Create Mode.
Note

To create a record instance using the Record Editor component of a view definition
You can use the Record Editor, which is the default component in View designer, to create or modify a record instance.
2. Select the application or the library for which you want to add or modify data.
3. On the Views tab, click any view name.

The View designer for that view is displayed.
4. From the Basic Components list in the left pane, drag and drop the Record Editor component to the View
designer canvas.
5. To add fields for the record definition, from the Properties tab in the right pane, click the General tab and then
perform the following steps:
a. From the Record Definition Name drop-down list, select the name of the record definition.
b. From the Mode list, select Create to create a record definition or select Edit to modify an existing record
definition.
c. Click Quick Add/Remove Fields, select the fields to apply and then click Apply.
The fields get added to the View designer canvas.
6. To define the properties of the fields that are added to the record definition, perform the following steps:
a. From the View designer canvas, select the field to which you want to define the properties.
b. From the Properties tab in the right pane, click the General tab.
c. From the Field Name drop-down list, select the name of the field.
d. In the Display Label field, type the label for the field.
e. To disable the field and make it inaccessible for all users , click Disabled and then specify the condition
when you want to disable the field. For example, you can disable the field at all times or you can specify to
disable the field in specific conditions.
f. To hide the field in specific conditions, click Hidden and then specify the condition when you want to hide
the field. For example, you can hide the field at all times or you can specify to hide the field in specific
conditions.
7. Save the view.
Note

If a record instance consists of a character field with length equal to zero, you must use the like operator to
filter the record. Do not use the equal to operator.
BMC Helix Innovation Suite server considers the field length equal to zero as CLOB datatype in Oracle
database and nvarchar datatype in SQL database.
To create a record instance using the Data editor
The following video describes the procedure for

creating and modifying record instance using Data Editor:
https://youtu.be/gehTnBcqAZk
2. Select the application or the library for which you want to add or modify data.
3. On the Records tab, select the record definition and click Edit data.
The Data Editor page is displayed.
4. Click New.
5. In the New Record window, enter the required information, and then click Save.
A record instance is created for the specific record.
Related topics
View definition components (see page 377)
Creating a view for a record instance using Record Editor (see page 396)
Enabling row level security by defining security labels

Security labels are used to enable the row level security. Security labels define a series of groups that can be given access
to record instances using a rule or a process. They add view and edit restrictions to record instances and fields. You can
create security labels using the Record designer.
When you create a security label in a record definition, a separate column of the security label is added in the database.
You can use the security label as a group while assigning permissions to a field or set the security labels through
processes and rules.
Note

To create a security label
1. Log in to the BMC Helix Innovation Studio, navigate to the Workspace tab, and select the application.
2. On the Records tab, navigate to the record definition for which you want to create the security labels.
3. Click the icon in the Properties pane on the right side and in the Security Labels section, click
Add/Remove Security labels.
4. In the Add/Remove Security Labels window, click Add Security Label and enter the values for the following fields:
Field Description
Name Enter the name of the security label.
Parent Select the security label which you want to assign as parent security label. This creates a hierarchy of security labels that is used for
permissions inheritance.
A parent label can only have one child label. See Parent security label (see page 350).
To add more security labels, repeat this step.

For example:
5. Save the changes and save the record definition.
After you add the labels, you can use the labels in the Rule designer and Process designer.
Notes

When you create a new record definition and add security labels, the security labels are added to the
Display ID field permissions. You can change or remove the permission of the Display ID field as per
your requirements.
When you inherit a record definition selecting the options Core Fields and Field permissions, the
Display ID field has the same security labels as that of the base record definition. For other record
definition inheritance options, the security labels in base record definition are not added in the
inherited record definition Display ID field permissions.
Parent security label

The parent security label allows permissions inheritance. A parent security label can have one child security label and
each child security label can only have one parent security label. A child security label can also have child security label of
its own, forming a multilevel hierarchy. In a multilevel hierarchy, assigning permission to a child security label grants
access to all ancestor security labels, such as the parent security label of a parent security label.
For example, in the following image, the security label named Parts Supplier is a parent to the Dealer A, and an ancestor
to Shop A1 security label.
Security label hierarchy
Using security labels in setting permissions

When you assign the permissions to a field in a record definition, the security labels are listed as a section of available
groups. All the security labels for the record definition are listed in alphabetical order by name. The parent and child
labels are listed at the same level. You can use the security labels like groups for assigning permissions.
The following image shows a sample Edit Permissions screen:

Setting the security labels in rules and processes

In the Rule designer and Process designer, an action (Palette > Records > Set Security Label) is available to populate the
security label field. You can use this action to set the security labels.
For more information on how to set the security label in Process designer, see Creating or modifying record instances
using Record Service Tasks (see page 457).
For more information on how to set the security label in Rule designer, see Working with rule definitions (see page 490).
Related topic
Creating hierarchical groups through security labels (see page 360)
Enabling record auditing

You can view and track updates made in record data through auditing. You can use the audit information to ensure that
business processes are followed and to identify and trace unauthorized access or activity.
You can enable or disable record auditing and view the audit records. Whenever the source record is modified, BMC
Helix Innovation Suite records the audit data from the source record to a new read-only audit record. You can audit
regular records, join records, and associated records.

How auditing works

The following illustration provides information about where the audit information is stored, and what information is
audited:
Process of enabling auditing

The following table lists the actions that must be performed to enable auditing:
Task Action Description Reference
1 Enable auditing on a record You must enable auditing on regular, join, and associated Enable auditing for a record definition (see page
definition. record definitions. )
When you enable auditing on a record definition, you

must also specify the name of the audit record definition
that is newly-created to store the audit details.
2 Specify the fields in the record You must specify the fields that must be tracked for Specify the record fields for auditing (see page 354)
definition for auditing. auditing. These fields are added to the newly-created
audit record definition as text-type fields.
3 (Optional) Specify the fields You can specify the fields from associated record Specify the fields from associated record
from associated record definition that must be tracked for auditing. These fields definitions for auditing (see page 355)
definitions for auditing. are added to the newly-created audit record definition as
text-type fields.
Note

To enable auditing for record definitions
2. Select the application in which you want to enable auditing on a record.
3. Click the Records tab.
4. From the list of available records, select the regular record definition or the join record definition that you want
to audit.
In this example, the Change regular record definition in the Ticketing application is enabled for auditing.
5. In the Details section, click the General Properties tab .
6. In the Auditing section, specify the preferences for tracking the changes in records.
The following table provides information about the audit properties:

Property Description
Enabled
Start the auditing of the record definition by selecting Enabled .
Audit Record Specify the name for the new audit record; for example, Audit for Change RecordDef.
Definition Name
Audit Filter Specify the criteria for auditing the records. BMC Helix Innovation Suite audits only those records whose fields match the
audit criteria.
For example, if you specify a customer name as the audit criterion, only that customer's records are audited.
If you do not specify any audit criteria, BMC Helix Innovation Suite audits all the records.

7. Click Save.
Whenever the source record is modified, BMC Helix Innovation Suite records the audit data from the source
record to a new audit record.
To specify the record fields for auditing

You can specify the fields in a record definition that should be specified for auditing, copying, auditing and copying, or
none. If you do not select fields for auditing, the audit record definition is created, but audit is not triggered.
To specify the record fields for auditing, perform the following steps:
2. Select the application in which you want to audit the fields.
4. From the list of available record definitions, click the record definition that you want to audit.
You can select either a regular record definition or a join record definition for auditing.
5. From the list of fields in the record definition, select the fields that you want to track.
6. In the Details section, select any one of the following auditing options:
Change triggers audit: An audit record is created if there is any change in the field value. The audited
records include the changed field values.

6.
Include value in audit: The field value is copied to an audit record. No new audit record is created.
The following example shows the auditing settings for the Display ID record field in the Task record definition:
7. Click Save.
Whenever the record fields from the source record are modified, BMC Helix Innovation Suite records the audit
data from the source record to a new audit record.
To specify the fields from associated record definitions for auditing

You can add fields from associated record definitions for auditing. This enables you to capture values of the associated
record instance fields at the time of auditing.
To enable auditing on fields from associated record definitions, perform the following steps:
2. Select the application in which you want to audit the fields.
4. From the list of record definitions, select the associated record definition from which you want to add fields for
auditing.
5.
5. In the AUDITING section, click Add/Remove Associated Fields.
6. From the list of Available Associations, click the association from which you want to add fields.
7. From the list of fields, click the Add icon next to the field that you want to specify for auditing.
8. In Name, specify a unique field name for the audit record definition.
9. In Field ID, specify the ID of the field.

The ID must be unique and contain only integers.
10. Click Save.
Warning
If a field from the associated record definition is deleted, it also gets deleted from the audit record
definition. When audit is triggered on this field, a null value is recorded in the field.
If an associated field is deleted from a record definition, it also gets deleted from the audit record
definition along with any audit data stored in the field.

Troubleshooting auditing
If the audit record is not created or the value in audited fields is null, use the following checklist to identify the issue:
Check if auditing is disabled (see page 359).
Check if the expression specified when enabling auditing on record definition (see page ) is according to your
business need.
Check if the Change triggers audit or the Include value in audit check box is selected when specifying the record
fields for auditing (see page ).
If the audited fields in an associated record definition contain null value, check the following conditions:
Association between the two record instances is not defined. For more information, see <add link>
Association is disabled.
Field in the associated record definition is deleted.
Association is deleted.
Actions that can be performed after enabling record auditing

The following table lists the actions that you can perform after you enable auditing on record definitions and specify
fields that must be audited:
Action Reference
View the audit record that contains the audit details. To view the newly-created audit record (see page )
Inherit audit-enabled fields from one record definition to another to avoid specifying To inherit field-level audit properties to a new record definition (see
them again. page 359)
Disable auditing on record definitions. To disable record auditing (see page 359)
If you no longer want to monitor the record changes, you can disable auditing on
record definitions.
To view the audit record

The access permissions from the record definition and fields that are audited are carried forward to their audit record
and cannot be edited. Roles that have access to the record definitions and fields that are audited can also view the audit
records.
To view the audit record, perform the following steps:
2. Select the application for which you want to view the audit record definition.

The newly-created audit record definition with the audit record type is displayed in the list of available records.
The following example shows a new audit record, Audit for Change RecordDef, that was created when the Change record
definition was modified:

Notes
All fields from the associated record definition are created as text fields in the audit record definitions.
When auditing record definitions that have one-to-many association, the values populated in audit
record definition are separated by two semicolons ( ;; )
Example: A ticket is associated with three tasks. Two tasks are closed, one is in progress. If audit the
task status, the contents of the audit field will be
"Closed;;Closed;;In Progress;;"
You cannot add attachment field types from associated record definitions for auditing.
Actions available for audit records

The following table provides information about the actions that can and cannot be performed on the newly-created
audit record:
Action Can be performed?
Rename the audit record. (tick)
Add an index to the audit record. (tick)
Modify only the index and permissions of the audit records. (tick)
Create a join record by using another audit record as the base. (tick)
Create an association between audit records. (error)
Add or delete fields from the audit record. (error)
Configure or remove the security label for audit records. (error)
Delete the audit record.

Action Can be performed?
Note: Only the administrators can delete the audit record. (error)
Manual creation or update of record in audit record definition. (error)
To inherit field-level audit properties to a new record definition

To avoid specifying the audit properties again, you can inherit or extend the field-level audit properties from an existing
record definition to a new record definition,
In this example, you are inheriting from the Change record definition to a new record definition. To inherit the field-level
audit properties, from the Inherit list, select the Audit Field Properties check box. For more information, see Inheriting an
existing record definition to a new record definition (see page 338).
To disable auditing for record definitions
2. Select the application for which you want to disable auditing for a record definition.
4. From the list of available record definitions, click the record definition for which you want to disable auditing.
You can select either a regular record definition or a join record definition for auditing.
5. In the Details section, click the General Properties tab .
6. In the Auditing section, click Enabled for the record definition that was enabled for auditing.
This action disables the record auditing and you no longer receive updates about the changes in the record.

Related topic
Creating hierarchical groups by defining security labels

You can define the relationship between user groups and rank them according to the level of importance or authority by
defining hierarchical groups. A hierarchical group is headed by an ancestor group with descendant groups beneath it. At
each level higher than the base of the hierarchy, the descendant groups can also be ancestors of the groups lower in the
hierarchy.
In BMC Helix Innovation Studio, you can define hierarchical groups to perform the following functions:
Define structure and form within the organization.
Express the relationships between the user information, and share the information as per the relationship.
Manage large amounts of data.
The following illustration displays a group relationship structure in a global car dealership company:
How hierarchical groups secure data
Row-level security for database tables

Hierarchical groups enable you to define row-level security (RLS) for database tables. With RLS, you can store
data for many users in a database table, and restrict row-level access based on the user's identity or role.
Some of the access levels that you can configure are as follows:
Restrict access to a certain data based on an employee's region and role.
Ensure that tenants of a shared system application can access only their data.
Security labels for database tables

Row-level security is defined by using security labels. A security label dynamically controls record and field access.
You can define rules and process flows to automatically assign security labels. For example, you can define a rule
to generate the name of a group as the security label for that group.
Security labels protect database tables at the row level, by assigning different levels of security. After row-level
security is defined by using security labels, only those users with the appropriate permissions can access the row
data.
For example, in a car dealership company, you can create security labels such as car type, sales group, and
dealership, and only users with the appropriate security classification are allowed access to the relevant data.
Relationships within the user groups

By specifying an ancestor-descendent relationship between user groups, you can grant data permissions
according to the relationship.
You can define the following relationships in a hierarchy:
Ancestor: A parent or top-level group within the hierarchy, with one or more subgroups associated with
it. An ancestor group can be attached to one or more child groups.
Descendant: A child group within the hierarchy, that is attached to a parent group. A child group can be
attached to only one parent user group.
Hierarchical group inheritance

The following examples illustrate the data flow between ancestor groups and descendant groups.
Scenario 1: Ancestor groups can view data from all descendant groups
In the Car dealership hierarchical group, the users in the hierarchy need to have access to a sales application to view all
the sales records. The sales application has a Sales record definition, that includes the latest sales records for a certain
type of cars. All ancestors of the Sales Person group can view the sales records of the sales people in all dealerships.
Example 2: Descendant groups can view data from all ancestor groups
In the Car dealership hierarchical group, the users in the headquarters use a sales application to view all the sales
records. The sales application has a Catalog record definition, that includes the latest changes in the sales policy for a
certain type of cars. All descendant groups beneath the top-level Car dealership group can access the Catalog record.

Process of defining a hierarchical group in an organization

The following table describes the steps of creating a hierarchical group in BMC Helix Innovation Studio:
Stage Task Description
1 Create the Digital Service Set up the application development process and deploy it to BMC Helix Innovation Studio. The application
application project and deploy development process consists of creating a project using Maven archetype and BMC Helix Innovation Suite SDK,
the project to BMC Helix implementing data and logical definitions using BMC Helix Innovation Studio, extending the services using Java
Innovation Studio (see page 799) and JavaScript (if required), and packing the application.
2 Identify the different user To define a hierarchical group, identify the data that each user needs to access according to the user's role in the
groups in the organization organization.
3 Creating or modifying security You can create security labels for regular record definitions or join record definitions.
labels in record definitions to
define hierarchy (see page 362)
4 Assign permissions to the You can assign permissions to the security label such that only the specified user group or role can access the
security labels (see page 362) record field data.
5 Configure the security labels for You can configure the security label for a rule or a process to enable the hierarchy.
a rule or a process (see page 362
)
After you create and configure the security labels for record definitions, you can perform any of the following tasks:
Inherit the existing security labels to new record definitions (see page 370) to extend the security labels from an
existing record definition to a new record definition.
Modify the existing security labels (see page ) to enforce the appropriate permissions if there is any change in
the organization structure.
Creating or modifying security labels in record definitions to define hierarchy

You can define hierarchy in an organization by using security labels. Security labels protect database tables at the row
level by assigning different levels of security. Only those users with the appropriate permissions can access the row data.
After you create a security label, a separate column of the security label is added to the database. For example, in a car
dealership company, you create security labels like car type, sales group, or dealership, and only the users with the
appropriate security classification are allowed access to the relevant data.

You can define the following relationships within the security labels:
Ancestor: A parent or top-level group within the hierarchy, with one or more subgroups associated with it. Only
the ancestor security label's groups can access the record and record field data of the security label's groups.
Descendant: A child group within the hierarchy, that is attached to a parent group. Only the descendant security
label's groups can access the record and record field data of the security label's groups.
The following illustration provides information about the steps involved in creating security labels:
You use the Records designer in BMC Helix Innovation Studio to create the security labels for a record definition. You
can create security labels for 834635982 (see page 362) or for 834635982 (see page 362). The creation of security labels
is a part of creating different types of definitions to customize your application. For more information, see Creating the
definitions for a tailorable Digital Service application (see page 323).
Note
The following table describes the steps of creating a hierarchical group in BMC Helix Innovation Studio by using security
labels:
Stage Task
1 Create security labels for 834635982 (see page 362) or for 834635982 (see page 362).

Stage Task
2 834635982 (see page 362) such that only the specified user group or role can access the record field data.
3 834635982 (see page 362).
Before you begin

Ensure that you have the following items:
A project for the Digital Service application is created, and the application is deployed to the server. After
completing this task, you can view and customize the application in BMC Helix Innovation Studio. For more
information, see Preparing to develop a Digital Service application (see page 799).
A unique name is used for the security label. Security labels with a duplicate name cannot be created.
To create security labels for regular record definitions

You can create a security label for a regular record definition. A regular record is a record definition that is not a
combination of multiple record definitions.
1. Log in to the BMC Helix Innovation Studio, navigate to the Workspace tab, and select the application.
3. Click the Settings icon ( )in the Properties pane on the right side and in the Security Labels section,
click Add/Remove Security labels.
The Add/Remove Security Labels dialog box appears.
4. In the Security Label field, enter a unique name for the security label and click Add.
5. To specify a security label as an ancestor or descendant, perform the following steps:
a. From the Security Labels area, click the Settings icon ( ) beside the security label that you
want to modify.
The security label appears in the Security Labels area. You must create the security label first and then
assign the label as an ancestor or descendant.
b. To specify an ancestor for the security label, select the required security label from the Ancestors
Security Label list.
Note
The label is autopopulated with the ancestors of the Security Label's groups. An ancestor
security label can be attached to only one descendant security label.
c. To specify a descendant for the security label, select the required security label from the Descendants
Note

c.
The label is autopopulated with the ancestors of the Security Label's groups. A descendant
security label can be attached to only one ancestor security label.
d. Click Update.
For example, see the following image:
6. Specify the rest of the properties for the record definition, such as add record fields, specify an index, export the
record data, and so on. For more information, see Creating or modifying regular record definitions (see page 329)
.
7. Click Save.
Notes
When you create a new record definition and add security labels, the security labels are added to the
Display ID field permissions. You can change or remove the permission of the Display ID field as per
your requirements.

Ancestor or descendant groups can access the record instances even after the hierarchy of security
labels is removed. To restrict the access, you must remove the ancestor or descendant security labels
from the Display ID permissions list of the record definition.
To create security labels for join record definitions

You can create security labels for join record definitions. A join record definition is a combination of data that is
retrieved from multiple record definitions. Join record definitions are similar to database joins.
1. Log in to BMC Helix Innovation Studio.
2. Create a join record definition. For more information about how to create a join record definition, see Creating
join record definitions (see page 340).
3. Click the Settings icon ( ) in the Properties pane on the right side and in the Security Labels
section, click Add/Remove Security labels.
4. In the Add/Remove Security Labels dialog box, select the security labels to include in the join record definition
and click Save.
5. On the Workspace tab, navigate to the application for which you need to create the join record.
6.
6. On the Records tab, click New and select Join Record.

The Create New Join Record window appears.
7. On the Record Definitions tab, specify the properties for the record definition.
Field Description
Primary The main record for combining the data.

record
Secondary The secondary record for combining the data.

record
Join type The type of join for the record definition. You can select either of the join record types:
Inner join—Selects entries only when corresponding values exist in both records.
Outer join—Includes all of the entries from the record that you select as primary records, even entries that do not have a
matching entry in the secondary record.
A join record is created that contains the security labels of the multiple record definitions.
To assign permissions for security labels

To ensure that the record field data can be accessed by only those groups that are attached to the security label, you
must assign appropriate permissions to a record field.
Assigning permission to security labels is similar to assigning permissions to groups. When assigning permission to a
record field, the available security labels are listed alphabetical order. All security labels (ancestors and descendants) are
listed at the same level.
Perform the following steps to assign permissions for security labels:
1. Select the record field for which you want to assign permissions.
2. In the Properties pane on the right side, click Edit beside the Permissions area.
3. In the Edit Permissions dialog box, click Add Permission and specify the properties for the record definition.
Field Description
Type Specify whether the permission is to be granted to a role or a group.
Group Select the group or the role that should be able to access the record field, and then specify any one of the following access types:
View: Users can only view the record field data.
Change: Users can view and change the record field data.

After you assign permissions for security labels, only those user groups or roles can view or change the record field data.
To configure the security labels in rules and processes

In the Rule designer and Process designer, an action (Palette > Records > Set Security Label) is available to populate the
security label field. You can use this action to set the security labels.
For more information about how to set the security label in the Process designer, see Creating or modifying record
instances using Record Service Tasks (see page 457). For more information on how to set the security label in the Rule
designer, see Working with rule definitions (see page 490).
To modify the existing security labels

You can modify an existing security label to enforce the appropriate permissions, for example, if there is any change in
the organization structure.
2. Select the application for which you want to modify the security label.
3. Navigate to Records and select the record definition that you want to update.
4. Click the Settings icon ( ) in the Properties pane on the right side and in the Security Labels
section, click Add/Remove Security labels.
5. In the Security Label field, enter a unique name for the security label and click Add.
6. To specify a security label as an ancestor or descendant, perform the following steps:

a. From the Security Labels area, click the Settings icon ( ) beside the security label that you
want to modify.
The security label appears in the Security Labels area.
b. To specify an ancestor for the security label, select the required security label from the Ancestors
Note:
The label is autopopulated with the ancestors of the Security Label's groups. An ancestor
c. To specify a descendant for the security label, select the required security label from the Descendants
Note:
The label is autopopulated with the descendants of the Security Label's groups. A descendant
d. Click Update.
For example, see the following image:

After you add the labels, you can use the labels in the Rule designer and Process designer.
Inheriting existing security labels to new record definitions

You can extend the security labels from an existing record definition to a new record definition. Inheriting security labels
from an existing record ensures that the record creation process is faster and has the following advantages:
You need not create all the security labels for all the record definitions in the hierarchy.
You can inherit all the properties and behaviors of the parent record definition.
You can modify properties such as fields and rules in the child record definition.
For more information, see Inheriting an existing record definition to a new record definition (see page 338).
Note

Before you begin

Ensure that you have the following items:
A project for the Digital Service application is created, and the application is deployed to the server. After
completing this task, you can view and customize the application in BMC Helix Innovation Studio. For more
information, see Preparing to develop a Digital Service application (see page 799).
A unique name is used for the security label.
To inherit security labels to new record definitions
1. Log in to BMC Helix Innovation Studio, navigate to the Workspace tab, and select the application.
3. Click the Edit icon ( ) in the Properties pane on the right side and in the Security
Labels section, click Add/Remove Security label.
4. In the Add/Remove Security Labels window, click Add Security Label and provide the following information:
Field Description
Security Label Details
Security label Enter a unique name for the security label and click Add. The security label is displayed in the Security Labels list on the right.
Ancestors From the list of available security labels, select the security label, that you want to assign as the parent in the hierarchy, and click
Security Label Add. A parent group can be attached to only one child group.
Descendants From the list of available security labels, select the security label, that you want to assign as the child in the hierarchy, and click
Security Label Add. A child group can be attached to only one parent group.
To add more security labels, repeat this step.

For example, see the following illustration:

5. Save the changes and save the record definition.
Note
After the security labels are inherited, you cannot change the label name or delete a label inherited from the super
record definition. However, you can rename or delete the labels that you created for this record definition and change
the hierarchy within the inherited labels.
After you add the labels, you can use the labels in the Rule designer and Process designer. For more information, see the
following topics:
Creating or modifying security labels in record definitions (see page 457) to know how to set the security label in
Process designer.
Working with rule definitions (see page 490) to know how to set the security label in Rule designer.
Note
When you create a new record definition and add security labels, the security labels are added to the Display ID
field permissions. You can change or remove the permission of the Display ID field as per your requirements.

Securing text fields

BMC Helix Innovation Suite enables you to enter a secure value in a text field by encrypting, hashing, or masking. You can
perform this using properties such as Store Encrypted, Store Hashed, or by masking a field value. The advantage of using
these properties is that the information entered in the text fields can be stored safely and viewers will not have access to
confidential information.
The difference between these properties is that Store Hashed and Store Encrypted can be enabled at text field level
whereas masking cannot be enabled for an individual text field. Also, Store Hashed and masking are one way encrypted
and can never be decrypted.
This topic describes the information about providing security to a text field using these options.
Notes
Application business analysts can customize the objects developed in their own applications and that
are marked customizable by the developers, but cannot customize the objects developed in com.bmc.
arsys. For example, objects in core BMC applications like Foundation, Approval, and Assignment cannot
be customized.
You cannot change the field IDs of default record fields.
To encrypt a text field

You can encrypt a text field in a record definition using the Store Encrypted property available in the Record designer.
With this property, value of the text field is encrypted on persisting in database but appears as clear text when shown in
UI. So, important and confidential information is secured . The Store Encrypted property is available only for the text
fields.
2. Select the application for which you want to encrypt record definition field.
3. On the Records tab, select the record definition and click the record name.
4. In the Record designer, select the field name that you want to encrypt.
5. Click the Settings icon in the Details pane on the right side.
6. In the field details, use the toggle key for the Store Encrypted property and save the record.

The value of a field with this property set is stored as a encrypted in the database, but is not masked on your application
UI.
To mask a text field

When you need to mask the value for a text field (for example, a password field), you set the Field ID property of the
record to 102 or 123. These special field IDs can be used only once per record definition.
2. Select the application for which you want to mask record definition field.
4. In the Record designer, select the field name for which you want to mask the value.
5. In the Details pane, navigate to field details section.
6. In the Field ID, enter the value 102 or 123 and save the record.
To verify a text field mask
1. Create a view.

2. Create a record instance for the record definition that contains the masked field (for example, a password field).
3. Preview the view definition.
4. Enter the value for the field and verify that the masked field value appears in the form of dots or asterisks.
To hash a text field

You can enable Store Hashed property for a newly created or already existing text field in a record definition. You can
enable Store Hashed property only for text fields. After enabling this property, if you enter a value in the text field, it
appears as dots or asterisks and not as clear text. A store hashed text value can never be decrypted. For a Store Hashed
property, the field length should be 30 characters.
You cannot modify Store Hashed property on a customized and inherited text field. You cannot change it on record
definitions like Join and Audit. For these record definitions, the Store Hashed property will always be the same as the one
defined for their parent record definitions.
This property is useful when any crucial, highly secured information needs to be entered and stored.
For example, you can add a password or similar authentication parameter for every user. If the text field for the
parameter is store hash enabled, the value entered for this parameter always appears as dots and never as a text.
For more information about PIN in Person data form, see Creating or modifying Person data (see page 664).
2. Select the application where you want to create a new record definition.
3. In a record definition, add a text field or go to any existing text field.
4. For the text field, in the Details pane, enter all the details including Name, Field ID and so on.
5. In Details pane, use the toggle key to enable the Store Hashed property.
6. Enter Length as 30 as the field length of a Store Hashed property should be 30.
7. Click Save.

After you enable the Store Hashed property, if you go to Edit Data of the text field, and click New, a field will be present
on the UI of the application. This field will have the same name as the Name entered in the text field details screen. If you
enter any text in this field, it will appear as dots or asterisks.
You can also use the Store Hashed property to validate the PIN value of the requester.
For more information about validating PIN value, see Validating and verifying a PIN value (see page 486).
Related topic
Filtering record definitions

Ability to filter record definitions from a long list of records enables a you to quickly search only relevant records. You
can filter and search a record by typing in a relevant search term in the Search box. You can also filter record definitions
based on the Modified Date column in the record definition grid.
List of records without filtering the Modified Date column List of records after filtering the M
Defining the user interface through view definitions

In BMC Helix Innovation Studio, a view definition is a graphical representation of your application. You use the view
definitions to design the user interface for applications.
You can create a view definition by arranging the data items in a specific order or by showing only specific data items.
For example, a view definition called Tracking Item which will be used to create and update Tracking Item records.
Note

Goal Instruction
Understand the components of view definitions. View definition components (see page 377)
Create view definitions or update the existing view definitions. Creating or modifying view definitions (see page 378)

Goal Instruction
Perform an action in a view definition such as saving a view, deleting a record instance, and Configuring actions by using an action button (see page
launching a URL. 384)
Define the layout for a region of a view that can include view components or nested container. Creating a layout using Containers (see page 391)
Create record instances or to modify existing record instances from the view definition. Creating a view for a record instance using Record Editor
(see page 396)
Display the record instances and fields of the associated record definitions in a tabular format on Working with the Record Grid (see page 404)
the user interface of the deployed application.
Extend a view so that multiple views are displayed as a single combined view during runtime. Enabling extension of application definitions (see page
415)
View definition components

The View designer in the BMC Helix Innovation Studio contains the following components that you can use while
designing a view definition the Digital Service application UI.
Note
Components Description
Basic components
Record Grid Displays record fields in a tabular format on UI.
For more information, see Working with the Record Grid (see page 404).
Record Provides the following features:

Editor
Allows data editing for record instances
Supports data menus and includes all supported typed data widgets
Includes configurable logic to define dynamic expressions, cascading menus, and configurable actions for validation
For more information, see Creating a view for a record instance using Record Editor (see page 396).
Action Launches an action in a view. For more information, see Configuring actions by using an action button (see page 384).
Button
Container Defines a region of a view that can include view components or nested container.
For more information, see Creating a layout using Containers (see page 391).
Rich Text Improves the appearance of text, including adding hyperlinks.
Form fields
Fields Displays the record fields on the UI. You can use the following fields types in the View designer:
Attachment, Boolean, Date, Date/Time, Decimal, Dropdown, Floating, Integer, Select group, Text, Text area and Time.
Approval components
Approval Provides a visual experience for creating and managing an approval process.
console

Components Description
Note: The Approval Service is deployed by default with the BMC Helix Innovation Studio. However, the approval components are available in
the View designer only when you define the dependency of your application on the Approvals library.
Related topic
Creating or modifying view definitions

You use BMC Helix Innovation Studio to create a view definition for designing the user interface for applications. You can
create a view definition by arranging the data items in a specific order or by showing only specific data items. For
example, a view definition called Tracking Item can be used to create and update Tracking Item records.
Before you begin

Before you create and manage view definitions, ensure that you have created a project and deployed it in BMC Helix
Innovation Studio. For more information, see Creating a Project using Maven and the Archetype (see page 806) .
Note
Creating a view definition
The following video describes the

procedure to create a simple view definition:
https://www.youtube.com/watch?v=IJOSEigTYJY
1. Log in to BMC Helix Innovation Studio and navigate to th e Workspace tab.
2. Select the application for which you want to create a view.
3. Select Views > New.
4. Select the layout template that you want to use.

The New View page is displayed.
5. In the Properties panel, enter a name and description for the view definition, and click Save.
The view definition name must start with an alphanumeric character. Only alphanumeric characters, hyphens,
dashes and spaces are allowed in the view definition name.
6. Select Scope/Customization Options to define the scope for a view definition. This option further contains the
following options:
Application/Library (default)—To limit the use of the definition within the same Digital Service application
or library.

Public—To enable the definition to be used by all the applications or library and allow customizations for
this definition.
7. (Optional) Add permissions for a view (see page 379) or a specific view component (see page 379).
Note
You can add permissions to a view or view component while creating the view definition, or after the
view definition is created.
8. Specify either of the following runtime parameters:
To specify that the user must provide some information at runtime before the view definition opens,
from the INPUT PARAMETERS list, click Add and specify the input field name.
To specify that the user must provide some information after the view definition closes, from the from
the OUTPUT PARAMETERS list, click Add and specify the output field name. Click Click to build an
expression for specifying the data allowed for the expression.
9. From the Palette, drag and drop the components or form fields to the canvas in the order that you want them to
appear on the user interface.
For more information about components that are available within BMC Helix Innovation Studio, see Defining the
user interface through view definitions (see page 376).
10. From the Properties pane, on the Validation tab , check and resolve any validation errors for the view
definition before you proceed.
11. Save the view definition.
To add permission for a view definition
1. In the Details section, click Edit beside the Permissions field.
2. Click Add Permission.
3. From the Type list, select whether you want to provide permission to a specific group or to a specific role.
4. From the Group list, select the group to which you want to provide permission.
The view will be displayed only to those users who belong to the group.
5. Click Save.
To add permission for a view component
1. Select the view component to which you want to add permission.
2. From the Details section, click Edit beside the Permissions field.
4.
The view will be displayed only to those users who belong to that group.
6. Perform one of the following actions:
a. To assign view-only permission, select the View check box.
b. To assign edit permission, select the Change check box.
7. Click Save.
To create complex view layouts compared with simple view layouts
The following video describes the procedure

to create complex layout for a view definition:
https://youtu.be/bG9J1F1xlNE
2. Select the application for which you want to create complex view layouts.
3. Select Views > New.
4. Select the layout template that you want to use.

The selected layout is added to the canvas.
5. Drag and drop one more container into a column in the canvas.
6. Select the number of columns that you want to add in the container. You can choose up to a maximum of 6
columns.
7. (Optional) To add nested containers, drag and drop another container into the container in the canvas.
8. Select each container individually and specify its properties.
9. (Optional) Add the required form fields and basic components to the view definition.
10. Click Save.
Copying a view definition

You can copy a view definition and create a view that is based on an existing view definition. This will save time taken to
design a new view definition.
To copy a view definition
2. Select the application that contains the view you want to copy.
3. Click the Views tab.

4. From the list of views, select the view and click Copy.
The view definition is copied as a new view.
Modifying view definitions

You can modify existing view definitions by adding permissions to a view definition or a view component, adding or
removing components, and so on.
To update the permissions for a view definition

By default, a view definition is visible only to the administrator users. To make a record available for other users, you
must provide the permissions to a specific group or a role to access the view. You can also restrict any component in a
view by assigning permissions to the component.
2. Select the application for which you want to add permissions for a view definition.
3. Navigate to Records and select the view to which you want to add permissions.
The view and the associated components are displayed.
Note:
By default, the view is displayed only to the administrators.
4. In the Details section, click Edit beside the Permissions field.
The view will be displayed only to those users who belong to that group.
8. Click Save to save the permission settings.
To update the permissions for a view component
2.
2. Select the application for which you want to add permissions for a view definition.
3. Navigate to Records and select the view to which you want to add permissions.
Note:
4. Select the view component for which you want to add permission.
5. From the Details section, click Edit beside the Permissions field.
8. From the Group list, select the group to which you want to provide permission. The field will be displayed only to
those users who belong to that group.
a. To assign view-only permission, select the View check box.
b. To assign edit permission, select the Change check box.
10. Click Save to save the permission settings.
To delete view components
2. Select the application for which you want to update the view definition.
3. Navigate to Records and select the view to which you want to update.
Note:
4. From the canvas, select the view component that you want to delete.
5. Click the cross sign beside the selected view component.

The view component is deleted from the view definition.

Using the Expression Editor
The following video describes the procedure to add

an expression to disable a field in a Record Editor:
https://youtu.be/LAY--nBT5rs
The Expression Editor is a dialog box that appears in the View designer in BMC Helix Innovation Studio whenever you
click the option Click to build an expression for a setting that requires an expression. It presents the data allowed for the
expression, such as the fields in the record grid and record editor, the fields in the associated record definitions, view
component properties, keywords, view input parameters, or static values. The Expression Editor includes a key pad that
consists of the most commonly used operators. Expressions can contain any valid sequence of operators, wildcards, and
keywords.
To build an expression, you select the available values in the Expression Editor. The following are the available values in
the Expression Editor for a Record Grid:
Filter By—all fields in the record definition and associations selected for the record grid.
Selected Row Count—number of rows that are selected.
Selected Rows—record grid rows (record instances) that you select.
First Selected Row—record grid row (record instance) that you select. Displays the columns selected to be
displayed on the record grid.
Clickable row—displays the selected columns that should be displayed on the record grid.
Total row count—number of rows in the record grid.
Keywords—available keywords
The following are the available values in the Expression Editor for a record editor:
Record definition name—name of the record definition selected for the record editor
Record instance Id—record instance ID value
Record instance—all fields in the record definition selected for the record editor
For example, the following image shows an expression to assign the value of Task name field to the Description field in a
record editor (To assign the value, select the field in the record editor and on the Value field click Edit):

You can use the Next button to set the expression for the next field in the record editor without exit from the Expression
Editor.
You can build the expressions using Expression Editor to perform the following actions:
Hide or disable a field in a record editor on specific conditions
Hide or disable action buttons on specific conditions
Assign value to field in record editor
Specify the record instance for a record editor
Specify filter conditions for a record grid
Associated record ID for a record grid
Specify URL in action buttons
Configuring actions by using an action button

Action buttons are shortcuts to certain tasks that you can perform in a view definition. You can create action buttons for
saving a view, deleting a record instance, launching a URL, and so on. The tasks are executed according to the sequence
of the action buttons in the view definition.
You can add an action button while creating a view or while editing an existing view definition. You also can specify
multiple actions for a single action button and specify the sequence in which you want the actions to be executed.
Note
To add an action button to a view definition

to add an action button:

https://youtu.be/T93mxH2G118
2. Select the application for which you want to add an action button.
3. On the Views tab, click the name of the view definition to which you want to add an action button.
4. From the Palette, drag the Action Button component to the canvas in the order that you want them to appear on
the user interface.
5. In the Properties pane on the right side, click the Settings icon , and then specify the preferences for each
button.
Label Defines a unique name of the action button.
Style Specifies the display format for the action button. The following styles are available:
Primary: Displays the button with red background color.
Secondary: Displays the button with a black border and no background color.
Clear: Displays the button with no background color and no border.
Link: Displays the button that appears as a hyperlink. You can also specify an icon to be used with the action button link.
Size Specifies the size of the action button. You can specify either small or large size for the action button.
Icon Defines the icon for the action button. For example, if you are creating a search button, you can select the Search icon.
Icon Specifies the alignment of the icon relative to the action button.
Alignment
Disabled Disables the action button in specific conditions, such as, if you want to disable the button at all times or when a specific condition
is met.
Hidden Hides the action button in specific conditions, such as, if you want to disable the button at all times or when a specific condition is
met.
6. Select the action button for which you want to add actions, and from the Actions section, click Add/Remove
Actions.
In the Add/Remove Actions window, select the actions according to your requirements. For multiple actions, you
can set the execution order of the actions by placing actions in a sequence.
You can configure one or more of the following actions:
Open an URL or start a process
Open or close a view
Associate, dissociate, delete records
Edit multiple records
Set properties for the action button

Save, cancel, or refresh the task
To add a button bar to a view definition

Button bar is a view component that can be used to align the action buttons in a series in a view definition.The following
image shows a sample view definition that contains a button bar:
To add a button bar to a view definition, perform the following steps:
2. Select the application for which you want to add a button bar.

3. On the Views tab, click the name of the view definition in which you want to add a button bar.
4. From the Palette , drag and drop the Button Bar component to the canvas.
5. From the Palette , drag and drop the Action Button components to the Button Bar and specify the required
properties for the Action Buttons. For more information, see To add an action button to a view definition (see
page 384).
6. Click the Settings icon in the Properties pane, and specify the following properties:
Alignment Specifies the position of action buttons in the Button Bar.
Hidden Hides the Button Bar in specific conditions, such as, if you want to disable the button at all times or when a specific condition is met.
Example 1: To use one action button to hide another action button

Using the Set Property parameter, you can define multiple actions for an action button by assigning values to the
property of the view component.
Example elements
For example, a view definition consists of two action buttons Action button1 and Action button2 along with other
view components. You can assign values to the action button properties such that when you click Action button1,
the Action button2 gets hidden.
To hide the Action button2 when the Action button1 is clicked, perform the following steps:
1. Open the view definition that you want to modify.
2. In the View designer, select Action button1 and click Add/Remove Actions.
3. In Add/Remove Actions, add Set Property action.
4. On the Property path field, using Click to build an expression, add the Hidden property for the Action button2
and click OK.
5. On the Property value field, using Click to build an expression, enter value 1 set Hidden property for the Action
button2 and click OK.
6. Save the changes to Add/Remove Actions screen.
Example 2: To define multiple actions for an action button

You can define multiple actions for a single action button, and specify the sequence in which the actions must be
performed.

Example elements
For example, consider a view definition Employee which consists of an output parameter, Department. To use the
value of this output parameter in another view definition, Organization, you must open the Employee view, assign
the value in the Organization view and save the Organization view.
To define multiple actions for an action button by using output parameter, perform the following steps:
1. Open the view definition using which you want to assign the value of the output parameter. For example, output
parameter Department
2. Add an action button to the view definition and specify the general properties for the action button.
3. In the Actions section, click Add/Remove Actions.
4. Add the Open view action to open the view definition.
5. Add the Set Property action as follows:
a. On the Property path field, using Click to build an expression, add the view component property to which
you want to assign the value of the output parameter Department.
For example, assign the value to a record grid field.
b. On the Property value field, using Click to build an expression, add Department.
6. Add Save View action and click Save.
Example 3: To enable editing of multiple records using an Edit Records action

You can enable editing of multiple records in a record grid by using the Edit Records action. This causes a built-in dialog
to appear in the application that allows the user to specify values that can be applied to all selected records. The fields
that cannot be edited across the selected rows do not appear in the application. The record editor updates only those
records that are visible in the grid. For example, if there are 50,000 records loaded in the record grid, but only 50
records are visible in the viewport, the record editor edits and updates only those 50 records.
To enable editing of multiple records, perform the following actions:
2. Select the application for which you want to add a Record Grid.
3. On the Views tab, click the name of the view definition in which you want to add a Record Grid.
4. From the Palette, drag the Record Grid component onto the canvas as you want it to appear in the application
user interface.
5. From the Basic Components Panel, drag the Action Button and add it onto the Record Grid.
6. Select the Action Button, and click Properties > Actions.

7. Click Add/Remove Actions.
8. On the Add/Remove Actions screen, click Edit Records action, configure the following:
a.
a. Records—To define an expression that evaluates to one of the following: Record Grid, or a collection of
Record Instances, a collection of Record Instance IDs, c lick Click to build an expression.
The Edit Expression screen appears.
b. Record Definition— To enable editing of the record definition, select the record definition.
9. Click Save.
Example 3: To define size of the modal views by using the Open View action
2. Select the application to which you want to add an action button.
3. On the Views tab, click the name of the view definition to which you want to add an action button.
4. From the Palette, drag the Action Button component onto the canvas in the order that you want them to appear
in the application user interface.
5. Select the action button for which you want to add actions, and from the Actions section, click Add/Remove
Actions.
6.
6. To define the action behavior, in the Add/Remove Actions window, select Open view.
7. In the Selected Actions > Open View section, enter the following details:
View—Specifies the target view of the deployed application.
Presentation—Specifies the target view size and position in the deployed application.
Full Width Spans the entire width of the window. The Full Width value of the Presentation drop down requires you to define
the Launch Behavior. You can choose to open the view in a new window or in the same window.
Modal (Centered, Docked Spans only a part of the window either docked on the left, right, or center location. The Modal value of the
Left, Docked Right) Presentation drop down requires you to specify the Title and Size of the view. You can choose any size ranging
from extra small (450px) to extra extra large(1600 px).
Size—Specifies the size of the target view of the deployed application.
8. Click Save.
Related topics
Creating or modifying view definitions (see page 378)
Creating layout with Containers (see page 391)
Working with the Record Grid (see page 404)
Creating a layout using Containers

A Container is a built-in view component available in the View designer. Containers are used to define the layout for a
region of a view that can include view components or nested container.

Note
To add a container to a view definition
1. In the View designer, in the Palette pane, from the Basic components, drag and drop the container to the canvas.
2. In the Properties pane, provide the properties for the container component. The following properties are
available:
Number Divides the container area into different columns. Select the number of columns in which you want to divide the container, up to a
of maximum of six columns.
columns
Column Changes the span size of the column. By default, the columns are divided in symmetric order depending on the number of columns you
span select.
For example, if there are 3 columns, the column span is 4 for each column.
Containers are based on 12-column grid system and the sum of column spans within one container always equals 12. Minimum span for
column is 1, and the maximum span for columns is 12.
To change the column span, on the column span field, reduce or expand the column span using auto expand available on the field.
Row The Row Wrap property controls the layout of multi-column containers based on the width of the view. The default value is Small. When
Wrap you add a container to an existing container, it automatically inherits the Row Wrap property from the parent container. If you change
Row Wrap value, you are prompted whether or not to set all the child containers to match its value.
Hidden Hides the container in the view definition. You can also specify the condition when you want to hide the container.
Styles Defines the margin and border for the container. The available options are no margin, 1 pixel border, and white background.
3. Add the view components in the container as per the requirements.
Related topics
Working with view definitions (see page 417)
Creating a responsive web layout (see page 393)
Creating a custom service in Java (see page 823)

Getting your Digital Service application ready for use (see page 391)
Creating a responsive web layout

BMC Helix Innovation Suite views are rendered with a responsive layout in browsers. In responsive layouts, the
components wrap vertically when the width of the browser's viewport is not sufficient to display them as laid out in the
View designer. This feature is useful on the mobile device browsers such as smart phones, tablets, and so on. To preview
the design, you c an also simulate the layouts on various devices.
To control the size of the layout, you must configure the Row Wrap property in the container view component and the
size of the modal views in the Open View actions. You can use the following definitions to configure the Row Wrap
property and the Open View actions:
Container view components with multi-column— A container has other view components within it. Typically,
when the view is displayed, the view components are stacked vertically and the components are all wrapped.
They appear as a table with one component per row. You can specify multiple columns within the container. This
displays the components side-by-side provided there is sufficient width for the container when it is displayed at
runtime. To configure responsive web layouts, you must add a container to a view definition and set the Row
Wrap property. The Row Wrap property controls the layout of multi-column containers based on the width of
the view. The default value is Small. When you decrease the width of the view to a width less than the selected
Row Wrap value of 576 pixels, each container column after the first one wraps onto a new line.
Note
W hen you add a container to an existing container, it automatically inherits the Row Wrap property
from the parent container . If you change Row Wrap value, you are prompted whether or not to set all
the child containers to match its value.
For more information and procedure on creating a layout by using Containers, see Creating a layout using
Containers (see page 391) .
Blades and Dialogs—For responsive web layouts, you must define the size of the modal views—docked or
centered as Medium (800px), as the width of the responsive web layouts is fixed. If the width is less than the view
itself, the view spans the browser width. For more information, see To define size of the modal views using the
Open View action (see page ) .

Component sizes— The widths (in pixels) that cause components to wrap, depend on the sizes specified for Row
Wrap, and Open View. The following table provides information on exact details of the widths supported by each
size. For example, smart phones typically require Small or X-Small widths.
Size Identifier Modal View Width Responsive wrapping occurs at
X-Small 450px never
Small 650px 575px
Medium 800px 767px
Large 1024px 991px
X-Large 1200px 1199px
X-X-Large 1600px 1599px
To preview device sizes with your desktop browser

The following example demonstrates how to preview your device sizes by using Google Chrome browser on a desktop:
1. Click the icon on the top right corner of the Google Chrome browser window.
2. Select More tools > Developer tools.
3. To enable the device toolbar in the main browser page, click the icon.

4. To change the width and layout of the browser window, drag the border of the browser.
By default, the browser page is in responsive mode, which means that you can manipulate the width of the
browser window and also change the layout. For example, when the width of the page is narrow, all components
are wrapped vertically, as shown in the following image:
5. To simulate the device sizes or orientation changes on a mobile browser, use the device controls.
For example, to observe the layout for an Apple iPad in landscape orientation, from the Responsive drop down,
select iPad and click the icon.

6. To return to the normal mode of the browser, exit the developer tools.
Related topics
Creating a layout using Containers (see page 391)
Creating a view for a record instance using Record Editor

The Record Editor is a built-in view component available in the View designer. Use the Record Editor to create a view
definition for designing the user interface for a particular record instance. You can create a view definition to create,
edit, or view a record instance by adding different form fields to the Record Editor. The form fields include attachments,
associations, or a group of multiple record fields.
You can add a Record Editor while creating a view or while editing an existing view definition.
Note

To create a view for creating record instances

to use a Record Editor in a view:
https://youtu.be/JvZSHbE6fAg
2. Select the application for which you want to add a Record Editor.
3. On the Views tab, click the name of the view definition to which you want to add a Record Editor.
4. From the Palette, drag and drop the Record Editor component to the canvas in the order that you want them to
appear on the user interface.
5. In the Properties pane on the right side, click the Settings icon
, and then specify the preferences.

Record Specifies the name of the record definition to which you want to add the Record Editor.
Definition
Name
Mode Specifies the mode in which you want the Record Editor to function. To enable users to create new record definitions, select
Create.
Form Adds the record fields that should be displayed on the view definition. You can add the required record fields by using Quick Add
Contents /Remove Fields and then selecting the record fields of interest.
6. (Optional) To specify the properties for a record field, click the record field and specify the preferences in the
Settings icon
in the Properties pane on the right side.

Display Label Specifies the display name of the record field.
Value Specifies the value of the record field.
Editing Mode Specifies the layout for your record field.

To specify the layout for Select field, choose from the following options:
Dropdown
Radio buttons
Note: If the Select field is optional, the None option gets added by default.
To specify the layout for Boolean field, choose from the following options:
Switch
Checkbox

You can set the Boolean field as a check box only when the field is marked as required.
Note: By default, an optional Boolean field is always displayed as a switch regardless of whether it is configured to switch
or checkbox layout.
Disabled Disables the record field in specific conditions, such as, if you want to disable the record field at all times or when a
specific condition is met.
Hidden Hides the record field under specific conditions, such as, if you want to hide the record field at all times or when a specific
condition is met.
7. (Optional) To add form fields to the Record Editor, from the Palette, drag and drop the Record Editor Inputs to
the canvas as you want them to appear on the user interface. Form fields are used to add the record fields to the
record that is associated with the Record Editor.
To create a view for editing record instances
2. Select the application for which you want to add a Record Editor.
3. On the Views tab, click the name of the view definition to which you want to add a Record Editor.
4. From the Palette, drag and drop the Record Editor component to the canvas as you want it to appear on the user
interface.
5. Click the Settings icon
in the Properties pane on the right side, and then specify the preferences.
Record Definition Name Specifies the name of the record definition to which you want to add the Record Editor.
Mode Defines the mode in which you want the Record Editor to function. To enable users to modify existing record
definitions, select Edit .
Record ID Provides the record ID of the record definition that the users must edit. Using Click to build an expression, specify
the record ID of the record definition.
Show a read-only state for this Displays the view definition as read only. When you select this property the following options are available:
component
Read— View definition is displayed as read only.
Write— View definition is displayed in the editable mode.
Layout Specifies the layout of the view definition.
6. (Optional) To specify the properties for a record field, click the record field and specify the preferences in the
Settings icon
in the Properties pane on the right side.


Display Label Specifies the display name of the record field.
Value Specifies the value of the record field.
Editing Mode Specifies the layout for your record field.

To specify the layout for Select field, choose from the following options:
Dropdown
Radio buttons
Note: If the Select field is optional, the None option gets added by default.
To specify the layout for Boolean field, choose from the following options:
Switch
Checkbox
You can set the Boolean field as a check box only when the field is marked as required.
Note: By default, an optional Boolean field is always displayed as a switch regardless of whether it is configured to switch or
checkbox layout.
Disabled Disables the record field in specific conditions, such as, if you want to disable the record field at all times or when a specific
condition is met.
Hidden Hides the record field under specific conditions, such as, if you want to disable the record field at all times or when a specific
condition is met.
7. (Optional) To add form fields to the Record Editor, from the Palette, drag and drop the Record Editor Inputs to
the canvas as you want it to appear on the user interface. Form fields are used to add the record fields to the
record that is associated with the Record Editor.
Note
In a view, Save and Cancel buttons are not created automatically. You need to add the action buttons (see
page 384) in the Record Editor and define the actions for the buttons.
To add form fields to a Record Editor

Form fields are used to add the record fields to the record that is associated with the Record Editor.
1. From the Palette, drag and drop each form field to the canvas in the order that you want them to appear on the
user interface. You can add multiple form fields to a record editor. You can add form fields such as add multiple
field values (see page 400), add a group of record fields to a record editor (see page 400), add attachments (see
page 401)or associations (see page 401).

To provide multiple field values in a view

You can select multiple values for a field in the Record Editor by using the multiple selection property. The multiple
selection property is available only for a field that has a named list associated with it.
For example, a record contains a field Location and in the record definition, the Location field contains a named list.
When the Location field is used in the Record Editor in a view, the multiple selection option is available for the field and
the field can have more than one value.
1. In the View designer, select the Record Editor and select the field to which you want to provide multiple
selection.
2. Select the check box for the Enable Multi-Selection property and save the view.
The following is a sample view of a field with multiple selection enabled:
To add a group of record fields to a Record Editor

to use the select group field in a Record Editor:
https://www.youtube.com/watch?v=EcMrG5AyzWg
You can add a group of dependent record fields to a Record Editor by using the Select Group field. For example, in a view
definition, if a field is used to specify the name of the country, you can add a dependent field to specify the time zone. So
that when you select a country, the time zone field has the time zone value for the specific country.
1. From the Record Editor Input area in the Palette, drag and drop the Select Group form field to the canvas as you
want it to appear on the user interface.

Disabled Disables the record field in specific conditions, such as, if you want to disable the record field at all times or when a specific condition is
met.
Hidden Hides the record field in specific conditions, such as, if you want to disable the record field at all times or when a specific condition is
met.
Field Set Provides the fields that are added to the group. Using the Add Dependent Field, specify the label, named list for options, and the record
field for storing the value.
For the second dependent field onward, the following properties are visible:
Source Record Definition—Displays the name of record definition for the named list.
Field For Filtering Option Values—Used to filter the named list based on the selected field.
To create a view for adding attachments

The Attachment view component is used to add an attachment or to view an attachment in a view definition. You can
attach only one file to an attachment field. The maximum file size defined in the record definition is used as the size limit
for the attachment. You can make the attachment field Full Text Search (FTS) and Multi-Form Search (MFS) aware by
using the Searchable setting for the attachment field in the record definition. For more information about FTS, see
Leveraging full-text search capabilities in your application (see page 287).
You can upload any type of file such as .txt, .gif, .pdf, .png and so on. When you sort on the attachment field, the
attachments are sorted by the attachment name.
Related topics
Configuring actions by using an action button (see page 384)
Creating a layout using Containers (see page 391)
Creating a view for associating records (see page 401)
Creating a view for associating records

You can use the Association element in a view definition to design a user interface where you can create or edit
associations between the record definitions. The Association element consists of the following modes to design the
layout for selecting the record instances while creating or editing associations.
Mode Description Example
View
Creates a
new view to
display the
record
instances
for creating
associations.
Supports
one-to-one,
one-to-

Mode Description Example
many, many-
to-one, and
many-to-
many types
of
associations.
Dropdown
Displays the
record
instances in
a drop-
down list to
create
associations.
Supports
one-to-one
or many-to-
one type of
association.
Filters and
displays the
records at
runtime
based on
the record
selected in
the related
association
drop-down
list.
You can add the Association element while creating a view or while editing an existing view definition.
Note
To design a view for creating record associations:
1. Log in to BMC Helix Innovation Studio and navigate to t he Workspace tab.
2.
3. From the Palette, drag the Association element to the Record Editor component.
4. In the Properties pane, click the Settings icon and then specify the properties.
Record Definition to Specify the name of the record definitions for which you want to create the association view.
Associate
Association to Use Display the list of associations available for the record definition.
Association Editing Mode Select the layout for your association and choose from the following options:
Views
Dropdown
Note: The Dropdown option is available only for associations with cardinality as one-to-one or many-to-one.
Display Label Specify the label for the association component.
Disabled Specify to disable the record field under specific conditions, such as, at all times or when a specific condition is met.
Hidden Specify to hide the record field under specific conditions, such as, at all times or when a specific condition is met.
For a View mode, provide the following properties:
View for Selecting Specify the view for selecting the existing associated records.
Associated Records
View for Creating Specify the view to create new associations.

Associated Records
Show/Hide Fields in Add the record fields that should be displayed on the view definition for the associated records.
Preview
For a Dropdown mode, provide the following properties:
Field to Display Specify the field in the associated record definition whose values should be displayed in the drop-down list. For
example, Company Name.
Filter by Association Filters and displays the associated records at runtime based on the record selected in the related association drop-
down list.
Record ID Provide the record ID of the record definition that the users must edit. Using Click to build an expression, specify the
record ID of the record definition.
5. Save the definition.
Scenario
An application uses three record definitions: Ticket, Company, and Support Group. The record definition
Ticket is associated to the Company and the Support Group record definitions by using the following
associations with the cardinality of the association as many-to-one:
Ticket to Company (many-to-one)
Ticket to Support Group (many-to-one)
Company to Support Group (many-to-many)

The following examples demonstrates how to create both view-based and dropdown-based associations.
Example 1: To create view based associations

The following video demonstrates an example of how to create view based associations:
https://youtu.be/dJPbXfdijMg
Example 2: To create drop-down based associations

The following video demonstrates an example of how to create drop-down based associations:
https://youtu.be/ZwSiBI4lKL8
Related topic
Working with the Record Grid

A Record Grid is a built-in view component available in the View designer. The Record Grid component provides the
following features:
displays the record instances in a tabular format on the user interface of the deployed application
displays the fields of the associated record definition on the user interface of the deployed application
enables users to sort the rows in a grid
enables users to filter the values in the grid and display only the rows that match the filter condition
enables users to filter rows by cell selection
edit multiple records at a time
You can add a record grid while creating a view or while editing an existing view definition.
The following image shows a sample Record Grid:
Note

To add a Record Grid to a view definition
2. Select the application to which you want to add a Record Grid.
3. On the Views tab, click the name of the view definition to which you want to add a Record Grid.
4. From the Palette, drag and drop the Record Grid component to the canvas as you want it to appear on the user
interface.
in the Properties pane on the right side, and then specify the preferences. The following table provides
information about the properties:
Mode Specifies whether the record definition should be displayed in record mode or association mode. If you select the record mode, provide
the following details:
Record Definition Name—Specifies the unique name for the record definition. You can also select a form created in the BMC
Remedy Developer Studio by using All Records tab.
If you select the association mode, provide the following details:
Record Definition to Show—Specifies the record definition that must be displayed in the view definition
Association to Use—Specifies the relationship with the record definition
Associated Record ID—Specifies the ID of the record that you associate
Enable Enables selection of single or multiple record rows on the application.

Row
Selection
Enable Enables column filtering within the record on the application.

Filtering
Initial Specifies the column with which the record instances will be sorted initially before the application is deployed. You can select the
Sort column and whether you want to sort the column in an ascending or descending order. By default, no column is selected. For example,
Column if you select the Display ID column and set the sorting in ascending order, at runtime the records in the Display ID columns are soretd
and will be displayed in ascending order.
Initial Provides the filters that will be applied to the application at runtime to display only those record fields that match the filter condition.
Filters The Initial Filters provides following options to add filters in the deployed application:
Basic—You can select values from the list of available filters to create a filter condition.
Expression—You can build an expression, such as the view component properties, keywords, view input parameters, or static
values to create a filter condition.
Add Defines the columns that will be displayed by default on the deployed application. You can add or remove the columns on the Record
/Remove Grid by selecting the available fields from the record definitions and from the associated record definitions.
Grid
Columns

6. Edit the column properties and click Save. You can modify the following column properties:
Column header Specifies the header of the column. By default, the field name is displayed as the column header. If required, modify
the column header.
Visible by default Displays the column on the view by default.
Sorting enabled Enables sorting of the column at runtime on the deployed application.
Filtering enabled Enables filtering of the columns at runtime on the deployed application.
Make column value as action Configures the column value as an action button. To add an action, click Add/Remove Actions and add the actions.
button
You can also edit the properties for the fields by using the edit option on the fields.
7. (Optional) You can add the action buttons to the Record Grid. To add an action button, drag-and-drop the action
button to the Drop Action buttons here area on the Record Grid and enter the properties of the action button.
8. (Optional) You can build an expression, such as the view component properties, keywords, view input
parameters, or static values. To build an expression, from the Initial Filters list, click Expression > Click to build an
expression. From the list of available values, select the values that you require and then click OK. For more
information, see Using the Expression Editor (see page 383).

To verify the Record Grid, preview the view definition.
Example 1: To add associations to a Record Grid

Example
Consider your application uses three record definitions such as Ticket, Company, and Support Group. The record
definition Ticket is associated to Company and Support Group record definitions by using the following associations with
the cardinality of the association as many-to-one:
Ticket to Ticket (many-to-one)
Ticket to Company (many-to-one)
Ticket to Support Group (many-to-one)
Add the columns from the associated record definitions to the record grid. For a detailed step-by-step procedure, see To
add a Record Grid to a view definition (see page 405).
Use this example to add Company Name and Group Name fields from the associated record definitions to the record
grid.

1.
2.
3.

4.
5.
Example 2: To enable editing of multiple records in a Record Grid

Example
You can enable editing of multiple records in a record grid by using the Edit Records action. This causes a built-in dialog
to appear that allows the user to specify values to be applied to all selected records. The fields that cannot be edited
across the selected rows do not appear. The record editor updates only those records that are visible in the grid. For
example, if there are 50000 records loaded in the record grid, but only 50 records are visible in the viewport, the record
editor edits and updates only those 50 records that are visible in the viewport.
To enable editing of multiple records in a grid, add an action button to the record grid and label it. For more information
on how to edit multiple records in a grid, see Configuring actions by using an action button (see page 384).
In the deployed application, the end user can edit multiple records as follows:
1.

2.
3.
Example 3: To create initial basic filters

Example
Create initial basic filters to display only the records that match the filter condition during runtime. For a detailed step-by-
step procedure, see To add a Record Grid to a view definition (see page 405).
Use this example to create initial basic filter to display tickets created by Company A.
1.

2.
3.
4.
Example 4: To create initial expression filters

Example
Create initial expression filters to display only the records that match the filter condition during runtime. For a detailed
step-by-step procedure, see To add a Record Grid to a view definition (see page 405).
Use this example to create initial expression filter to display tickets created by Company A.

1.
2.
3.

4.
5.
Example 5: To create filter presets

Example
Developers can now define filter presets that can be used in the deployed application. These filter presets are saved in
the view definition and are visible in the deployed application. The users can create their own filter presets. They can
either modify a shared filter preset by adding, removing, or editing the filters included in the preset. Users can also define
multiple filters and save them as a private preset. The private presets are stored in user preferences.
The following example demonstrates how to create and modify a filter preset.

1.
2.

3.
4.
5.
6.

Related topics
Creating layout with Containers (see page 391)
Creating a view for localized field values

You can use the Localize Text element in a view definition to design a user interface to create or edit values of a
localizable text field.
To create a view for localized field values
3. Click the Views tab and then select New > Container.
4. In the new view definition, from the Palette, drag the Localize Text element to the Record Editor component.
5. In the Properties pane, specify the properties such as field name, display label and so on.
6. Click Save.
A view definition is created that enables a user to create or edit field values at run time in the localizable field by clicking
the Localize link. For example, see the following sample view created with Department as the localizable field:
Note
The view definition displays the Department field values based on the user's current locale. If locale values are
not defined, Department field values from the default locale are shown.
Related topic
Localizing field values (see page 788)
Enabling extension of application definitions

You can develop applications on BMC Helix Innovation Suite that are customizable, non-customizable, or extendable (see
page 290). You can create extendable applications so that developers can leverage the out-of-the-box application
definitions to make additive changes in the definitions such as adding new fields.

Extendable applications ensure that the out-of-the-box definitions remain unchanged so that the customizations are not
lost when your application or server is upgraded. You can easily move the customizations to other environments by
creating install packages (see page 766) and deploying the install packages to other environments (see page 773).
To enable extension in a view definition

Add the Extension Container component to the out-of-the-box view definition. You can add multiple Extension
Containers to a view defintiion.
2. Select an application in which you want to extend a view.

Example: Lunch order application
3. Click the Views tab, and select the view that you want to extend.
Example: Restaurant Information Create view
4. Select the Record Editor component on the canvas.
5. From the Palette, drag the Extension Container component inside the Record Editor component on the canvas.
The Extension Container component cannot be used with components other than the Record Editor component.
6. Click the Settings tab.
7. In the Name field, provide a meaningful name that describes the fields that will be displayed in this container.
Example: Add restaurant details
8. Click Save.
You must repeat this procedure for all view definitions that you want to enable for extension.
How extendable application definitions are used

After you enable extension in a view definition, developers can leverage the out-of-the-box definitions to make additional
changes by creating the following definitions:
Extension record definition—A regular record definition with new fields that you want to add to the record
definitions and view definitions that are being extended.
Example: Additional Restaurant Information record definition with new fields
Extension association definition—A direct association between the record definition that is being extended and
the extension record definition.
Example: Association between Restaurant Information definition (that is being extended) and Additional
Restaurant Information (extension record definition)
Extension view definition—A view definition that displays both the fields in the view that is being extended and
the extension record definition.
Example: Additional Restautrant Information Create to include fields from Restaurant Information and Additional

Restaurant Information
For more information about how applications can be extended, see the example of extending Foundation
definitions (see page 704).
Related topics
Extendable application definitions to allow additive changes (see page 290)
Glossary (see page 52)
Facilitating data entry through named lists

In BMC Helix Innovation Studio, a named list is a reusable list of data that you can associate with a record field to make
data entry faster and more accurate. Use named lists to assist with data entry on application UI fields in BMC Helix
Innovation Studio. After you associate a named list with a record field, you can enter the named list name in a field and a
list of values are displayed.
Named lists offer the following advantages:
Restricts the input to a specified set of valid options, which eliminates input error for the values entry and
ensures consistency.
Speeds up the speed of data entry by allowing the selection of options rather than manual value entry.
You first create a named list in BMC Helix Innovation Studio, and then associate that named list with a record definition
or a view definition.
Note
Creating a named list

for creating a named list:
https://youtu.be/pHWJ0IpwlZA
2. Select the application for which you want to add a named list.
3. On the Named Lists tab, click New.
4.
4. On the Create Named List window, specify the properties for the named list.
Name of List Provide a unique name of the list. The name must start with an alphanumeric character. Only alphanumeric characters, hyphens,
dashes and spaces are allowed in the name.
Record Identify the record definition to associate the named list. Note: The Application/Library scoped definitions are marked with an
Definition asterisk ( * ). Ensure that you follow the guidelines listed in Guidelines to define scope for the definitions (see page 319) before
you select these definitions.
Condition to Define the condition to control which items appear on the named list in the application.
Filter List
Results
Label Field to Provide the name of the field that you want displayed to the user.
be Displayed to
the User
Source Field for Define the value to associate the named field with the record. This name list is displayed on the view definition.
Value of If you select different fields for Label Field to be Displayed to the User and Source Field for Value of Selection, see s834636177
Selection (see page 417).
Scope Option to define the scope for a named list definition. This option further contains the following options:
/Customization
Application/Library (default)—To limit the use of the definition within the same Digital Service application or library.
Options
5. Save the named list.
Selecting different fields for label and source

If you select different fields for Label Field to be Displayed to the User and Source Field for Value of Selection, you must
add a field to the selected record definition to store the label value and create a rule to populate label value. So that
when you use the record definition that has support group field with this named list associated in a record grid, you can
add label field for support group and filter the record grid data based on the label value.
If you do not add a field to store the label value and rule to populate label value, you use the record definition in a record
grid in a view definition. On the view definition, when you apply filter on the support group field, the search result does
not displays (displays zero row) the result for the support group field.
Example:
Consider the following definitions:
Record definition Ticket—consists of Customer ID field (in Ticket) is bound to named list Customers
Named list definition Customers—consists of different values for Label Field to be Displayed to the User
and Source Field for Value of Selection and the definition uses record definition Ticket
View definition—consists of a record grid (for Ticket)
Using the view definition if you want filter and sort customers (by Customer name), you must fulfill the following
considerations:
In the record definition Ticket, you must have two fields:

for storing the ID
for storing the Label (Customer Name)
For creating record instances (for record definition Ticket), record editor you use should only expose the
Customer ID field (which is displayed as a dropdown list of Customer Names).
A rule to update the Customer Name field when a Ticket is created or updated. Following are the sample
images for creating rule:
Sample image
Rule
Action properties
Trigger properties
Rule properties
Following is the sample JSON for creating rule:
{
"version": null,
"lastUpdateTime": "2016-11-03T15:48:16.264+0000",
"lastChangedBy": "jonnie",

"owner": "jonnie",
"name": "com.example.taskmanager:Update Ticket Customer Name",
"tags": null,
"description": null,
"overlayGroupId": "1",
"guid": "rxGAA5V0GEZNIAO6COPWO5HAFSYUYX",
"triggerEvent": {
"resourceType": "com.bmc.arsys.rx.services.rule.domain.RecordTriggerEvent",
"eventTypes": [
"ON_UPDATE",
"ON_CREATE"
],
"executionOrder": 500
},
"isEnabled": true,
"recordDefinitionNames": [
"com.example.taskmanager:Ticket"
],
"qualification": null,
"actions": [
{
"resourceType": "com.bmc.arsys.rx.services.rule.domain.CustomRuleAction",
"name": "Get Record",
"actionTypeName": "getRecord",
"inputMap": [
{
"assignTarget": "recordDefinitionName",
"expression": "\"com.example.taskmanager:Customer\""
},
{
"assignTarget": "recordID",
"expression": "${ruleContext.Customer ID}"
}
],
"outputMap": [
{
"assignTarget": "Customer Name",
"expression": "${actionResult.output.10001995}"
}
],
"runAsUser": null
}
],
"overlayDescriptor": null,
"allowOverlay": false
}
When add a field to store the label value and create a rule to populate label value, record grid (for Ticket) displays
the Customer Name column which allows you to filter and sort customers.
Associating the named list

After you create a named list, you associate the named list with a record definition or a view definition.
To associate the named list with a record definition

4. Select the record definition to which you want to associate the named list.
5. Select the field name for which you want to define a named list.
6. Click the Settings icon in the Properties pane.
7. From the Named list drop-down list, select the named list.
8. Click Save.
To associate the named list with a view definition
3. On the Views tab, click the name of the view definition to which you want to associate a named list.
4. From the Palette pane, drag and drop the Text component to the canvas as you want it to appear on the user
interface.
5. Click the Settings icon in the Properties pane .
6. From the Field Name drop-down list, select the record field with the named list association.
7. Click Save.
Related topics
Creating the definitions for a tailorable Digital Service application (see page 323)
Defining the application business logic through processes

BMC Helix Innovation Studio provides Process designer, a graphic-based interface, to create and customize business
processes of a Digital Service application. Processes are the named services of an application. Business logic is the core
of each application and a process is an application service that performs application business logic and achieves the
application purpose. You can invoke business logic for an application by calling processes of that application. Each
process has a name, inputs, and outputs. For example, Approval is the sole service of Approval application, that can be
invoked by calling Approval process through REST API or through metadata.
You can design processes meant to accomplish a business goal by using the Process designer. You can also use RESTful
APIs to modify processes. APIs give you more power and control over managing processes and performing actions that
might not be possible through the UI.

Note
Before you create a process, ensure the following:
You have an understanding about the process objective, required inputs, and desired output.
You have all the elements required to create or modify your process. If the required element in not available, you
may request your developer to create and deploy it. For more information about process elements and an
example of a process created in BMC Helix Innovation Studio, see Process designer elements (see page 429).
Best practices for designing a process

Following are some of the best practices that you should follow when designing a process:
Do not create big process with lot of steps and actions. Process definitions are to visually represent a business
procedure. When the process definition becomes too big, it starts to lose the benefit of a visual workflow. Use a
modular approach to divide the steps in smaller sub processes. You can do this using the Sub Process or Call
Activity element.
Ensure that you have properly thought through between writing code (using @Action) and creating a process
definition. Consider the following scenarios when selecting the correct option to write code or use Process
designer:
If the business logic needs to be visually described or if your users can configure it, design a process using
the Process designer.
Using service task to perform self sustained unit of work, and let process manage states.
You can write the code if it is faster to implement a complicated logic than using the Process designer.
When you create a new process, concentrate on laying out the flow first. Do not focus too much on configuring
each element. When the flow is completed, save the process and then continue to configure each element one
by one.
Workflow for creating a process

The stages involved in creating a process is show in the image below:
To access the Process designer and create a process
2. Select the application in which you want to create a process.
3.
3. In the application, click the Processes tab.
4. Click New to create a new process definition that will represent your process.
The Start and End elements appear on the canvas by-default. A process can have only one Start and End element.
If you want to configure the Start event or the End event), select the element and enter the required properties
in the Properties panel.
To configure a process
You can configure process definition properties such as the process name, permissions for users who can run the
process, and variables associated with the process.
Perform the following steps to configure a process:
1. On the Process designer console, navigate to Process Information section, the Properties panel.
2. Configure the properties as described in the following table:

Name Name the process such that the purpose can be easily identified. For example, Employee On Boarding process.

2.
Note: Process name should only alphanumeric characters, hyphens, dashes and spaces.
Description Provide description that briefly explains the process objective.
Scope/Customization Option to define the scope for a process definition. This option further contains the following options:
Options
Application/Library (default)—To limit the use of the definition within the same Digital Service application or
library.
Public—To enable the definition to be used by all the smart applications or library and allow customizations for
this definition.
Enabled Select this option if you want to users to start using the process.
Run as Allows all process Service Tasks (see page ) to execute with the permission of the selected user role
3. At the top right corner of the Process designer console, click Save.
To add process permissions

You can set process permissions for a group and individual role. You have two levels of permissions for processes - Read
and Execute. Following are the details about the permissions levels:
Read: This permission gives you the privilege of viewing the process definition details. You can can view each flow
element and the data bound with that element. Anyone who can view the process definition can also execute the
process.
Execute: This permission allows you to run the process. However, you cannot necessarily be able to view the
detailed configuration of the process definition.
Tip
Assign the process Read permission to a user, such as manager, who needs to view the business process
details of your application. The manager may not always be an administrator. For users other than the
manager, assign the process Execute permission.
Perform the following steps to add process permissions:
1. Click Edit in the Permissions section.
2. In the Edit Permissions for window, click Add Permission.

3. In the Type column, select Role or Group as required.
4. In the Group column, select the particular role or group.
5. Select the type of permission - Execute or Read.
6. To add another permission, repeat steps 2 through 5.
7. Click Save.
To add process variables

A process has the following parameters that you have to configure depending on the purpose of your process:
Input Parameter values that you need to provide when starting a process instance. An input variable can be optional or required.
variable
When you add a required input variable with Text data type or Record data type, the context key for the process is set automatically.
A context key gives a business reference to a process instance and can be used as an identifier for a process instance. When you look at
the process instance in the Manage Process dashboard, you can quickly identify the process instance, and you can relate the process
instance to the business use case. For example, an Approval Process that has a context key as HPD0002340 indicates that the Incident
request HPD0002340 started the Approval Process.
If a process instance has multiple required input variables, the first input variable is used as the context key.
If a process does not contain any required process variables of data type Text or Record to start the process, a context key named
instance is automatically added at the process run time. The context key is displayed in the Manage Processes dashboard.
If you have multiple required input variables and you delete the input variable that is used as the context key, the context key is assigned
to a next suitable input variable.
Output Parameter that a process instance returns on process completion.

variable
Perform the following steps to add process parameters:
1. In the Properties section, click Add/Remove Variables.
2. In the Add/Remove Variables window, click Add Variable.

3. Enter the variable field details as described in the following table:

Field Description
Name
Name Specify a suitable name for the variable.
Variable ID Specify an unique ID for the variable. This value must be numeric.
Variable Specify if the variable is an input/output parameter or a local variable. For an input parameter, if you select the Variable Type as Input
Type Required and Data Type as Text or Record, a context key is set automatically. See context key (see page 425).
Process input parameters and output parameters are the interface of a process. When starting a process, data is passed to the input
parameters and when the process is complete, data is received from the output parameters. The only exception to this is Record data
type.
Process local variable facilitates process execution. It can be used to capture the result of a process activity such as signal input of a
Receive Task or loop data item for a multi-instance loop.
Description Provide a description that clearly indicates the purpose of this variable.
Data Type From the dropdown list, select the required data type for the variable. See Process variable data types (see page 426).
Notes:
If you select Record as the Data Type, you must select a Record definition that you want to associate with the parameter.
If you choose Selection as the Data Type, you must specify the options that are displayed in the selection list.
(Optional) If you select Object as the Data Type, you can select the Document definition that you want to associate with the
parameter.
Default Specify a value that you want to appear by default for the parameter.
Value
4. (Optional) To add more parameters, repeat step 2 through step 3.
5. Click Save.
Process variable data types

The data types Boolean, Date, Date/Time, Decimal, Floating, Integer, Object, Record, Selection, Text, Time, and Document
are supported for the process variables.
The following table describes the record data type, the object data type, and the document data type:

Data type Description
Record Use the Record datatype to hold a record instance. For the Record data type, a parameter is passed by reference. When a parameter is passed by
reference, the caller and the receiver use the same variable for the parameter. If the receiver modifies the parameter variable, the effect is visible to
the caller variable.
If the record data type is used as a process input parameter, and a record instance is updated by the process, the caller automatically receives
the updated record instance when the process returns. You do not need to define record as the process output parameter in order to
receive an updated record instance.
If you want to share a process by different record definitions, you can use Sample Record Definition to associate a record data type to more
than one record definitions.
To use the Sample Record Definition, on the Add/Remove Variables window, add a variable, select the datatype of the variable as
Record, and select Use Sample Data.
Sample Record Definition allows to refer record fields (however the record definition name of the record is not validated at the
process runtime). If a record instance does not have a field referenced by a process, a null value is used.
It is recommended that record definitions that share the same process definition are inherited from the common base record definition.
When you use Sample Record Definition, it is the base record definition, which ensures all fields referenced in the process definition are
available to all inherited record definitions. For more information on record inheritance, see Inheriting an existing record definition to a new
record definition (see page 338).
Object Use the Object datatype to hold an object. For the object data type, a parameter is passed by value. When a parameter is passed by value, the caller
and the receiver have two independent variables with the same value. If the receiver modifies the parameter variable, the effect is not visible to the
caller.
(Optional) Use a Document to hold a JSON schema for an object. When you associate document with an Object type variable, you can expand the Object
Object variable as per the Document schema and use the individual attributes (such as simple object, nested object, or array of objects) in a process
associated expression. For more information, see Defining document definitions (see page 497).
with
The following images demonstrate how to access individual attributes within a simple objects or an array of objects.
Document
Accessing attributes in a simple object:
Accessing attributes in an array of objects:

Data type Description
Notes:
To access all the elements in an array, you must use a multi-instance loop.
You can associate an Object with a document only if the runtime assigned value to an Object is in the JSON format.
To add process elements

Process designer elements are the building blocks of any process. These elements perform certain actions depending on
their configuration. You drag the elements onto the canvas. For information about using Process designer elements, see
Process designer elements (see page 429).
Adding capabilities to your process

After you create the process, consult the following topics for additional capabilities you can add to your process.
Next task Reference
Create process steps from start to end to create a business process flow, provide the process flow
Creating process steps or activities (see page
order, loop through a data list, and control the execution of a process flow.
434)
Creating and controlling process flows (see

page 442)
Integrate with other applications, refactoring a large process in smaller readable components,
Call activity (see page )
model a user performing a task so that a process resumes once the task is complete.
Sub-Process (see page 437)
User task (see page 435)
Add wait states, compute expression value to use the expression value in a process flow, add text
Adding a Timer event to a wait step (see page
annotations that provide additional information about a process, and notify process users.
446)
Using an annotation (see page 447)
Sending a user message from a process (see

page 470)

Next task Reference
Create or update record instances and define a relationship between the record instances in a
Creating or modifying record instances using
process flow.
Record Service Tasks (see page 457)
Creating associations using Association Service

Task (see page 468)
Handle errors in a process. Handling errors in a process (see page 452)
View the process dashboard and manage process execution such as start a process, stop a process, Managing processes by using the Manage Processes
or resume a process. dashboard (see page 474)
Related topics
Process designer interface (see page 63)
Expression Editor (see page 499)
Process designer elements
Process designer uses a combination of the default Business Process Model and Notation (BPMN) elements and BMC
extended elements. For example, the Process designer uses Service Task element in BPMN to create Record, User
Message, Expression, and Association elements. These elements are available in the palette of the Process designer UI.
You can drag and drop the desired element on the canvas to design your process.
Note
Some of the standard BPMN elements that BMC has used are described in the following table:
Element Category Element Name Symbol Description
Events Start (see page 422) Indicates where a process or sub-process starts.
End (see page 422) Indicates the end of a process or sub-process.
Timer (see page 446 Interrupts a wait step and let the process make a decision about how to proceed after
) the wait step times out.
Error Boundary (see Captures errors and exceptions within a process and identifies the path that should
page 452) be executed after the Business error or exception is captured.

Error End (see page Displays the business errors that occurs in a process.
452)
Activities (see page Call Activity (see Calls another process. It is for application integration and component reuse.
434) page )
Connector (see Integrates an application with third party systems.

page 617)
User Task (see page Represents user performing a task. The Task is represented by a record. The task is
435) considered as complete if the completion criteria is satisfied.
Receive Task (see Represents a wait step in the process that waits for the arrival of a message.
page )
Sub-Process (see Describes a detailed sequence.

page 437)
Service Task (see Models a Service Task, which invokes a Java service method that is exposed as an
page ) Action Type through @Action annotation.
Web Request (see Integrates an application with a RESTful web service in a codeless way.
page 604)
Gateways (see page Parallel (see page Models concurrency in a process. It forks into multiple paths of execution or joins
442) 442) multiple incoming paths of an execution.
Exclusive (see page Models a decision in the process, and the conditions on exit paths.
442)
Sequence Flow Sequence Flow (see Sequence element connects two elements in a process flow.
(see page 442) page 442)

Annotations (see Text Annotation Provides additional information for the reader of the process diagram.
page 447) (see page 447)
Service Tasks provided by BMC are described in the following table:
Assignment (see Suggest Assignee (see page Automates the task assignment by using machine learning.
page 478) 478)
Cognitive (see page Suggest Category (see page Automates the manual task of data categorization by using machine
478) 478) learning.
PIN (see page 486) Verify Pin (see page 486) Verifies if the PIN value provided by a user matches the PIN value set
for that user.
Records (see page Create Record (see page Creates a record instance for a specified record definition.
457) )
Delete Record (see page Deletes a record instance for a specified record definition.
)
Get Record (see page ) Retrieves a record instance for a specified record definition.
Get Records by Query (see Retrieves a set of record instances based on a specified query.
page 459)
Get Security Label (see Retrieves a security label for a specified record definition.
page )
750999216 (see page 429) Deletes a security label for a specified record definition.

To identify if the security label is updated, see Identifying updates to

the security label (see page 460).
Update Record (see page Updates a record instance for a specified record definition.
)
Set Security Label (see Restricts access of a user, group, or a role to a record.
page 460)
To identify if the security label is updated, see Identifying updates to
the security label (see page 460).
User Message (see Send Message (see page Sends a notification about the status of a particular activity.
page 470) )
Send Message by Template You can use the existing templates to send notifications.
(see page 470)
Show Alert (see page ) Used to display an error, warning, note.
Associations (see Associate Child Records Used to associate a child record instance with its parent record
page 468) (see page ) instance.
Associate Records (see Used to associate the two record instances with the relevant ids.
page )
Disassociate Records (see Removes the association between the two records.
page )
Disassociate All Records Removes the association between all the records.
(see page 468)
Document Create Document (see Accesses individual attributes within the document schema
page 488)
Expressions (see Compute Value (see page Used in the workflow to calculate a value by performing an arithmetic
page 473) 473) operation.

Example of using Process designer elements

Consider a purchase process as an example. The purchase process involves a manager review to initiate a procurement
process. If the item is available, it is shipped to the customer and a notification is sent to the customer. If the item is not
available, the order is canceled and the customer is informed about the cancellation.
A purchase process is shown in the following flowchart:
The purchase process can be designed in Process designer using elements available in the palette of the Process
designer UI. The following image illustrates the purchase process designed using Process designer:

The following table describes the various elements used in the purchase process:
No. Element Description

Type
1 Start Denotes the starting of a process

Event
2 User Task Manager review requires a human intervention. Hence, a user task element is used here.
3 Sub After the manager review is complete, and the completion criteria is fulfilled, a procurement process is triggered. Since procurement is a
Process larger process in itself, a Call Activity element is used here.
4 Exclusive Depending on the availability of the item, the process progresses further. For a decision to be taken and further direct the process to an
Gateway appropriate activity, an exclusive gateway is used.
5 Parallel If the item is available, the shipment activity has to be triggered and also the customer has to be informed about the shipment. Both these
Gateway activities must happen concurrently, so a parallel gateway is used.
5a User The customer has to be notified about the shipment date, a User Message Service Task is used.
Message
5b User Task Shipping an item needs human intervention. Hence, a user task element is used.
6 Parallel The end result of shipping an item and informing the customer should converge for the process to end. The parallel gateway is used is join
Gateway the two paths of execution.
7 User If the item is not available the customer has to be informed about non availability. A user message element is used to trigger this
Message notification.
8 Update If the item is not available the order has to be canceled. Update record element is used process the cancellation activity by setting the
Record Status field of the record to Cancel.
9 Delete After the order has been canceled, it must be deleted. A delete record element is used to delete the order.
Record
10 End Event Denotes the completion of a process
Related topic
Creating process steps or activities

A process has a sequence of steps that flows from start to end. In Business Process Model and Notation (BPMN), a step
is referred as an activity. Activities are the building blocks of a business process. You can use activities with other process
elements to create a business process flow. In Process designer, use the Activities elements to include an activity in a
process. You can drag these elements to the canvas according to the business logic that you want to create.
Types of Activities
You can use the following types of activities in a process:
Call Activity (see page 435)
User Task (see page 435)
Receive Task (see page 436)
Sub-Process (see page 437)
Service Task (see page 437)

Call Activity
A Call Activity element calls another process referring to a process definition that is previously defined and is available
for reuse or application integration. When a process execution arrives in the Call Activity , a new execution is created.
The new execution is a sub-execution of the execution that arrives in the Call Activity . This sub-execution is then used to
execute an instance of the process referred by Call Activity , thereby creating parallel child execution within a regular
process. The main execution waits until the called process is completed, and then the original process continues. Call
Activity is used in scenarios such as:
Application integration, such as Incident application call in Task Manager application
Business procedure reuse
Runtime determination of process to be invoked, such as Approval Flow, where different approval request are
used in different Approval Flow.
Call Activity properties and their description

View the properties and their description
Called Option to specify the process to be called:

Process
Select Process: You can select a predefined process that is invoked by the Call Activity.
Build Expression: You can build an expression that resolves to a process definition name or a process definition GUID that is invoked by
the Call Activity. You can get the process definition GUID in the Process designer JSON view. If the expression is resolved to a process
definition name, ensure that you update the expression when the process definition is renamed.
Sample When the Called Process is configured as an expression, Sample Process property is displayed. This is an optional property. It allows you to
Process configure the input map and output map of the called process in the Process designer, even if the process to be called is decided at the runtime.
INPUT Parameters of the referenced process that were specified as required. You must build an expression to provide values to the required
MAP parameters so that the system can execute the referenced process.
OUTPUT Process parameters that you want to obtain as output values from this element. You can build an expression for assigning an output value to a
MAP process variable.
MULTI See 834636269 (see page 434).

INSTANCE
LOOP
User Task
The User Task element models a user performing a task. The task is represented by a record. The task is considered as
complete if the completion criteria is satisfied. You can use a Timer event with the User Task activity. The Time event
interrupts a wait step and lets the process make a decision about how to proceed after the wait step times out. For more
information about the Timer event, see Adding a Timer event to a wait step (see page 446).
User Task properties and their description

Mode Option to use a new record or an existing record to represent a task. You can select from the following options:
Create Record
Update Record

Record Name of the record definition for which you want to represent a task.
Definition
Record ID The record instance or the record instance ID that you want to update. If a task is represented using an existing record, you must
configure the record ID. The record instance if passed can only refer to a transaction entry (record entry passed from a rule to a process
parameter).
This field is available only if you select Update Record in the Mode field.
Completion Criteria that specifies when this user task is considered as complete. The criteria is a condition expression that evaluates fields of a task
Criteria record.
INPUT MAP Fields of the record definition that are assigned a value using the expression builder. You can set the value of a record field through a
process parameter. This value is used to create or update a record instance.
For example, a record definition has a field called EmployeeName and the process has a parameter called EmpName. You can build an
expression that assigns EmpName to the field EmployeeName. As the EmployeeName and EmpName parameters are mapped by the
expression, the process uses the value in the EmpName parameter to set the EmployeeName field of the record instance that the process
creates or modifies.
OUTPUT MAP Process parameters that you want to obtain as output values from this User Task element. You can build an expression for assigning an
output value to a process variable.
CANCELLATION Parameters that you want to set if the user task is cancelled. A user task can be cancelled in the following conditions:
INPUT MAP
When the user task is active and the process instance is cancelled
When the user task is active and an associated timer times out.

INSTANCE
LOOP
Receive Task
A Receive Task element models a wait step in the process that waits for the arrival of a message. It is typically used with
connectors, where the connector initiates an asynchronous request to the integration target. Receive Task waits for the
integration target to finish the request and call back. Integration target uses SignalProcessInstanceCommand to call
back the Receive Task and then the process execution continues. SignalProcessInstanceCommand has correlation ID
that uniquely identifies the Receive Task of a process instance. For more information about
SignalProcessInstanceCommand, see Platform Application Java API Documentation (see page 1004).
You can use a Timer event with the Receive Task activity. The Time event interrupts a wait step and lets the process
make a decision about how to proceed after the wait step times out. For more information about the Timer event, see
Adding a Timer event to a wait step (see page 446) .
The following images illustrates an example of a Receive Task:

Receive Task properties and their description

SIGNAL INPUT PARAMETERS Names of the process variable that is used by the signal process instance command.
SIGNAL PARAMETERS Names of process variables that receive inputs from signal process command.
MULTI INSTANCE LOOP See 834636269 (see page 434).
Sub-Process
A Sub-Process is an element that contains other activities, gateways, events, and so on which form a process that is part
of another process. A Sub-Process can only be used inside a parent process. It cannot be invoked by another process
using a Call Activity. A process that is defined in a Sub-Process element is not reusable, that is, other processes cannot
call this process through the Call Activity element.
A Sub-Process is used to enhance process readability, to group certain steps to create a logic group, and present the
user with high level steps. As Sub-Process is part of the parent process, if you move elements to a Sub-Process, all
expressions configured on these elements continue to work.
Service Task
A Service Task element is used to invoke a Java service method that is exposed as Action Type using @Action annotation.
You can create your own Service Task. To create a Service Task, you can use BMC Helix Innovation Suite SDK to create
service classes, package the classes in your smart bundle and annotate methods as Action Type in the service class. The
advantage of Service Task is that you can extend the platform by creating your own service, and integrate it seamlessly in
BMC Helix Innovation Studio. See Creating a custom service in Java (see page 823).
Service Task properties and their description

Action Type Name of the Action Type that performs Service Task. This field is populated automatically.
Name
Run as It allows execution of Service Task with permissions inherited from the process or the selected user role.
You can be set this field to Inherit from Process or Administrator to allow workflow to successfully perform the task on behalf of
the user.
If the Service Task does a query in a record definition where data has row level permission enforced, set this field to Current User.
Current User refers to the user who started the process.
INPUT MAP It defines the data binding of the action input. Inputs are defined in the Java service method as input parameters.
OUTPUT MAP It defines the data binding of the action result. The result is a return object of the Java service method. You can use this to save the activity
result to a process variable.
Note: It is recommended to use expression to pass the activity result to other activities.

INSTANCE
LOOP

To add Activities in processes
Note
1. In the Process designer, you can drag and drop the activity elements to the canvas according to the business
logic that you want to create.
2. Enter the required properties of the activity element.
3. Click Save.
To enable multi instance loop

A multi instance loop defines process activity repetition. It allows execution of an activity for each item in a data array.
Multi instance loop is available with Call Activity, User Task, Sub-Process, and Service Task Activities.
1. In the Process designer, select the activity element for which you want to use Multi instance loop.
2. In the Properties pane, in the MULTI INSTANCE LOOP section, enter the values for the following properties:
Loop Type It allows executing a certain activity for each item in a given collection, sequentially or in parallel.
Note: If you do not select the Loop Type, multi instance loop is not enabled on the activity.
Loop Data An expression that represents a collection of items. It refers to an array of data such as list of task records, or a list of approvers.
Input
Input Data A process variable that represents data type of each item. It is assigned with a value from the Loop Data Input array (such as a task
Item record or name of an approver).
Completion (Optional) If you do not want the process to loop through all data, configure Completion Criteria.
Criteria A multi instance activity ends when all instances are finished. However, it is possible to specify an expression that is evaluated every
time an instance ends. When this expression evaluates to true, all remaining instances are deleted and the multi instance activity ends.
The process continues thereafter.
For example, in an approval use case, you can use completion condition to define if 3 out of 5 approvers approve the request, the
loop is considered complete.
3. Click Save.
Multi instance loop example

The following images illustrates a process, where the process fetches a list of records. For each record, it updates the
record integer field, and appends the record display ID to a process variable IDs. Record handling is done in a Sub-Process
, where update record and append IDs steps are performed. In this example, Multi instance loop is defined on the Sub-
Process.

The following images show sample configuration of the process variable and the process steps (Get Loop Source Records
, Sub Process, Increment Integer Field and Append Display ID) for the above process:
Process steps Sample configuration
Process variable
Get Loop Source Records

Sub-Process
Increment Integer Field

Append Display ID
Related topic

Creating and controlling process flows

You can connect two elements in a process to provide a flow to the process tasks. You can also control the execution of
process flow such as separate or combine the flow according to the business requirement.
To connect elements in a process, the sequence flow element is used. The sequence flow element can have only one
source and one target and is represented with a solid arrow. This element is not a part of the Process designer Palette
section. To control the execution of a process flow, the Gateway element is used. The Gateway element is a part of the
Process designer palette.
This topic explains the types of gateways with examples and gives the procedure to connect the elements in process and
to control the process flow.
Types of Gateways
Gateway Description Example
Parallel A Parallel
gateway element
m odels
concurrency in a
process. It used
to visualize
concurrent
execution of
activities. It forks
into multiple
paths of
execution or joins
multiple
incoming paths
of an execution .
An Exclusive
Exclusive gateway element
models a decision
in the process,
and the
conditions on exit
paths.
When the
process
execution arrives
at an Exclusive
gateway element,
the system
evaluates the
conditions that
you define in the
outgoing
Sequence Flow
element of all
flows.The system
evaluates the
conditions in the
order in which
they are defined
and selects a flow
to execute
depending on

whether a
condition
evaluates to true
or a condition is
not defined.
Limitation of the
Exclusive gateway
You can use

Exclusive gateway
element to create
loops in
processes, only if
the loop runs for
less that 15
iterations.
Workaround
If you want to use

the Exclusive
gateway element
to create loops
that runs for
more than 15
iterations, modify
the existing loop
in the following
way:
1. Define a
local
process
variable
to
maintain
the
iteration
count.
2. Within
the loop
created
by using
the E
xclusive
gateway
element,
increment
the local
process
variable
(iteration
counter)
for every
iteration.

3.
3. If the
iteration
counter is
greater
than 15,
the
Compute
Value
element
(Reset
Count)
resets the
iteration
counter
to 0.
4. Use the
Receive
Task
element
that has a
timer
attached
to it.
5. After the
specified
time has
elapsed,
the
process
routes to
the
original
Exclusive
gateway
element.
Here, the
iteration
counter
restarts
from 0
and
therefore,
the loop
continues
for the
next 15
iterations.
To connect elements in a process
Note

1. In the Process designer, select the element on the canvas that you want to connect to the other element.
The sequence flow element is displayed.
2. Drag the sequence flow element (arrow) and connect to the other corresponding element.
3. In the Properties pane, enter the properties for the sequence flow element. The following table provides more
information on sequence flow element properties:
Type Type of the Sequence Flow element. You cannot select a particular type. The type is decided at the run time depending on where the
sequence flow is used, and if a condition is defined on the sequence flow. The types of sequence flow are as follows:
Default: Used to denote an outgoing path of an exclusive gateway where the sequence flow has no defined condition.
Conditional: Used to denote an outgoing path of an exclusive gateway where the sequence flow has a defined condition.
Normal: Used to denote a path that connects all other flow nodes.
Label Name of the element by which the element is shown in the process diagram.
Label Position of the label on the element.

Position
4. Save the process.
For information on how to run a process, see Managing processes by using the Manage Processes dashboard (see page
474).
To control process flows by adding Gateways
2. Select the application in which your process exists.
3. In the application, click Processes tab.
4. Click the process name where you want to add the Gateways element.
The system opens Process designer and displays the process diagram on the canvas.
5. Drag and drop the Gateways element to the canvas and place the element where you want to represent
concurrent tasks (Parallel gateway) or specify a condition (Exclusive gateway).
6. In the Properties pane, enter the values of the element properties and specify the flow of execution that you
want to create for your business logic.
If the source automation system provides a Template ID or Template Name as part of the inputs to create the change
record, the corresponding template is searched and applied to the change record.

Related topic
Adding a Timer event to a wait step

A Timer element i nterrupts a wait step and let the process make a decision about how to proceed after the wait step
times out. This element can be used only with the User Task and Receive Task elements that are termed as wait steps.
Note
To add timer event
4. Click the process name where you want to add events.

5. To add Timer event in the process, perform the following steps:
a. On the canvas, drag and drop Timer event to the User Task element or the Receive Task element as per
the process requirements.
b. In the Properties pane, enter the timer description, select the Timer Type.
Time Type describes the time within which a task must be completed before the system ends a task.
Interval Timer: Time specified in months, weeks, days, hours, and minutes.
If you select Interval Timer, provide the Interval Definition value.
Time Expression: Time specified as a timevalue expression.

You can use any of the following values in the expression:
Current time: Specifies that the event should be triggered at a future time.
Current time and an integer: Specifies that the event should be triggered after specific time (in
seconds) from the current time. For example, when you specify Current Time + 1000, the event
will be triggered after 1000 seconds from now.
Current date: Specifies that the event should be triggered at a specific date. For example, if you
schedule the timer to 30 March, the event will be triggered on 30 March at 00:00:00 hours.
Current date and an integer: Specifies that the event should be triggered on a specific date in the
future. For example, if you schedule Current date + 2, the event will be triggered after 2 days from
the current date.

6. Click Save.
The following image illustrates an example of a timer event:
Related topic
Adding text annotation in processes

A text annotation provides additional information about a process or an individual element in a process. You can use text
annotation to describe complex tasks, terminologies, more information about tasks, and so on. Text annotations help the
user to understand and perform a process smoothly. A text annotation is used for information purpose only and is not
involved in any kind of process function or activity.
An example of a text annotation is shown in the following image:
Notes

Text annotations are different from help text. Text annotation is visible to the one using the process,
whereas help text is visible to the one who designs the process.
Application business analysts can customize the objects developed in their own applications and that
are marked customizable by the developers, but cannot customize the objects developed in com.bmc.
arsys. For example, objects in core BMC applications like Foundation, Approval, and Assignment cannot
be customized.
To add text annotations to a process, perform the following steps:
1. Log in to BMC Helix Innovation Studioand navigate to the Workspace tab.
4. Click the process name that you want to modify.

5. Drag and drop the Annotations element to the canvas, enter the description that you want to provide for an
element or the process, and enter the location and size of the element.
6. Click Save.
Related topic
Adding attachments to processes

BMC Helix Innovation Suite enables you to add attachments as parameters to a process by using the Attachment
parameter. You can publish the process as an interface, which enables a user to include attachments to those interfaces.
For example, add an attachment parameter in any of the following scenarios:
You can add an attachment parameter to an application interface and attach files to records.
Digital Workplace users should be able to attach additional details when creating case requests.
This capability enables you to:
Add attachments to processes quickly and easily.
Share files conveniently.
Enhance collaboration between users.
For example, Digital Workplace users should be able to attach additional details when creating case requests. See the
following illustration:

You can attach only one file to an attachment parameter; however, you can attach multiple attachment parameters to a
process. You can attach any of the file formats that the SaaS administrator configures for your environment. However, if
the SaaS administrator restricts specific file formats from being uploaded and viewed, you cannot attach the restricted
file types to processes.
For example, you add a Record Association attachment of input type to a process. When you run the process that
contains an attachment parameter, you are prompted to choose the file to attach to the process.
To add an attachment parameter to a process
1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab
2. Select the application in which you want to create a process or modify an existing process.
3. Perform any of the following tasks:
If you want to create a new process and add an attachment parameter to the process, click New >
Processes tab.
If you want to add an attachment parameter to an existing process, select the process.
4. In the Properties section of a new process or an existing process, click Add/Remove Variables.
5. In the Add/Remove Variables window, click Add Variable.
6. Provide the following information:

Field Description
Name
Variable ID Specify a unique ID for the variable. This value must be numeric.
Variable Specify whether the variable is an input parameter, output parameter, or a local variable. For more information, see Defining the
Type application business logic through processes (see page 421).
Data Type From the dropdown list, select Attachment data type.
7. Click Save.
The attachment parameter gets added to the process.
Tasks that you can perform after adding the Attachment parameter
The following table provides information about the actions that you can perform after you add an attachment to a
process:

Task Description
Start process instance that When you start the process instance that includes an Attachment parameter, select the file that you want to attach to the
includes an attachment process. You can attach files, such as PDFs, text documents, images, and so on to individual processes.
Get process instance Retrieves the attachment associated with the process instance. You can download the attached file, update it with the required
attachment information, and upload the updated file to the process.
Pass an attachment to To pass an attachment from one process to the other, the parent process can pass an attachment as an input to the child
another process by using process.
the Call Activity element
If any child process has output as an attachment, the attachment can be stored into a process variable of the parent process or
it can be passed to any other activity as an input.
A Get Record Service Task retrieves a the field value of the record definition; however, the service task cannot retrieve the
Use action
attachments of a record definition. To retrieve the attachments associated with a specific record definition, BMC Helix
getAttachment to
Innovation Suite provides a new Get Attachment Service Task.
get the attachment
from record To retrieve attachments of a specific record definition, use the following Service Tasks in your process:
instance
1. Get Record: Retrieves the details of the record.
Use Get Record or
Get Records by
2. Get Attachment: Retrieves the attachment associated with the record.
Query Service
Tasks for
attachments
Notes
Do not use the part of Get Attachment Record instance. You must use the whole object.
You cannot use the Get Attachment Service Task in a rule; the service task can only be used in a process.

Task Description
For more information, see Creating or modifying record instances using Record Service Tasks (see page 457).
Delete a process that BMC Helix Innovation Suite stores the actual attachments associated with the process to a separate backend record definition.
includes an attachment When the process is deleted, those attachments too get deleted.
Use the activity result that has attachments. If any activity has output as an attachment, the attachment can be stored into a
Store activity result
process variable or it can be passed to any other activity as an input. For example, the get attachment result is stored as an
with attachment
activity result and can be used in the process as an input to other task or stored to a process variable.
Assign activity
result to process
variable
Create or update Record Create Record and Update Record Service actions support attachment type input when used in process. A process can use
service actions attachment type variable to pass as an input to create a record and update a record by using the service actions.
The output of the actions cannot be used for attachment type field. If you want to access the particular attachment that is
associated with the record action, you can use the newly-added Get Attachment Service Type in addition to the create record
or update record actions.
Pass attachment to signal Signal process command supports the attachment type variable as an input.
process command
Tasks that you cannot perform after adding the Attachment parameter
Tasks that you cannot perform with processes having attachment parameter from rules:
Pass attachment to any service action. For example, create record, update record.
Use attachment as an output in rule from action or process
Use output of Create Record, Update Record, and Get Record service actions for attachment type field
Pass attachment variable to the process instance when the trigger type is 'After delete'
Tasks that you cannot perform with processes having attachment parameter:
Pass attachment to user task
Use the output of user task for attachment
Pass attachment to custom action
Use output of Create Record, Update Record, Get Record, and Get Record by Query service actions for
attachment type field
Related topics
Creating process steps or activities (see page 434)
Handling errors in a process

A process contains a sequence of steps that flows from start to end. Occasionally, these steps can generate errors or
exceptions. You can use the following events in the Process designer to capture and display these errors or exceptions.

Name Symbol Description
Error An Error Boundary event captures errors and exceptions within a process and identifies the path that should be followed to
Boundary resolve the error after the Business error or exception is captured. For more information, see Capturing errors and exceptions
using Error Boundary event (see page 453).
Error An Error End event displays the business errors that occur in a process. For more information, see Displaying errors using Error
End End event (see page 455).
Capturing errors and exceptions using Error Boundary event

An Error Boundary event is always placed on the boundary of the Activities elements such as Call Activity, User Task, Sub-
Process, Service Task, or Receive Task element. For example, if you add the Error Boundary event on the boundary of
Sub-Process element, all the errors and exceptions generated from the child processes and all of its descendant process
definitions are captured by the Error Boundary event.
Use the Error Boundary event to:
Add multiple Error Boundary events to an activity.
If you configure an activity with multiple Error Boundary events, the Error Boundary event configured for
capturing specific errors and exceptions takes precedence over the Error Boundary event configured for
capturing Business generic errors and exceptions.
Capture unique error or exception. No two Error Boundary events capture the same error or Java exception with
the same error number.
Provide a fully qualified name for an exception if you want to capture a specific exception.
The Error Boundary event captures the following errors and exceptions:
Error Description
/Exception
Business Business errors are the logical errors occurring within a process that cause the process to operate incorrectly or produce incorrect results. For
errors example, assigning a value to the wrong variable produces incorrect result.
Business errors are captured only on Call Activity and Sub-Process and are displayed using the Error End event in a process or sub-process. If
you add an Error Boundary event on the boundary of a Call Activity element or a Sub-Process element, you can configure the Business error to
be captured by the Error Boundary event.
Java Instances of different Java exceptions are generated during the runtime process. For example, when creating a User Task record, if you do not
exception provide the required field values, RxFrameworkException is generated.
The exception has an optional error number to indicate the exact problem reported through the exception.
To add an Error Boundary event in a process
1. Open the process in which you want to add the Error Boundary event.
a. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
b. Select the application in which your process exists.
c. In the application, click the Processes tab.
d.
d. Click the process name in which you want to add events.

The Process designer opens and displays the process on the canvas.
2. Add the Error Boundary event to the process.
a. On the canvas, drag and drop an Error Boundary event on the boundary of any of the Activities elements,
for example, a Call Activity element or a Sub-Process element according to the process requirement.
b. In the Properties pane, enter the description and select Add/Remove Errors.
The Add/Remove Errors UI allows you to capture the errors and exceptions based on the following
options:
All Business Errors – To capture all the errors from Call Activity or Sub-Process elements.
Specific Business Error – To capture those errors that are from only Call Activity or Sub-Process
elements defined for the task.
All Exceptions – To capture all the Java exceptions generated by the process.
Specific Exceptions – To capture only the specifically mentioned exceptions.
3. Click Save.
Accessing errors captured by Error Boundary event

You can access the following details of error captured by the Error Boundary event:
Business errors—Error message
Java exceptions—Error message, error number and exception class.
If there are multiple Error Boundary events, you can configure all the events individually.
To access error details captured by Error Boundary events
1. Open the process in which you have the Error Boundary event.
c. In the application, click Processes.
d. Click the process name from which you want to get access the error details.
2. Drag and drop the appropriate user message Service Task (Send message, Send Message by Template or Show
Alert) to the canvas and place it at that point of the process flow where you want to send the error details.
3. In the Properties pane, select the parameter in which you want to send the error details such as Body (for Send
message and Send Message by Template) or Alert text (for Show Alert).
4. Click Click to build an expression.

4.
5. In the Errors node, select the error message, exception class, and error number (for Java exception error), or
error message (for business error) caught by the Error Boundary event.
Displaying errors using Error End event

An Error End event is used to indicate a business error in a process. This Business error is captured by the relevant Error
Boundary event. If no Error Boundary event is found to capture the Business error, the error is displayed to the user.
An error message is defined for a Business Error. The error message is an expression which refers to context data, for
example, a process variable, a result of an activity, or a keyword. The expression in the error message is evaluated when
the process generates a Business error.
To add an Error End event to a process
1. Open the process in which you want to add the Error End event.
c. In the application, click Processes tab.
d. Click the process name where you want to add events.

The Process designer opens and displays the process on the canvas.
2. Add the Error End event to the process.
a. On the canvas, drag and drop an Error End event.
b. In the Properties pane, type a label and description.
c.
c. From INPUT MAP, select Click to build an expression.

The Click to build an expression allows you to create an expression for an error message, which will be
displayed at runtime.
3. Click Save.
Example of using Error Boundary and Error End events in a process

The following diagram depicts a sample process of reviewing a new Sales lead for an organization. The Error End events
are used in this process to display the errors generated during process execution. The Error Boundary event is used to
capture the errors and exceptions generated during the process execution.
The following table describes the stages of this process example:
Stage Description
1 The Provide new sales lead User Task allows a Sales representative to provide information for the new sales lead.
2 The new sales lead information is sent to the Review sales lead sub process.
3 Using
The Review customer rating User Task allows the Sales representative to provide information for reviewing the Customer rating.
4 The Review profitability User Task allows the Sales representative to provide the profitability information related to the new sales lead.
5 After the Review profitability User Task is completed, if sufficient information to review the profitability is not provided, the following Business error is
generated:
Insufficient data to review profitability.
6 An Error Boundary event captures the Insufficient data to review profitability business error, provides additional
information for the sales lead, and restarts the Review sales lead sub process.
7 A second Error Boundary event captures all the exceptions and sends a message to an administrator.
8 If the Review sales lead sub process is completed successfully without generating any Business errors or exceptions, the Store lead in CRM system
action stores the new sales lead in the CRM system.

Creating or modifying record instances using Record Service Tasks

According to the business logic that you want to create in a process flow, you may need to create or update record
instances of record definitions used in a process. To perform operations such as add, delete, or retrieve a record
instance, you can use the Record Service Tasks in the Process designer.
For information about record instances, see Defining record definitions to store and manage data (see page 324).
Types of Record Service Tasks

Record Description
Service
Task
Create A Create Record Service Task creates a record instance for a specified record definition. You can create process parameters that can be
Record mapped with the record definition fields. The values that you provide to the process parameters can be used to set record instance fields at the
time of instance creation.
Update An Update Record Service Task updates a record instance in a record definition based on a specific record instance ID. You can specify the ID
Record of the record instance that you want to update through a process parameter or through an expression.
Delete A Delete Record Service Task deletes a record instance for a specified record definition. You can specify the ID of the record instance that
Record needs to be deleted through a process parameter or through an expression.
Get Record A Get Record Service Task retrieves a record instance from a record definition based on a specific record instance ID. You can specify the ID of
the record instance that you want to retrieve through a process parameter or through an expression.
Get A Get Attachment Service Task retrieves the attachments associated with a specific record definition.
Attachment
Get A Get Records By Query Service Task retrieves record instances from a record definition based on the specified query.
Records By
Query
Get A Get Security Label Service Task retrieves a security label from a record definition based on a specific record instance ID. You can specify the
Security ID of the record instance that you want to retrieve through a process parameter or through an expression.
Label
Remove A Remove Security Label Service Task deletes a security label for a specified record definition. You can specify the ID of the record instance
Security that needs to be deleted through a process parameter or through an expression.
Label
To identify if the security label is updated, see Identifying updates to the security label (see page 460).
Set A Set Security Label Service Task sets the security labels (enables row-level security of record instances) through a process.
Security
To identify if the security label is updated, see Identifying updates to the security label (see page 460).
Label
To add Record Service Tasks to processes
4. Click the process name that you want to modify to create record instances, delete record instances, retrieve
record instance details, retrieve security labels, delete security labels, set security labels, or update record
instances.
5.
5. Drag the appropriate Record Service Task to the canvas according to the operation you want to perform.
6. Enter the required properties of the Record Service Task; see Record Service Task properties (see page 458).
7. Click Save.
Note
When using the output value of a Record Service Task as the input for an approval process, do not a ssign the
output value directly. You must first assign the output value to a record-type process variable and then assign
the process variable as an input to the approval process. This restriction does not apply to the Create Record
Service Task.
Record Service Task properties

The following sections provide information about Record Service Task properties for which tooltips are not available on
the UI. For information about the common Service Task properties such as Run as, or Multi instance loop, see Service
Task properties (see page ).
Create Record properties
INPUT Record Definition Name—Record definition for which you want to create a record instance. You can select a record definition from the current
MAP application.
Add/Remove Input Map Fields—Fields of the record definition that map to the process parameters or to an expression that assigns a value to the
mapped fields. The new record instance is created using the values assigned to the mapped fields.
OUTPUT Process parameters that you want to obtain as output values from this Create Record Service Task. You can build an expression for assigning an
MAP output value to a process parameter.
For an example of the Create Record Service Task, see Pushing field values to other record instances (see page 461).
Update Record properties
INPUT
Record Source —Source of the record: database or process variable.
MAP
Record — Record instance, available only if the record source is a process variable.
Record Definition Name — Name of the record definition, available only if the record source is in the database.
Record ID — ID of the record to which you want to restrict access, available only if the record source is in the database.
Add/Remove Input Map Fields—Property that maps the fields of the record definition to the process parameters or to an expression that
assigns a value to the mapped fields. The record instance is updated using the values assigned to the mapped fields.
For an example of the Update Record Service Task, see Updating the current record instance using field values from
another record instance (see page 464).
Delete Record properties
INPUT
Record Definition Name—Record definition for which you want to delete a record instance. You can select a record instance from the
MAP
current application.

Record ID—ID of the record instance that you want to delete. You can provide the ID through a process parameter or through an
expression.
Get Record properties
INPUT
Record Definition Name—Record definition for which you want to retrieve data of a record instance. You can select a record instance
MAP
from the current application.
Record ID—ID of the record instance that you want to retrieve. You can provide the ID through a process parameter or through an
expression.
OUTPUT Process parameters that you want to obtain as output values from this Get Record Service Task. You can build an expression for assigning an
MAP output value to a process parameter.
Get Records By Query properties
INPUT
Record Definition Name—Record definition for which you want to retrieve data of a record instance. You can select a record instance
MAP
from the current application.
Query Expression—Query expression to retrieve record instances.
Add/Remove Input Map Fields—Fields of the record definition that map to the process parameters or to an expression that assigns a value
to the mapped fields. The new record instance is created using the values assigned to the mapped fields.
Retrieve—Property you can select to retrieve the first matching record or retrieve all matching records based on the query.
OUTPUT Process parameters that you want to obtain as output values from this Get Records By Query Service Task. You can build an expression for
MAP assigning an output value to a process parameter.
Get Security Label properties
INPUT
Record Source — Source of the record: database or process variable.
MAP
Record Definition Name—Record definition for which you want to retrieve security label details. You can select a record instance from
the current application.
Record ID—ID of the record instance for which you want to retrieve security label details. You can provide the ID through a process
parameter or through an expression.
Security label—Select the security label.
OUTPUT Process parameters that you want to obtain as output values from this Get Security Label Service Task. You can build an expression for assigning
MAP an output value to a process parameter.
The Get Security Label returns three output parameters:
Group —Comma-separated list of group names that are granted access.
User —Comma-separated list of user names that are granted access.
Role— Comma-separated list of application role names that are granted access. The role names are displayed in the following format:
<fully qualified application name>:<role name>

Set Security Label properties
INPUT MAP
Record Source — Source of the record: database or process variable.
Record — Record instance, available only if the record source is a process variable.
Record Definition Name — Name of the record definition, available only if the record source is in the database.
Record ID — ID of the record to which you want to restrict access, available only if the record source is in the database.
Security Label —List of security labels as defined in the record definition.
Group Names — Comma-separated list of group names to which you want to grant access.
User Names — Comma-separated list of user names to which you want to grant access.
Role Names —Comma-separated list of fully qualified (application name:role name) role names to which you want to grant access.
If the application name is not mentioned, the application of the record definition is used instead.
Format: <fully qualified application name>:<role name>,
Example: com.bmc.arsys.taskmanager:Task Viewer,com.bmc.arsys.casemanagement:Case
Agent
Organization Ids—Comma-separated list of organization ids to which you want to grant access .
Remove Security Label properties
INPUT MAP
Record Definition Name—Record definition for which you want to delete a security label. You can select a record definition from the
current application.
Record ID—ID of the record instance for which you want to delete a security label. You can provide the ID through a process
parameter or through an expression.
Security Label —List of security labels as defined in the record definition.
Group Names — Comma-separated list of group names to which you want to revoke access.
User Names — Comma-separated list of user names to which you want to revoke access.
Role Names — Comma-separated list of application role names to which you want to revoke access.
Organization Ids —Comma-separated list or organization ids to which you want to revoke access.
Example: Identifying updates to the security label

Security labels (see page 348) are used to enable the row-level security and define a series of users, groups, or
application roles that can be given access to record instances by using a rule or a process. To identify if there is an
update to the security label made by Set Security Label or Remove Security Label actions, after the associated record
instance is updated, you can use the SECURITYLABELCHNG() function.
The SECURITYLABELCHNG() function is used in a rule or a process. This function returns 1 if the security label of the
current record is updated for the current transaction and returns 0 if the security label is not updated.
When using SECURITYLABELCHNG() function in a process, ensure that you add record instance as a parameter. When
using SECURITYLABELCHNG() function in a rule, you do not need to add any parameter.
The following image illustrates a sample process to check whether the security label of a case record is updated if the
assignee is from a different support group. If the security label is updated, then trigger the process to make changes to
the related tasks.

Note
If you have a wait state in the process, for example, User Task or Receive Task, then the SECURITYLABELCHNG()
function returns 0 even if the security label is changed.
Example: Creating or updating record instance

To create a new record instance and to update a record instance, you can use Create Record and Update Record Service
Tasks respectively.
To find record instances that need update, use Get Records By Query action type and to loop through all
records, use Update Record action type.
If you want to create record instances and do not finding any matching records, use a gateway to do null check of
the output of Get Records By Query.
If you want to update only one record instance, you can optimize Get Records By Query by retrieving only the
first matching record instance, and update only that first record instance without using the loop.
In Get Records By Query, select only those fields that are needed by the process. This simplifies the activity result.
The following image illustrates a sample process:

The following images shows sample configuration of steps Find the Company, Update Company Record, and the No
branch of the Found the Company gateway for the above process:
Find the company
Update Company Record

Found the Company

Example: Updating the current record instance by using field values from another record instance
You can update the current record instance with field values from another record instance by using Get Records By
Query and Update Record. To find the record instance from which you want to use the field values, u se Get Records By
Query. To set field values of the current record instance, use Update Record.
For optimization and simplicity, Get Records By Query should only retrieve fields that are needed by the process, and
should only retrieve the first matching record.
The following image illustrates a sample process:
The following images illustrate sample configurations of process variable and process steps for the above process:
Process step Sample configuration
Process variable
Find Customer Name

Process step Sample configuration
Set Customer Name on

Task
In Set Customer Name on Task, the name is

Example: Updating a transaction value using process and rule

The transaction value references the value of the field in the current transaction only. When you create or update a
record instance for business applications, you may be required to validate and update the record instance before storing
it in the database. In BMC Helix Innovation Studio, a rule has a trigger that is activated on record events. It is
recommended that the rule calls a process to perform an action. In the Rule designer, the transaction value is
represented by using the Current Record ($ENTRY$) keyword.
To update the transaction record instance through a process, use the Update Record Service Task and select the
following parameters:
Record Source—Process Variable
Record—the transaction record instance
The following images illustrates a sample configuration to update the transaction record:
Action Sample configuration
Rule Start
Process
Process
Input
Parameter

Action Sample configuration
Update
process
variable
(task)
using
Update
Record
Service
Task
To enable the sample record definition feature, in the Process designer Process Properties pane, navigate to Add
/Remove Variables, select the Data Type as Record and select the Use Sample Data check box and then select the
sample record definition.

To share a process with different record definitions and to associate a record data type to more than one record
definitions, you can use a sample record definition, where a process can refer to fields of different record
definitions. However, the process does not validate the record definition name at runtime. If the record instance
does not have a field referenced by the process, a null value is used.
It is recommended that record definitions that share the same process definition are inherited from a common
base record definition. Record inheritance ensures that all the fields referenced in a process definition are
available to all inherited record definitions. For more information about record inheritance, see Inheriting an
existing record definition to a new record definition (see page 338).
Related topic
Creating associations using the Association Service Task

In a process flow, you can define a relationship between the record instances. You can use the Association Service Task
in Process designer to create associations between record instances or to remove associations between record
instances.
Types of Association Service Tasks

Associate Associates a record instance with another record instance that is dependent on the original record instance. A
Child record instance is associated to the child record object.
Record
If the association definition is a direct association, the Associate Child Record action updates the foreign key
field of the child record.
If the association definition is an indirect association, the Associate Child Record action gets the child record
ID, and stores it in the association table.
Associate Associates two record instances.

Records
Disassociate Removes the association between two specific record instances.

Records
Example: The Employee record instance has an association with the Phone Number record instances - office and
personal. You want to disassociate the Employee record instance with the personal Phone Number record instance.
Disassociate Removes association for all record instances. Use this task only when you do not need to refer to the disassociated
All Records record instances.
Example: The Author record instance has an association with Knowledge Article record instances. You want to
disassociate the Author record instance with all the Knowledge Article record instances so that you can associate
the Knowledge Articles with another Author.
Note

To associate or disassociate records
4. Click the process name where you want to associate or disassociate records.
5. Drag and drop the Association Service Task (Associate Child Records, Associate Records, Disassociate Records,
or Disassociate All Records) to the canvas, and in the Properties pane, enter the values for the properties.
The following table provides more information on the Association Service Task properties:
INPUT MAP
Association Definition Name—Name of the association definition.
(for
Associate First Record ID—ID of the first record instance that you want to associate or disassociate.
Records Example: Employee
and
Second Record ID—ID of the second record instance that you want to associate or disassociate.
Disassociate
Example: Contact Number
Records)
INPUT MAP
(for
Disassociate Node Side—Specify whether you want to disassociate the record instance on the left side of the association or the right side
All Records) of the association. The disassociation works bidirectionally between the two nodes.

Example: You have a many-to-many association between a story and task. You want to disassociate all the record instances of
tasks with the stories. Select Node A (Story record definition).
Record ID—ID of the record instance in the node side selected earlier.
Example: Specify the record ID of node A (Story record definition).
INPUT MAP
(for
Associate First Record ID—ID of the first record instance that you want to associate.
Child
Second Record—Second record instance that you want to associate or disassociate.
Record)
For more information about the common Service Task properties such as Run as or Multi instance loop, see
Service Task properties (see page ).
6. Click Save.
Related topics
Creating record associations (see page 342)
Sending a user message from a process

You can use the User Message elements (Show Alert, Send Message, and Send Message by Template) in the Process
designer to send email notifications or in-app notifications to the users at any stage of the process.
Types of user messages

Show Alert Displays alerts based on specific conditions. The alert can be of the following types:
Information
Warning
Error
Send Sends a message to one or more users.

Message
For example, if a task is assigned to a user for approval, you can use a Send Message to notify the user about the pending task.
The message appears in the notification bell for the users as well as in an email.
Send Sends a message by using a defined template to one or more users.

Message by
For example, if a task is assigned to two users for approval, you can use Send Message by Template to notify both users about
Template
the pending tasks by using a common predefined template. The message appears in the notification bell for the users as well
as in an email.
Note

Before you begin

To use the Send Message element, ensure that the administrator has configured the outgoing mailbox. For more
information, see Configuring incoming and outgoing email (see page 751).
To use the Send Message by Template element, ensure that the administrator has configured the text template. For
more information, see To configure templates (see page 754).
To send a user message
4. Click the process name from where you want to send messages.
5. Drag the appropriate User Message element (Show Alert, Send message, or Send Message by Template) to the
canvas and place it at that point of the process flow where you want to send a notification.
6. In the Properties pane, in the INPUT MAP section, fill out the following properties:
User Properties
Message
Service
Task
Show
Alert Text—Click the Click to build an expression link and enter the alert message or provide the expression for the alert
Alert
message that should be displayed.
Send
Subject—Click the Click to build an expression link and enter the subject for the user message or provide the expression for the
Message
subject of the user message.
Body—Click the Click to build an expression link and enter the contents of the message or provide the expression for the
contents.
Recipients— Click the Click to build an expression link and enter the login name or valid email address of the users. For multiple
recipients, add comma-separated login names or valid email address.
(Optional) Outgoing Profile Source—Select the option on how you want to add the Outgoing Email Profile.
Profile Selection—Enables you to select the existing outgoing email profiles from the Outgoing Email Profile list.
Build Expression—Enables you to provide the expression to select the correct outgoing email profile.
(Optional) Outgoing Email Profile—Select the outgoing profile that is configured (see page 753)by the administrator.
If the list fails to display the outgoing profile, see Troubleshooting incoming and outgoing email issues (see page 991).
Note: If you do not specify an outgoing email profile, the default outgoing mailbox is selected to send the message.
Send
Subject—Click the Click to build an expression link and enter the subject for the user message or provide the expression for the
Message
subject of the user message.
by
Template Recipients—Click the Click to build an expression link and enter the login name or valid email address of the users. For multiple
recipients, add comma-separated login names or valid email address.
Template Name—The template name must be exactly the same name that is used by the administrator when configuring
templates (see page 754).
(Optional) Body—If this parameter is configured, the text is prepended to the template contents.

User Properties
Message
Service
Task
(Optional) Record Definition Name— Click the Click to build an expression link and enter th e fully qualified record definition
name from which you want to populate the template contents.
(Optional) Record Instance Id —Click the Click to build an expression link and enter the record instance ID from which you want
to populate the variable values in the template.
(Optional) Outgoing Profile Source—Select the option on how you want to add the Outgoing Email Profile.
Profile Selection—Enables you to select the existing outgoing email profiles from the Outgoing Email Profile list.
Build Expression—Enables you to provide the expression to select the correct outgoing email profile.
(Optional) Outgoing Email Profile—Select the outgoing profile that is configured (see page 753) by the administrator.
If the list fails to display the outgoing profile, see Troubleshooting incoming and outgoing email issues (see page 991).
Note: If you do not specify an outgoing email profile, the default outgoing mailbox is selected to send the message.
The following image demonstrates the properties configured to send email notification by using Task Template and Task
Management profile.
7. If you want a process activity to run in loop, fill out the Multi Instance loop section. For more information about
the common Service Task properties like Run as and Multi instance loop, see Service Task properties (see page
).

Tip
If you have used the Error Boundary event earlier in the process, you can send details of a business error or
Java exception by using the User Message Service task.
Related topic
Computing values in processes

To specify conditions in a process flow, you can build expressions that represent arithmetic or a function expressions. To
obtain the expression value, you can use the Compute Value Service Task in the Process designer and use the expression
value in the process flow.
Note
To evaluate expressions in processes
4. Click the process name that you want to modify to obtain expression values.
5. Drag and drop the Compute Value Service Task to the canvas and place it at that point where you want the
system to evaluate an expression.
6. In the Properties pane, enter the values for the properties. The following table provides more information on the
Compute Value properties:
INPUT Custom expression that represents an arithmetic or a function expression. You can build a custom expression and use the output of the
MAP expression in your process.
For example, build an expression to concatenate input parameters with static values and use the expression output in different actions.
OUTPUT Process parameters that you want to obtain as output values from this Compute Value Service Task. You can build an expression for
MAP assigning an output value to a process parameter.
For more information on the common Service Task properties like Run as, Multi instance loop, see Service Task
properties (see page ).
7. Click Save.

Related topic
Managing processes by using the Manage Processes dashboard

While creating processes, you might want to:
Run a process to check the logical flow.
View the process dashboard to get a quick information about processes and their respective instances and
instances status.
Troubleshoot a process instance if a task in the process instance resulted in a system error.
Note
In a process, when the Call Activity element results in errors, the errors are not highlighted when you
use the Manage Processes dashboard.
You can perform all these tasks by using the Manage Processes dashboard.
Manage Processes dashboard

BMC Helix Innovation Studio provides a feature called the Manage Processes dashboard where you can perform the
following actions for processes:
View a list of all processes of an application
Search for a process
Start a process instance of a selected process
View process diagram of a selected process
View process instances of a specific process and their statuses based on a time frame
Search for a process instance
View process instances based on a criteria
Suspend, resume, and cancel process instances
Check progress of a process instance
To view the Managing Processes dashboard
2. click the required application or library.
3. Click the Processes tab.
4. In the Process menu bar, click Manage Processes.

The system displays the Manage Processes dashboard.

To run a process
1. Go to the Manage Processes page, see To view the Managing Processes dashboard (see page 474).
2. From the Process list, select the process that you want to run, and click Run.
A process instance of the selected process gets started.
To view process instances based on a time frame

The process instance list displays the process instances of all or a selected process. The list provides a summary of
process instances such as context key, start date, and status of process instances. The context key is displayed as the
primary column. By default, the system displays summary of process instances of all processes for the last one hour. You
can change the time frame and select a specific process to view process instances summary.
2. In the Process list, click the process for which you want to view the process instances.
3. In the Time Frame box, click the required time frame or enter a custom time range for which you want to view
process instances.
The system updates the Status bar graph to display statuses of process instances for the selected time frame.
The system also updates the Process instance list to show the summary of process instances for the specified
time frame.
4. (Optional) You can view process instances for a specific status by clicking the respective status tab on the Status
menu bar.
To display Process ID column in the process instance list

By default, the Process ID column is not displayed in the Process instance list.
1. Go to the Manage Processes page. For more information about Manage Process page, see To view the Managing
Processes dashboard (see page 474).
2. In the Process instance list, click Visible Columns and select Process ID.
For example:

To cancel, resume, or suspend a process instance

You can cancel, resume, or suspend process instances based on their current status by using the Manage Processes
dashboard.
1. Go to the Manage Processes page. For more information about Manage Process page, see To view the Managing
Processes dashboard (see page 474).
2. From the All Process list, select the process for which you want to cancel, resume, or suspend a process instance.
3. In the Process instance list, click the context key of the process instance that you want to cancel, resume, or
suspend.
The process instance details are displayed. The following image illustrates a sample of process instance details:
4. As per your requirement, cancel, resume, or suspend the process instance.
To cancel the process instance, click Cancel.
To suspend the process instance, click Suspend.
To resume the process instance, click Resume.
To view process instances based on a criterion

You can view process instances based on a specified criteria. Once the system displays the matching process instances,
you can cancel, resume, or suspend instances based on their current state.
2. In the Process instance menu bar, click Filter.
3. Click Owner or Context Key as a criterion.
4. Enter the value for which you want to search for the selected criteria and click .
The system displays all process instances that match the value that you entered.

To change the status of a process instance

You can change the current status of process instances. You might need to change the process instance status while
testing a business process that you developed. For example, if a process instance has an error status, you might want to
troubleshoot why the process instance resulted in an error. If you discovered an error in the business process design,
you might want to cancel the process instance that is in error.
1. Go to the Manage Processes page; see To view the Managing Processes dashboard (see page 474).
Search the process instance whose status you want to change. You can search the process instance using
the context key.
From the Status menu bar, click the required status and search for the process instance whose status you
want to change.
3. Select the check box for the process instance.
4. On the Process instance menu bar, click the required status.

The system changes the status of the process instance and updates the Status bar graph.
To view the progress of a process instance

You can view the progress of a process instance. For example, if a process instance is in a suspended status, you can
investigate, which task resulted in the process instance getting the suspended status.
Search the process instance whose progress you want to view. You can search the process instance using
the context key.
From the Status menu bar, click the required status and search for the process instance whose progress
you want to view.
3. Click the process instance from the Process list.

The system displays the progress graph of the process instance. The task that is being currently executed is
highlighted in green. You can click on any task to get information such as time of completion and status of the
task.
4. (Optional) To refresh the screen, you can click the Refresh icon on the top right corner.
Related topics

Automating categorization and assignment of application requests

In BMC Helix Innovation Suite, you can automate the manual tasks for categorization and assignment. Auto-
categorization of application requests is achieved by using the BMC Helix Innovation Suite Cognitive Service. For auto-
assigning application requests to individuals, you can use the BMC Helix Innovation Suite Cognitive Service or the Call
Assignment Policy element in the Process designer.
The following table explains the methods of auto-categorizing and auto-assigning application requests:
Action Reference
Auto-assignment by using BMC Helix Innovation Suite Cognitive Service To add auto-assignment in a process (see page 479)
Auto-assignment by using the Call Assignment Policy element in the Process designer Defining assignment processes to trigger the assignment
policies (see page 629)
Auto-categorization by using the BMC Helix Innovation Suite Cognitive Service To add auto-categorization element in a process (see page
478)
To add auto-categorization in a process
3. In the application, click Processes.
4. Click the process name to which you want to add auto categorization.
The system opens the Process designer and displays the process diagram on the canvas.
5. Based on your requirements, add the input and output variables required for the process.
For information about adding input and output process variables, see Defining the application business logic
through processes (see page 421).
6. Drag the Cognitive element called Suggest Category to the canvas and place it where you want to add it in the
process and provide the input and output connections.
7. Select the Suggest Category element and enter the values for the properties.
The following table describes the properties:
INPUT MAP
Training Specify the training data set.

Data Set
Name
Text To Specify the data that you want to categorize.

Classify
OUTPUT Specify the process parameters that you want to obtain as output values from this element.
MAP You can build an expression for assigning output values to process variables. The data that you want to categorize can have multiple
categories. For example, in the CSV file, for the text "Unable to localize view component," you specify two categories: Localization and
View component.
Note: To get multiple categories output values, you must create a list of the categories. If you do not create a list, the output value is
only the first category.

8. Click Save.
To add auto-assignment in a process

Before you add an auto assignment in a process, you must implement a Java interface to use the assignment types. BMC
Helix Innovation Suite Cognitive Service returns the login IDs of the assignee. You must ensure that the assignee belongs
to the Agents group in the Foundation library. See Creating a Java program to use auto assignment (see page 570).
4. Click the process name to which you want to add auto assignment.
5. Based on your requirements, add the input and output variables required for the process.
6. Drag the Assignment element called Suggest Assignee to the canvas and place it where you want to add it in the
process and provide the input and output connections.
7. Select the Suggest Assignee element and enter the values for the properties.
The following table describes the properties:
INPUT MAP
Record definition Specify the record definition name for the listener
name
Assignee Training Specify the training data set

Data Set Name
Task Category Specify the category that is used by the BMC Helix Innovation Suite Cognitive service to return a list of possible assignees.
Assignment type Specify the type of assignment
Round Robin—Tasks are assigned in Round Robin manner; that is, the first assignee in the list is assigned to the first
task, second assignee to the second task, and so on.
Load Balanced By Number—Task is assigned to an assignee depending on the number of tasks already assigned to
that assignee.
For example, if Seth has four tasks assigned and Ajay has five tasks, the new task is assigned to Seth.
Load Balanced By Capacity—Task is assigned to an assignee depending on the amount of work.

For example, if Seth has four days work to complete the assigned tasks and Ajay has five days work to complete the
assigned tasks, the new task is assigned to Seth.
By Skill Level—Task is assigned to an assignee depending on the task expertise.

For example, if Seth has more experience to complete a task as compared to Ajay, the task is assigned to Seth.
Note: To use these assignment types, you must implement a Java interface. See Creating a Java program to use auto
assignment (see page 570).
Task Required Specify the date or time by which the tasks should be completed
Resolve date
Task Effort Specify the estimation of the task effort, in hours

Task Priority Specify the priority of the task

You must provide a number (0,1, 2, or 3) as follows:
0—Critical
1—High
2—Medium
3—Low
OUTPUT MAP Specify the process parameters that you want to obtain as output values from this element
You can build an expression for assigning an output value to a process variable.
Example: Using a process to automate categorization and assignment of an issue

The following process automatically categorizes an issue and assigns it to the assignee by using the BMC Helix Innovation
Suite Cognitive Service. The process categorizes the issue by using the issue summary and returns a category. The
Suggest Assignee action uses this category to determine the correct assignee.
Suggest Category values
Property Example value
Action Type Name Suggest Category
Label Suggest Issue Category
Description Returns the category of the issue
Run as Inherit from Process
Training Data Set Name Defect Category
Text To Classify "Unable to localize view component"
Suggest Assignment values
Action Type Suggest Assignee

Name
Label Suggest Assignee
Description Returns assignee
Run as Inherit from Process
Record Definition Task

Name

Assignee Training Issue assignee

Data Set Name
Task Category Output
Note: Here the output value used is the first classified category for the text.
For example, in the CSV file you have specified two categories Localization and View component for the text "Unable to localize view
component". The Localization category (first classified category) is used as the value for Task Category.
To use multiple categories, see 750999131 (see page 478).
Assignment Type Round Robin
When you run the process, the output of the Suggest Category action (Localization) is provided to the Suggest Assignee
action and the Suggest Assignee provides the name of the assignee as an output. The following image illustrates a sample
process activity result:
To add auto categorization and auto assignment in a rule
2. Select the application in which your rule exists.
3. In the application, click Rules.
4. Click the rule name to which you want to add an auto categorization or auto assignment.
The system opens the Rule designer and displays the rule diagram on the canvas.
5. Drag the Suggest Categorization element (for auto categorization) or Suggest Assignee element (for auto
assignment) to the canvas and place it where you want to add it in the rule and provide the input and output
connections.
6. Select the element, enter the values for the properties, and repeat for the next element.
The properties of the Suggest Category and Suggest Assignee element are the same as those described in To add
auto categorization in a process (see page ) and To add auto assignment in a process (see page ).
7. Save the rule.

For more information about how to create a rule, see Creating rules (see page 493).
Example: Using a rule to automate categorization and assignment of an issue

The following rule automatically categorizes an issue and assigns it to the assignee by using the BMC Helix Innovation
Suite Cognitive Service. The rule categorizes the issue by using the issue summary and returns a category. The Suggest
Assignee action uses this category to determine the right assignee. Here the Suggest Assignee element uses the first
category for the issue that is provided by the Suggest Category element. To use multiple categories, see 750999131 (see
page 478)
You can trigger the rule on a record event such as On Create, After Create, On Update, and so on. For information about
record events, see Rule designer elements (see page 491).
For information about the sample values, see Suggest Category values (see page 480)and Suggest Assignment values
(see page 480).
Example: Using multiple categories of data classification

The following process uses multiple categories provided by a Suggest Category element. To use a Suggest Category
element that returns a list of String for data classification, loop the output data of the element.
In this process, Getting Automatic Categorization (Suggest Category element) has three output values and these output
values are used to update the Setting Categories. Setting Categorization 1, Setting Categorization 2, and Setting
Categorization 3 use the first, second, and third values of Getting Automatic Categorization output respectively.

The following steps describes how to assign Getting Automatic Categorization output to Setting Categorization 1, Setting
Categorization 2, and Setting Categorization 3:
1. Create a local text variable Current Categorization to store the current categorization.
2. Create a local integer variable Counter and initialize it to 1 by using a Compute Value element Setting Counter = 1.
Select the output of Setting Counter = 1 as source.

3. Loop the output of the Getting Automatic Categorization in a subprocess and for every step in the loop store the
current categorization in the local variable Current Categorization.
For example, map Problem Area 3 with the Current Categorization variable by using Update Record.
4. Use an Exclusive Gateway element to update the right Setting Categories according to the value of the counter.
When the counter is 1, it updates the first categorization. When the counter is 2, it updates the second
categorization. When the counter is 3 the default branch is used to update the third categorization.

4.
The third path of the Exclusive Gateway is the default path (without a condition). In this case, it is the path when
the counter is greater than 2.
5. Increment the counter by 1 at each iteration of the loop, so that in the next iteration of the loop, the exclusive
gateway picks up another branch.

Related topic
Adding cognitive capabilities to a custom application (see page 552)
Validating and verifying a PIN value

BMC Helix Innovation Suite has Verify Pin as a Process and Rule designer element. This element provides a functionality
of validating and verifying PIN value provided by a user.
You can set the Verify Pin element in the Process or Rule designer. By using Verify Pin element, you can compare the PIN
value entered in Person data with the PIN value given by the user.
Alternatively, you can validate the PIN value by using REST APIs.
To configure Verify Pin element in the Process designer
2. Select the application where you want to verify the PIN value.
3. In the application, go to the Processes tab and click New.
4. From the Process designer Palette section, select the Verify Pin element.
5. Navigate to the Properties pane on the right side of the screen, and select the record definition in which store
hashed field ID is saved.
For more information about the store hashed functionality, see Securing text fields (see page 486).
6. From the Gateways section, drag and drop Exclusive gateway element .
Note
Define boolean expression for Exclusive gateway using Verify Pin output value.
For example, if the PIN values match, set the output as 1 (True), and if the values do not match, set the
output as 0 (False).
Verify Pin element returns boolean value which can be used with exclusive gateway to attain the
expected goal.

7. Select the Field ID and Record ID and click OK.
8. Enter PIN which is already stored and needs verification and click OK.
9. Click Save.
The following image illustrates the example of Verify Pin element and the consequent messages that are displayed if the
PIN verification is successful or not:

Creating a document instance

After you define the schema for a document and create a document definition (see page 497) to access individual
attributes within the metadata object and use these attributes in an expression within a process, you can create a
document instance. A document instance is the data created by the application for which the structure is specified by
the document definition. You can create a document instance by using the Create Document element in the Process
designer.
For example, consider you define the following document to get the error details from a third-party application.
Example:
{
"error code": "",
"error message": "",
"Issue area":""
}
The following images show the document instances created for the document definition:

Before you begin

Ensure that you have created a document definition. For more information, see Defining document definitions (see page
497).
To create a document instance
2. From the Workspace tab, navigate to the application for which you want to create a document instance.
3. Perform one of the following tasks:
If you want to create a new process and add the Create Document element to the process, select
Processes > New.
If you want to add the Create Document element to an existing process, click the Processes tab and select
the name of process.
4. From the Palette, drag the Create Document element on to the canvas as per the process requirements.
5. In the Element Properties pane, enter the properties for the Create Document element, as described in the
following table:
GENERAL
Label Enter a suitable name for the element.
Description Enter details about the element.
INPUT MAP
Document Definition Select the document definition that you want to use for this process.
Name
Add/Remove Select the attributes from the document definition you selected. For each node that you select, click Click to build an
Document Nodes expression, and add the value for each node.
MULTI INSTANCE LOOP
Loop Type Select Select Parallel or or Sequential from the list. from the list.

For information about Multi instance loop , see Creating process steps or activities (see page 434) .
6. Click Save.

Action Reference
Access complex objects, array of objects, array of strings, and nested complex objects within the metadata object and use these Adding process variables
objects as input or output to an expression within a process. (see page 426)
Adding rules to validate data or trigger events in a process

BMC Helix Innovation Studio provides Rule designer, a graphic-based interface, to create and customize business rules of
an application.

A rule, along with a process, models the business logic of an application. The purpose of a rule is to perform data
validation, and interact with a process on record events or timer events. You can create rules that are triggered, based
on a specific time interval or a schedule.
This section provides you the information on elements available in the Rule designer, how to create rules, and how to use
the Connector element to integrate your application with a third-party service or application.
Action Reference
Understand the elements available in the Rule designer. Rule designer elements (see page 491)
Create a rule that defines the business logic of your application. Creating rules (see page 493)
Integrate your application with a third-party service or application by using the Connector Integrating applications using rule connector element (see page
element. 620)
Rule designer elements

Rule designer provides drag and drop elements that can be used to create a business rule. These elements are available
in the Palette section of the Rule designer user interface.
Note
The details about Rule designer elements are given in the following table:
Category Element Name Symbol Description
Trigger Trigger A trigger element is used to indicate when the particular rule should get initiated.
See Defining a trigger for a rule (see page 495).
Qualifications Qualification Qualification element is used to set a particular condition to initiate some other
action.
Platform Actions Signal Process Notifies a process that is in an idle state at the receive task stage.
Start Process Initiates the selected business process that matches the rule condition.
Cancel Process Stops the current process that is being executed. When this action is executed, all
instances that match the Context Key are cancelled.

Assignment Automates the task assignment by using machine learning.
See Automating categorization and assignment by using the cognitive elements (see
page 478).
Association Associate Child Associates a record definition with another that is inherited within the other record
Record definition.
Associate Records Associates two record definitions that can be interlinked to function in conjunction
with each other.
Disassociate Removes the relationship between the two associated record definitions.
Records
Disassociate All Removes the relationship between all the associated record definitions.
Records
Cognitive Suggest Category Automates the manual task of data categorization by using machine learning.
See Automating categorization and assignment of application requests (see page 478
).
PIN Verify Pin Verifies if the PIN value provided by a user matches the PIN value set for that user.
For more information about Verify Pin, see Validating and verifying a PIN value (see
page 486).
Records Create Record Creates a record instance for a specified record definition.
Delete Record Deletes a record instance for a specified record definition.
Get Record Retrieves a record instance for a specified record definition.
Retrieves a set of record instances based on a specified query.

Get Records By
Query
Remove Security Deletes a security label for a specified record definition. To identify if the security
Label label is updated, see Identifying updates to the security label (see page 460).
Note: The SECURITYLABELCHNG() function is supported only with the Record Event
trigger type. If you use SECURITYLABELCHNG() function with the Timer Event or
System Event trigger type, an error is generated while saving the rule.
Set Security Label Assigns permissions about which user, role, or group can access a particular record
definition.
To identify if the security label is updated, see Identifying updates to the security label
(see page 460).
Note: The SECURITYLABELCHNG() function is supported only with the Record Event
trigger type. If you use SECURITYLABELCHNG() function with the Timer Event or
System Event trigger type, an error is generated while saving the rule.
Update Record Edits a record instance for a specified record definition.
User Message Send Message This action sends message to designated Recipient(s) using the pre-existing template.
Specify the “Subject”, “Body” and Recipient list and Template name to define the
action. You can use field values of current record for the same.
Send Message By This action sends message to designated Recipient(s). Specify the “Subject”, “Body”
Template and Recipient list to define the action. You can use field values of current record for
the same.
Show Alert Use the Show Alert action to display an error, warning, information that meets the
rule conditions. You can define Alert text, Alert code and Alert type for this element.
Expressions Evaluate Expression This Action is used to evaluate any expression and returns the output which can be
mapped to current Record’s field value on which the rule is triggered.
Provide the expression as input to this action and define output map to capture the
evaluated value.
Related topic
Creating rules
R ules define the business logic of your Digital Service applications. You can create rules to interact with a process, send
notifications, integrate your application with third party systems, and so on.

Before you begin

Before you create rules, ensure that you have created a project and deployed it in BMC Helix Innovation Studio. For
more information, see Creating a Project using Maven and the Archetype (see page 806).
Note
To create a rule
2. Select the application in which you want to create a rule.
3. In the application, click the Rules tab and, then click New.
The Trigger element appears on the canvas by default.
4. In the Properties pane, on the General tab, enter the values for the following rule parameters.
Name Description
GENERAL
Name Name of the rule.
Description Description of the rule that helps you understand the purpose of the rule.
Scope Option to define the scope for a rule definition. This option further contains the following options:
/Customization
Application/Library (default)—To limit the use of the definition within the same application or library.
Options
Enabled Select to enable the rule.
RECORD DEFINITIONS
Add/Remove Specify the record definitions to which the rule applies.

Record Note: The Application/Library scoped definitions are marked with an asterisk ( * ). Ensure that you follow the guidelines listed in
Definitions Guidelines to define scope for the definitions (see page 319) before you select these definitions.
5. From the Palette, drag and drop the elements to the canvas in the order that you want them in the rule. For
information on elements, see Rule designer elements (see page 491).
6. Enter the values for the properties of the Trigger element and all the elements that you add to the rule.
7. Click Save.
Related topic

Defining a trigger for a rule

In the Rule designer (see page 491), the Trigger element is used to create a trigger that defines the conditions under
which a rule is initiated.
This topic describes the types of triggers, gives the procedure to define the trigger in a rule, and examples of using each
trigger type in a rule.
Trigger types
The following trigger types are available in BMC Helix Innovation Studio:
Trigger Description
type
Record The Record Event trigger type initiates a rule when any of the following events takes place on the record definition:
Event
When the record definition is created, updated, deleted, or imported. When you want a rule to perform actions in the transaction of the
trigger operation, you can use rules to trigger workflows on On Create, On Update, On Delete, and On Import record events.
After the record definitions are created, updated, deleted, or imported. When you want a rule to be initiated after record definitions are
saved in the system, you can use the After Create, After Update, After Delete, and After Import events. Actions that run after the record
transaction cannot update the transaction record.
Example: If you want to automatically start an approval process after a purchase request is saved, you can use the After Create record
event.
Execution order allows you to set the precedence for the rules when more than one rule is associated with the same record definition.
For an example of using the Record Event trigger in a rule, see Trigger a rule on the On Create Record event (see page 496).
Timer The Timer Event trigger type initiates a rule when you specify one of the following time-specific events:
Event
Interval—You can specify the required duration to trigger a rule in the Interval Definition field.
Schedule—You can specify the required schedule time to trigger a rule in the Schedule Definition field.
Pool Number—You can use escalation pools to distribute the load. The pool number should be between 1 and the number of threads
configured for the escalation queue. If the Pool Number is blank or outside the valid range, the escalation is assigned to Pool Number 1
and is run by the first escalation thread.
For an example of using the Timer Event trigger in a rule, see Trigger a rule on a Timer Event (see page 496).
System The System Event trigger type initiates a rule when the following event takes place:
Event
EmailReceiveEvent—You can specify this trigger to initiate a rule after an email is received.
Note: You can use only the Start Process, Cancel Process, Connector, and Signal Process actions with the EmailReceiveEvent.
You cannot configure the Output Map for System Event trigger type.
For an example of using the System Event trigger in a rule, see Trigger a rule on the System Event (see page 497).
To define the trigger in a rule
1. Log in to BMC Helix Innovation Studio and navigate to the Workspace ta b.
2. Select the application in which you want to create a new rule.
3. In the application, click the Rules tab.
4. Click New.
The system opens the Rule designer and displays the rule diagram on the canvas.
5. Innovation Suite 18.11

BMC Helix Page 495
5. Select the Trigger element and in the Element Properties tab, select the appropriate trigger type.
6. Define the properties of the selected trigger type.
7. Save the rule.
Examples of trigger types
Example: Trigger a rule on On Create Record event (see page 496)
Example: Trigger a rule on Timer event (see page 496)
Example: Trigger a rule on System event (see page 497)
Example: Trigger a rule on On Create Record event

The following image illustrates a sample rule that starts a process when a new task is created:
Example: Trigger a rule on Timer event

The following image illustrates a sample rule that triggers a process based on a schedule specified in a timer:

Example: Trigger a rule on System event

The following image illustrates a sample rule that triggers a process to create a ticket when a new email is received:
Related topic
Defining a document schema

A document definition is a schema with fields defined in JSON format. You create a document definition to access
individual attributes within a metadata object and then use those attributes in an expression for a process. A document
definition supports only JSON key value pairs to access attributes, such as a complex object, an array of objects, an array
of strings, or nested complex objects.

A document definition defines the communication between two third-party modules. You can define a document
definition when you communicate with a third-party module by using custom actions or connectors. The document
definition enables you to access the attributes returned by the custom actions or connectors and use these attributes as
an input or output within a process.
Example
Consider a scenario where you use a JIRA connector to create a new record instance when a JIRA issue is
created. The connector action returns a JSON key value pair as a result. You can use an Object type variable to
access the JSON result, but the Object type variable does not allow you to access specific attributes within
this result.
To overcome this issue, you create a document definition to access each attribute within the JSON key value
pair and create a new record instance.
To create a document definition
2. Select the application for which you want to add a document definition.
3. On the Documents tab, click New.
4. In the Create Document Definition window, specify the properties for the document definition.
Document Name Type a unique name that identifies the document.
Document Schema Provide a document schema in JSON format that defines the property structure of the document definition.
Example 1:
{
"status":""
}
Example 2:
{
"status":"",
"error":{
"errorCode":"",
"errorMessage":""
}
}
Scope/Customization To define the scope of the document definition set the following options:
Options

(Default) Application/Library—Limits the use of the definition within the same application or library.
Public—Enables the definition to be used by all applications or libraries and allows customization to this
definition.
5. Click Save.

Action Reference
Use the created document definition to access complex objects, array of objects, array of strings, and nested complex objects Adding process variables
within the metadata object and use these objects as input or output to an expression within a process. (see page 425)
Create data for the structure defined by document definition. Creating a document
instance (see page 488)
Expression Editor
BMC Helix Innovation Studio provides an Expression Editor in the View designer, Process designer, and Rule designer that
you can use to configure the data required for views, processes, and rules of an application. For example, you can
provide an expression to configure the data of input map properties of a Call Activity in a Process designer.
For information about Expression editor in the View designer, see Creating or modifying view definitions (see page 378).
For information about expressions, see Types of expressions in expression editor (see page 1017).
Expression Editor in Process designer and Rule designer consists of the following sections:
Expression builder where you build the expression
Virtual keyboard
Context based dictionary UI from where you can pick an expression of a process variable, a keyword, and an
activity result.
Data dictionary UI
The following table describes the nodes in the Data dictionary UI:
Dictionary Description Expression

node
Process The process variables that you define in the process definition are available in the Expression ${processContext.
Variables Editor. This includes the process input parameters, output parameters, and local variables. <variable id or name>}
If a process variable is a record, and has associations, the associations are available in the ${processContext.task.
Expression Editor which help to navigate to the associated records without using query. _associations.
<association definition
GUID>.nodeA/nodeB...}
Activities The results of all the activities that have outputs are available in the Expression Editor. The results ${activityResults.
of all the activities are captured in the process context and you do not have to store an activity <activity GUID>.field}
result by using the activity output mapping. You can use an expression to pass the activity result to
other activities.
General

Dictionary Description Expression

node
The keywords such as Server URL, Current date, Current date and time, Current Groups, and so on $<keyword name>$
are available in the Expression Editor.
Errors This node is available only if you have already defined an Error Boundary event (see page 452) ${errors.
earlier in the process. <errorBoundaryEventGUID>.
errorMessageOrClass}
You can use an expression to access the exception class and error number (for Java exception
error), or error message (for business error) caught by the Error Boundary event.
Email This node is available only when you are using the Email Receive Event (see page 495) in a rule. "${ruleContext.
Receive mailSentTo} = \"
The incoming mailbox attributes, such as mailbox name, email sent to, plain text body, and so on,
Event helpdesk@calbro.com\" AND
Fields are available in the Expression Editor.
( ${ruleContext.priority}
= \"1\" OR ${ruleContext.
priority} = \"2\" OR
${ruleContext.priority}
=\"3\") AND ${ruleContext.
plainTextBody} LIKE \"%
sometextfrommailbody%"
Expression Editor examples

The following table illustrates Expression Editor examples:
Configuration using Expression Editor Example
In Process designers and Rule designers, you can use regular

expressions in a Qualification (condition).
In Rule Designers, you can configure expressions in Rule

Qualification.
For example, the expression 'Created By' LIKE "%Mi%
Jo%" matches with Michael Jordan, Mike
Johnson, Micth Joe and so on.
In Process designers, you can use expressions in the following

components:
Get Records By Query action
In the condition for Exclusive gateway
User Task Completion condition
In the Process designers, expressions can be used only with the

LIKE operator.
The following characters are allowed in the expression:
%: Matches any string.
_ (Underscore): Matches any single character. For

example, the expression 'Created By' LIKE
"M_n" matches Man, Men.
[]: Matches any given char. For example, 'Flag'

LIKE [a-p] matches any char in given range a to
p.
Configure an expression by using individual attributes from a JSON

schema.

Configure an expression by using fields in the configured incoming

mailbox.
Configure condition using an activity result.

Configure the expression by using error details caught by the Error

Boundary event.
Configure a condition to check if the security label for a record Using Process:
instance is updated.
When using SECURITYLABELCHNG() function in a process,

add a record instance as a parameter. When using
SECURITYLABELCHNG() function in a rule, you do not need
any parameter.
Note: In Rule designer, the SECURITYLABELCHNG() function

is supported only with Record Event trigger type. If you use
SECURITYLABELCHNG() function with Timer Event or
System Event trigger type, an error is generated while saving the
rule.
For more information about configuring a condition to identify the

changes in security label, see Identifying updates to the security
label (see page 460).

Using Rule:
Configure a selection field.

Configure an association expression.
Server URL in user message.
Configure Start Process expression in a rule.
Symbols used in Expression Editor.

Related topics
Types of expressions in expression editor (see page 1017)
Creating configuration settings for your Digital Service application
In BMC Helix Innovation Studio, you can create configuration settings and configuration functions for your application.
The types of configuration settings includes a set of parameters, key-value pairs, or a data wizard.
Types of configuration settings

You can define one of the following configuration setting for a bundle:
Setting Description
Type
External When your configuration is outside BMC Helix Innovation Suite, you can add a link to the external configuration setting in your bundle. When users
Settings click the link, the configuration setting page opens in a web browser.
For more information, see Creating External Settings (see page 506).
In- In-bundle Settings leverages record definition and view definition in the bundle. This setting allows the configuration to have custom data and
bundle custom UI. Since the record definition and view definition is a part of the bundle, you can create custom logic and behavior within your application
Settings to manage the settings.
For more information, see Creating In-bundle Settings (see page 508).
Shared Shared settings are located in one bundle and can be accessed by other bundles. Shared configuration settings have a common storage location
Settings and UI.
Benefits of Shared Settings
Data is stored in a single location as key-value pairs and is accessible by any application deployed on BMC Helix Innovation Suite.
A unique permission model can be defined for each application even though the setting itself is shared.
The common user interface ensures consistent look and feel of the shared setting across all applications.

Setting Description
Type
Limitations of Shared Settings
Custom UI can't be used to configure the setting.
Custom logic can't be leveraged to manage settings.
More information on Creating Shared Settings (see page 511).
To create external settings

Add a link to your application that points to an external page with configuration settings. When users click the external
link, the page is opened in a new tab of the web browser.
Example
If your configuration exists outside BMC Helix Innovation Suite, you can provide a URL to an external application or
setting.
The following image is an example of an External Setting in the BMC Remedy Mid Tier:
2. Select the application or library bundle for which you want to create an External Setting.
3. Click the Configurations tab.
4. Select New > External Settings.
5. In the New External Settings window, specify the properties for the setting.

5.
Property Description Sample values
Component Enter a unique name for your Setting. The name is displayed in the Configurations tab in your bundle's Workspace. GoogleSettings
Name
External Specifies the URL that is launched when the user clicks the setting. http://www.
Link google.com
Status Select the status of the setting as ON or OFF. ON
Available in If you want the setting to appear in the left hand navigation of the Settings menu either in your application or in ON
Navigation the BMC Helix Innovation Studio Administration tab, select ON.
Sidebar
Component Enter the display name of the Setting that appears in your application or in BMC Helix Innovation Studio. Google
Label Settings
Show In Select the location of your setting—in your application's Settings menu or in the Administration tab of BMC Helix Application
Innovation Studio, or both.
Permissions Select the roles and groups that can access the Setting. You can add permissions to groups or application roles. Administrator
You can select roles from multiple applications deployed on the system. group
First Menu Enter the name of the top level navigation item that is displayed in the left hand navigation of the Settings menu. If External
multiple settings use the same name for First Menu, then all those settings appear under the same navigation item. Settings
Second Enter the name of the second level navigation item that is displayed in the left hand navigation of the Settings Level 2
Menu menu. If left blank, no second level item will appear. If multiple settings use the same name for Second Menu, then
all those settings appear under the same navigation item.
6. Click Save.
Example
You want to give an external link to Google website. If you enter the sample field values, the external setting in the
application is displayed as follows:

To create in-bundle settings

You can create an In-bundle Setting by using any of the following methods:
By using Angular JS (see page 508): Register a custom angular app by using Angular JS, and then use that app for
creating an In-bundle Configuration setting in BMC Helix Innovation Studio.
By using BMC Helix Innovation Studio (see page 509): Use a View definition for creating an In-bundle Setting for
your application or library.
By using Angular JS
Step 1: Register the custom angular app by using Angular JS
1. Decide how you want to manage your Setting in an application.
2. Create a directive for your UI entry point.
3. Register with the Admin Settings Service Provider.

Example:
(function() {
'use strict';
angular.module('ax.tenants').config(function(rxAdminSettingsCustomViewProvider)
{
rxAdminSettingsCustomViewProvider.registerComponent({
componentName: 'manage-tenants',
runTimeDirective: 'manage-tenants'
});
});
})();
Step 2: Use the custom angular app in BMC Helix Innovation Studio
2. Select the application for which you want to create an In-bundle Setting.
4. Select New > In-bundle Settings.
5. In the New In-bundle Settings window, specify the properties for the setting.
Property Description Sample
values
Component Enter a unique name for your Setting. The name is displayed in the Configurations tab in your bundle's Workspace. Tenant
Name activation
Is View Opens a view definition in the bundle in the application Selected

Component
Registered Specifies the unique name of the registered module

manage-
Module
tenants
Name


values
Status Select the status of the setting as ON or OFF. ON
Available in If you want the setting to appear in the left hand navigation of the Settings menu either in your application or in the ON
Navigation BMC Helix Innovation Studio Administration tab, select ON.
Sidebar
Component Enter the display name of the Setting that appears in your application or in BMC Helix Innovation Studio. Activating
Label tenants
Permissions Select the roles and groups that can access the Setting. You can add permissions to groups or application roles. You Administrator
can select roles from multiple applications deployed on the system. group
First Menu Enter the name of the top level navigation item that is displayed in the left hand navigation of the Settings menu. If My settings
multiple settings use the same name for First Menu, then all those settings appear under the same navigation item.
Second Enter the name of the second level navigation item that is displayed in the left hand navigation of the Settings menu. Tenant
Menu If left blank, no second level item will appear. If multiple settings use the same name for Second Menu, then all those settings
settings appear under the same navigation item.
6. Click Save.
Example
If you enter the sample field values, the in-bundle setting in the application is displayed as follows:
By using BMC Helix Innovation Studio

In this method, you use a newly created or existing view definition to create the configuration setting for your
application.
2. Select the application for which you want to create an In-bundle Setting.
5. In the New In-bundle Settings window, specify the properties for the setting.

5.

values
Component Enter a unique name for your Setting. The name is displayed in the Configurations tab in your bundle's Workspace. Tenant
Name activation
Is View Opens a view definition in the bundle in the application Selected

Component
Registered Specifies the unique name of the registered module, which is the view definition that you created Approval
Module Console
Name
Status Select the status of the setting as ON or OFF. Selected
Available in If you want the setting to appear in the left hand navigation of the Settings menu either in your application or in the Selected
Navigation BMC Helix Innovation Studio Administration tab, select ON.
Sidebar
Permissions Select the roles and groups that can access the Setting. You can add permissions to groups or application roles. You Administrator
can select roles from multiple applications deployed on the system. group
Component Set the display name of the Setting that is shown in your application or in BMC Helix Innovation Studio. Activating
Label tenants
First Menu Enter the name of the top level navigation item that is displayed in the left hand navigation of the Settings menu. If My settings
multiple settings use the same name for First Menu, then all those settings appear under the same navigation item.
Second Enter the name of the second level navigation item that is displayed in the left hand navigation of the Settings menu. Tenant
Menu If left blank, no second level item will appear. If multiple settings use the same name for Second Menu, then all those settings
settings appear under the same navigation item.
6. Click Save.
Example
The following illustration shows the flow of creating an In-bundle Setting:

To create shared settings
2. Select the application or library bundle in which you want to create the shared setting.

4. Select New > Shared Settings.
5. In the New Config window, on the General tab, specify the properties for the setting.
The following table provides information about the Setting properties:
Component Enter a unique name for your Setting. The name is displayed in the Configurations tab in your bundle's Workspace.
Name
Show In Select the location of your setting—in your application's Settings menu or in the Administration tab of BMC Helix Innovation Studio,
or both.
Component Enter the display name of the Setting that appears in your application or in BMC Helix Innovation Studio.
Label
Status Select the status of the setting as ON or OFF.
Setting Select on the the following options:

Repeat ON—If the setting can have multiple saved values.
OFF—If the setting can only have one saved value.
Setting Select the parent for this setting. When selected, this setting will show up within the selected Setting and not in a menu.
Parent
Permissions Select the roles and groups that can access the Setting. You can add permissions to groups or application roles. You can select roles
from multiple applications deployed on the system.
Available in If you want the setting to appear in the left hand navigation of the Settings menu either in your application or in the BMC Helix
Navigation Innovation Studio Administration tab, select ON.
Sidebar
First Menu Enter the name of the top level navigation item that is displayed in the left hand navigation of the Settings menu. If multiple settings
use the same name for First Menu, then all those settings appear under the same navigation item.
Second Enter the name of the second level navigation item that is displayed in the left hand navigation of the Settings menu. If left blank, no
Menu second level item will appear. If multiple settings use the same name for Second Menu, then all those settings appear under the same
navigation item.
6. To add one or more fields in the Settings window, click (+) New Field and then select the field type.
7. In the Properties tab, specify the properties of the field.

The following table provides information about the field properties:
Field Name Enter a unique name for the field. The name is displayed in list of fields for your setting.
Field Label Enter the display name of the field that appears in your application or in BMC Helix Innovation Studio.
Required Select this option when you want it to be a mandatory configuration field.
Permissions Select the roles and groups that can access the Setting. You can add permissions to groups or application roles. You can
select roles from multiple applications deployed on the system.
Default Value Set the default value of the field. If left blank, the field will not have a default value.
Key Field for Select if this field is repeated.

Repeated Setting
8. (Optional) To add a field group to a shared setting, click Manage Field Groups and then select the field group.
9.
9. Click Save.
Example scenarios of configuration settings for an application
Examples
Example 1: Define properties that can be accessed by all users of an application
Consider that you want to define a singular set of properties that affect all users who use the Task application. For
example, you can define the following properties:
AutoCloseCompleteTask (Boolean)
AutoCloseDays (Integer)
NotifySubmitterOnClose (Boolean)
These settings can be defined so that only the users having Task Config permission can access and populate these
properties. The properties, in turn, influence the business process and application behavior. After you define the
properties, users can access them in different ways such as on the Administration tab of BMC Helix Innovation
Studio.
You can then define a process that searches for these settings and values, and follow different business processes
based on the content. This makes the application data configurable.
Example 2: Specify a set of properties that can be defined for each user of an application
Consider that you want to define ShowFullName (Boolean) property. After you define the setting, it can be
repeated for multiple users for defining application settings stored at an individual user level.

Example 3: Specify a set of properties that can be defined and restricted based on data other than group
Consider that you want to define a property based on multiple types of a ticket priority. For properties that are
repeated in Settings, you can define a parent-child relationship between the Settings. This means that you define a
dependency of one Setting on another Setting.
Here, Setting 2 is configured as the parent Setting for the Urgency-based Setting.


Task Reference
Extend the service objects and customize their behavior. Creating a custom service in Java (see page 823)
If you have completed all tasks of developing your application, package and test the Getting your Digital Service application ready for use (see page
application. 915)
Making definitions available for customization

Your Digital Service application users can customize record definitions, view definitions, process definitions, rule
definitions, named list definitions, and association definitions of your application. By default, these definitions are not
customizable, you can make them available for customization by using corresponding designers in BMC Helix Innovation
Studio. For example, you can make the record definition available for customization by using the Record designer.
Configuration settings and the data exported or deployed with the application (bundle data) are always customizable.
There is no customization option available in BMC Helix Innovation Studio to disable the customization of these
definitions.
Definition scope
The column Scope displays the following options for the definition:
Application—Limits the use of the definitions within the same application.
Note
The Library option is available for all definitions in a library.
Public—Enables the definitions to be used or referenced by all the applications or libraries and further enables
the customization of definitions.

For more information about Definition scope and the guidelines, see Object definition scope (see page 43) and
Guidelines to define scope for the definitions (see page 319).
You can view the scope for record definitions on the Records tab.
Customization status
Definitions can have any of the following customization statuses:
Customized–A tenant or a user has customized the definition.
Not Customized–A tenant or a user has not customized the definition.
Not Applicable–The definition cannot be customized by a tenant or a user.
You can view the customization status for record definitions on the Records tab.
To make a definition available for customization

Before you enable the definitions for customization, ensure that you follow the guidelines listed in Guidelines to define
scope for the definitions (see page 319).

For record definitions
2. Select the application or library for which you want to customize the definitions.
4. In the Details pane of the Record designer, click Scope/Customization Options.
5. In the Scope/Customization Options window, from the Definition Scope, select Public.
For more information, see Guidelines to define scope for the definitions (see page 319) .
Note
If you do not select Public, the Allow future customization to this Record Definition customization
option is not available.
6. Select the following customization options according to your requirements.

Customization option Description
Allow future customization to this Record Makes the record available for customization.
Definition Note: If you do not select this option, the following customization options are not available.
Properties of this Record Definition Allows customization of record definition properties (not the permissions and indexes)
Permissions of this Record Definition Allows customization of record definition permissions
Search Indexes of this Record Definition Allows customization of search indexes
Record Definition fields within this record Allows customization of fields in the record definition
7. Provide the customization options for the record fields by selecting the Allow Future Customization to this
Record Definition and Fields within this Record Definition options.
To allow field properties customizations, select Allow Properties Customization checkbox for the field.
To allow field permission customizations, select Allow Permission Customization checkbox for the field.
8. Click Save.
The following image shows the customization options for a record definition:

For view definitions, process definitions, rule definitions, named list definitions and association definitions
2. Select the application or library for which you want to customize the definitions.
3. On the appropriate tab, select the definition and click the definition name.
4. In the Details pane of the designer, click Scope/Customization Options .
5. In the Scope/Customization Options window, from the Definition Scope, select Public.
For more information, see Guidelines to define scope for the definitions (see page 319) .
Note
If you do not select Public, the Allow future customization to this Definition customization option is
not available.
6. Select Allow future customization to this Definition to make the definition available for customization.
7. Click Save.
The following image shows the customization options for a view definition:

Related topic
Guidelines for Digital Service application definitions customization (see page 313)
Creating and customizing application views by using Shell

You can design a special configurable view for applications. A view is an outer container of an application, and acts as an
entry point for users to access the application on the Web. To design a view, you use BMC Modern Shell, which is a built-
in landing page and default menu system that is configured for every application.
BMC Modern Shell enables you to:
Design the application UI without requiring coding skills

Create header and navigation by using inbuilt navigation and framework services from BMC Modern Shell
Enable navigation between views in an application

You can toggle between the views created by using BMC Helix Innovation Studio and the contents available in the
current web application in the form of HTML, JavaScript and CSS code.
Customize the list of navigational links and the list of actions
Control user access by assigning permissions to Shell menu items
For every application, the shell navigation is generated by application archetype and is available for an application in the
BMC Helix Innovation Studio.
The following image shows the Shell editor for Task Manager application:

The following image shows the application view when users access the Task Manager application:
To access the Shell editor for applications
2. Select the application that you want to modify.

The application details are displayed.
3. From the application, click Edit beside BMC Modern Shell.

The BMC Modern Shell Designer is displayed.
Process for designing an application view in Shell

You can design the application’s view in BMC Modern Shell by configuring the following items:
Action Description Example
View in Shell editor:

Add Provides
navigation navigation
components options for the
to the end users.
View in deployed application:
header
For more
information, see
Adding navigation
components to
header (see page
523)
Assign Enables you to If you assign permissions to the Administrator group for a Shell menu element, only those users belonging to the
permissions control access to Administrator group, such as IT Helpdesk Administrators, can see and access the Administration menu group. Users who
to menu Shell menu items are not a part of the Administrator group, such as IT helpdesk agents, cannot access the Administration menu group. See
components of view the following image:
components, by
assigning
appropriate
permissions to
them in BMC
Modern Shell.
For more
information, see
Controlling user
access by
assigning
permissions to
menu elements
(see page 529).
Enable Enables the end

switching users to toggle
between between multiple
applications between
applications.
For more
information, see
Toggling between
application views
and viewing
notifications (see
page 533).
Enable and Implements The following image shows a sample search result with default configuration:
customize search for the
global end users of your
search application.
Global search
provides default
and customized
search options.
For more
information, see
Enabling and
customizing
global search
(see page 526).

View and Provides

customize information
the user about the user
profile and the
application
settings for that
user. You can
customize this
component by
adding additional
menu items to it.
For example, you
can add a link to
the user's profile.
For information
about how to
customize the
user menu, see
To customize the
user menu (see
page 523).
Track Tracks
notifications notifications
created by
application, so
that users are
aware and can
take necessary
actions.
For more
information, see
Toggling between
application views
and viewing
notifications (see
page 533).

The following image shows a sample notification:
Related topic
Creating configurations for your Digital Service application (see page 505)
Adding navigation components to header

BMC Helix Innovation Suite provides a few Shell navigation components that can be customized. These components are
available in the palette section. You can use the components by dragging them on the canvas and providing the
properties for the components.
The shell navigation components available in the shell are described in the following table:
Component Symbol Description Example
Menu Item Menu item is used to The following image shows an Administration menu group:
launch an action in a
navigation bar, such as
navigate to a view,
navigate to a state or
launch an URL.
Menu Menu group is used to The following image shows Customer groups and Customers menu items within the
Group group one or more menu Administration menu group.
items. You can add the
menu group to the
navigation bar and add
menu items to the menu
group.

Component Symbol Description Example
Note
You can customize the objects developed in your own applications, but cannot customize the objects
developed in com.bmc.arsys. For example, objects in core BMC applications like Foundation, Approval, and
Assignment cannot be customized.
To add navigation components to an application header

3. From the application, click Navigation.

4. From the Shell Navigation section, drag the Shell menu element you want to add to the palette.
5. From the Settings tab of the Properties pane, provide the following information:
Field Description
Label Enter a unique name for the Shell menu element.
Icon
Select the icon you want to display beside the Shell menu element. For example, if you select add circle icon, a
icon is displayed beside the Shell Menu element.
Note: This option is available only for Shell menu items.
Action to Trigger Specify the action that must be executed when the Shell menu item is accessed. For example, select to launch a URL,
navigate to a view or state, or navigate to Reporting. Note: This option is available only for Shell menu items.
Hidden Select if you want to hide the Shell menu element in specific conditions, such as, if you want to disable the element at all
times or when a specific condition is met.
Permissions Click Edit to control access to Shell menu elements of view components by assigning appropriate permissions to the
elements. For more information, see Controlling user access by assigning permissions to menu elements (see page 529).
Input Parameters Specify the details for the action that you selected to trigger when users access the Shell menu item. If you selected to
launch a URL, provide the URL. If you selected to navigate to a view, select the view that users should navigate to. Note:
This option is available only for Shell menu items.

To customize the user menu

You can add multiple Menu Item elements, such as My Profile and Edit My Profile, to the User Menu component.
However, you cannot add the Menu Group element to the User Menu component.


The BMC Modern Shell designer is displayed.
4. From the Shell Navigation section, drag the Menu Item element to the User Menu component.
The following image is an example of a View Profile menu item that is added to the user menu:
5. From the Settings tab of the Properties pane, modify the properties for the Menu Item element.
6. Click Save.
When users access the application, they can see details about their account and the application settings.
To troubleshoot permission issues for accessing Shell navigation components

In the deployed application, a blank view is displayed if you do not have permissions to access the first menu item of BMC
Modern Shell.
This issue occurs because BMC Helix Innovation Studio supports direct access URL and tracks the last accessed URL
before redirecting you to the BMC Helix Innovation Studio login page. When you log in to BMC Helix Innovation Studio
by using a web browser instance that was previously used by another user, BMC Helix Innovation Studio redirects you to
the last-accessed URL or view.

In this case, perform any one of the following actions:
Different users can use different web browsers to access BMC Helix Innovation Studio on the same computer.
Clear the cache after the first user has logged out if you want to use the same web browser instance.
You must clear the cache even if you are using incognito mode of the web browser.
Related topic
Creating and customizing application views by using Shell (see page 519)
Enabling and customizing global search

Using the Global Search option, you can implement search for the end users of your application. By using the search
feature, the application users can perform search operations within the application.
Before you begin
Configure the Full Text Search (FTS) (see page 526).
Your application must consist for the following elements:
Record definition that consists of at least one text field that has the FTS property enabled (search field).
You can create multiple record definitions to include in the search.
View definition that consists of record editor component for each record definition with search fields
added. The view needs to have an input paramater that is bound to the ID of the record from the search
results and the record editor Record ID should point to that view parameter.
Record instances of the record that have data for the search fields. This data is used in the search
operations.
For more information on creating record definitions and record instances, see Defining record definitions
to store and manage data (see page 324) .
To configure FTS before you customize global search
1. Log in to BMC Remedy Mid Tier.
2. Navigate to the AR System Administration FTS Configuration form (BMC Remedy AR System Administration
Console > Common Server Configuration > General > FTS Configuration).
3. Select the FTS Agent checkbox and click Save.
To enable global search and customize search views

By default, the Global search option is disabled. You can use the default search results view or can use a custom view to
display search results.
To configure default search results

You can use the default search results view by enabling the Use default search result view option and configuring search
results view.
2.
2. Select the application.
3. Navigate to Application Shell and Global Navigation and click Edit.
4. On the canvas, select the navigation bar and in the properties, uncheck Disable Global Search.
5. Select Use default search result view and click Configure results view.
6. On Configure Results View, add the records to include in the search result, select the view from the Display View
When Clicked drop down list, and click Save.
7. Save the changes to the shell and close the shell.
To use a custom view

To display search results by using a custom view, disable the Use default search result view option and provide the value
for Custom Search State.
To disable global search

In the navigation bar properties, select Disable Global search.
To test global search
1. In the BMC Helix Innovation Studio and navigate to the Workspace tab.
2. Select the application and click Visit Deployed Application.
3. On the navigation bar of the application, click , and enter the search string.
The search results appear in new window.
The following image shows a sample search result with default configuration:

The annotations in the image are described in the following table:
Annotation Description
1 Search string used to perform search.
2 Search results are stored in the order of relevancy. You can use the filter to specify the record definitions that should be included in the search
results.
3 Search results have the following format:
Record definition name is displayed as a nonclickable text.
ID is displayed as a clickable link that navigates to the view set for the record definition in default search view properties
The second line displays the title of the result and the hit for search match is displayed in the third line with the exact search string
highlighted.
4 Search results are sorted in descending order by relevancy.
5 By default, the first 50 search results are displayed. The search page utilizes an infinite scroll pattern. When you scroll down, the page loads a
chunk of 50 additional search results at the bottom of the page.
Related topics
Enabling access to reports within an application

Reports enable the users of an application to view and analyze the application data based on different criteria. For
example, the user of an application views the application data to analyze the performance of all the teams, number of
hours each team worked, number of issues each team resolved, and so on. By analyzing the application data, users can
also identify the low and high performance points in the application and take necessary actions.

You can enable launching the Reporting dashboard from an BMC Helix Innovation Suite application. Application users
can access their reports directly from the application UI.
Before you begin

Ensure that the SaaS administrator has performed the following tasks:
Performed onboarding of customers.
Specified report and centralized configuration settings in Remedy Mid Tier.
To enable access to Reporting from an BMC Helix Innovation Suite application
2. Select the application from which you want to launch Reporting, and click Navigation.
3. From the Shell Navigation section, drag the Menu item element to the canvas.
4. On the Properties tab, click and enter the following information:
a. In the Label field, enter an appropriate name for the menu item. For example, Reports.
b. From the Action to Trigger list, select Launch URL.
c. In the Input Parameters section, enter the Reporting URL in the URL field.
5. Click Save.
To access Reporting from an BMC Helix Innovation Suite application
1. Log in to the application in which you provided access to Reporting.
2. On the navigation bar, look for the option to launch Reporting.
3. Click the option to access reports.
Related topic
Controlling user access by assigning permissions to menu elements (see page 529)
Controlling user access by assigning permissions to Shell menu elements

You can control access to Shell menu elements of view components by assigning appropriate permissions to the
elements in BMC Modern Shell. BMC Modern Shell is a built-in landing page and default menu system that is configured
for every application. You can assign permissions to Shell menu elements, such as menu groups and menu items.
This capability provides the following benefits:
Controls access to certain Shell menu elements.

End users who have appropriate permissions can view and access the application's Shell menu elements. Users
without appropriate permissions cannot view or access the Shell menu elements.

Protects against unauthorized access or activity through menu elements during application runtime.
For example, if you assign permissions to the Administrator group for a Shell menu element, only those users belonging
to the Administrator group, such as IT Helpdesk Administrators, can see and access the Shell menu element. Users who
are not a part of the Administrator group, such as IT helpdesk agents, cannot access the Shell menu element.
You can assign permissions to Shell menu elements while customizing the applications in BMC Helix Innovation Studio.
Note:
If permissions are not assigned for a Shell menu element, by default, BMC Helix Innovation Suite assigns public
permissions to that menu element. All end users, regardless of their user role or group, can see and access the
menu element.
The following illustration provides additional information about assigning access permissions to Shell menu elements:
To assign permissions to Shell menu elements

3.

4. From the Shell Navigation section, select the Shell menu element for which you want to control access.
You can select any one of the following Shell menu element:
Shell Description Example
menu
element
Menu Combines one or more menu items into a group. You The following image shows an Administration menu group:
group can add the menu group to the navigation bar and add
menu items in the menu group.
Menu Launches an action in a navigation bar, such as navigate The following image shows Customer groups and Customers menu items
item to a view, navigate to a state, or launch a URL. within the Administration menu group.
5. From the Settings tab of the Properties pane, click Edit beside Permissions.
6. In the Add Edit Permissions dialog box, specify the user permissions by providing the following information and
click Save to save the permission updates:
Field Description
Type Specify whether you want to assign permissions to a user group or user role. A user can acess the Shell menu element if a group the user is
in has access, or a role mapped to such a group has access. You can provide permissions for any of the following user profiles:
User group: Provides access to user groups based on a common profile. For example, assigning permission to Administrator user
group.

Field Description
User role: Provides access to user roles for specific applications. Application roles are permissions similar to groups, except that
they belong to a particular application, instead of a particular server. Application roles are used exclusively in deployable
applications.
For more information, see Creating and modifying application roles (see page 749).
Group Select the user group or user role to which you want to assign access permissions. Only those users who belong to the selected group or
role can view and access the Shell menu elements.
The following image shows the Edit Permissions dialog box for Administration menu group:
7. Click Save to save the changes made for the application.

The permissions are assigned to the Shell menu elements.
When end users access the deployed application, those who belong to the Administrator user group, such as IT helpdesk
administrators, can view and access the Administration menu element.

End users who do not belong to the Administrator user group, such as IT helpdesk agents, cannot see the Administration
menu element.
Related topics
Toggling between application views and viewing notifications

The navigation bar consists of a switch that allows you to switch between multiple applications. It contains the list of
applications in your environment (the list of application bundles deployed).

To enable switching between applications, perform the following steps:
2. Select the application.
3. Navigate to Application Shell and Global Navigation, and click Edit.
4. On the canvas, select the navigation bar and in the properties, select Allow switching between apps.
5. Click Save.
To verify the working of the application switcher, click Visit Deployed Application. For example, for the Task Manager
application, the application switcher appears on the navigation bar as shown in the following image:
To track notifications
The notification option is used to track notifications. Notifications can be text messages or HTML messages that
are sent from an application user. The following images show sample notifications:

The annotations in the image are described in the following table:
Annotation Description
1 Notification count is the count of active notifications.
2 View all is used to display all the notifications.
3 Delete icon is used to delete the notification.
You can send notifications to an application users by using a process. For information on sending notifications, see
Process Designer elements: User Message (see page 421).
Related topics
Configuring
This section provides information on how you can use BMC Helix Innovation Suite services and libraries to customize
your applications:
Action Reference
To extend your application to include an approval mechanism that facilitates the end-to-end execution of events Adding an approval process to an
from the time a user makes a request till the request is addressed—either approved, rejected, or, cancelled. application (see page 536)
To automate your application workflow tasks, such as assignment and categorization, use the cognitive service Adding cognitive capabilities to a custom
application (see page 552)
To add conversation capability to your applications, use the chatbot framework that enables you to use the Adding a chatbot and conversational
virtual agent capability of Artificial Intelligence (AI) in your applications. capabilities to your application (see page
576)
To integrate an application with a third-party systems by using connectors.

Action Reference
Integrating with another application by

using a connector (see page 615)
To integrate with RESTful services in a codeless way. Integrating with REST services in a
codeless way (see page 604)
To enable automatic request assignment for application requests by defining the rules in an assignment policy Enabling automatic record assignment in
and triggering the policy from assignment processes. an application (see page 623)
Adding an approval process to an application

You can create an approval process to define workflows and logic required to approve your request for a particular
record and configure approval flows to define the overall completion criteria for the approval process. You can also
define views for your approval process so end users can submit approval requests and update it them. The Approval
Console displays all approval requests. For more information about the Approval Console, see Viewing and responding to
approval requests (see page 550) .
The following image illustrates the end-to-end process to create approval process and approval flows using BMC Helix
Innovation Suite .
Before you begin

Before you start adding an approval process to your application and configuring the approval flows, make sure you
complete the following activity:
If you want to use associations to display field values on the Approval Console, configure the record associations.
The associations will be displayed on record registration screen. For more information, see Creating record
associations (see page 342) .
To create an approval process and configure approval flows, perform the following tasks:
Action Reference
First, start by defining an approval process. Creating an approval process (see page 537)
If you want to evaluate some additional expressions,

create a self approval process with additional logic in it
and select it in the self approval flow.
Optionally, you can chain approval process to have

different flow groups approve your requests.
After you define the approval process, register the Registering a record (see page 543)
record definitions for which you want to create the
approval flows on.
If you want to define an approval that is approved by Configuring self approval flows (see page 544)
automatically by the system, create a self-approval
flow.
Configuring approval flows (see page 546)

Action Reference
If you wan to define an approval that is approved by an

individual or group, create an approval flow.
The requester gets notified when approval request is Creating approval notifications to notify approvers (see page 549)
approved, an approval request is rejected, an approval
request is reassigned, an error exists in approval
signature, and so on.
Related topics
Viewing and responding to approval requests (see page 550)
Approvals (see page 47)
Creating an approval process

Approval process defines logic, workflows, and specific steps required for the approval request to get approved. It
facilitates the end-to-end execution of events from the time a user makes a request until the request is addressed—
either approved, rejected, or cancelled. It defines workflows and logic required to approve your request for a particular
record. The workflow can have steps defined to generate the approval flows, approve, reject, reassign the request, or
cancel it. You can cancel user-driven approval requests that are in pending state. To generate approval flows for your
approval request, you must first define the approval process. Typically, for an approval process, a request record is the
input and an approval status is the output. An approval process, when triggered, generates signatures, handling all
notifications and approval responses.
Perform the following tasks to create an approval process, to define variables for an approval process that does not
require user intervention, and to chain approval processes.
Create a self-approval process for an approval request which does not require user intervention.
To create an approval process
1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab .
2. Select the application for which you want to create an approval process.
3. In the application, click the Processes tab, and select New.
4. To configure the process definition properties such as the process name, permissions for users who can run the
process, and variables associated with the process, on the Properties panel, click the icon and perform the
following actions :
1. a. Enter a Name and Description for the approval process.
b.
1.
b. To enable the approval process, select the Enabled check box.
c. From the Run as list, select the user who must run the approval process.
d. To configure process variables, i n the Variables section, click Add/Remove Variables and enter Input
/Output Variables as follows:
Input Variables—The input process variables are usually record instances for which the approval
process is being defined, such as:
Field Details
Name Enter a name for your input variable.
Variable Type Select Input/output Variable > Input.
Variable ID Leave blank for a regular approval process.

The value of this variable, if not specified, is generated dynamically. Specify this value when creating
self-approval process.
Data Type Select Record.
Record Select record instance for which you want to create the approval process.
Output Variables—The output process variables define the outcome of the approval process,
such as the status of the request. These are usually text fields.
Field Details
Variable Type Select Input/output Variable > Output
Variable ID Leave blank in regular approval process. The value of this variable, if not specified, is generated dynamically.
Data Type Select Text.
2. From the Approvals palette, drag the Approval Process element onto the canvas.
3. To configure the Approval Process element properties, perform the following actions and click Save:
a. Select the Approval Process element and then click the icon.
b. In Input Map, configure the following:
i. S elect the input variable which you defined while configuring process definition properties.
ii. (Optional) To specify an approval flow to use in this approval process, select Flow Group Name,
perform the following steps.
Note
If you have already configured a flow group, you can select it here. If the flow group is
not yet configured, leave this field blank. When it is blank, the Approval Process
dynamically selects an Approval Flow . To configure flow groups , s ee Configuring
approval flows (see page 546).
1. Next to the Flow Group Name label, click Select.

2. In the Select From Approval Flows screen, select the relevant flow group and click Use
Selected Flow.
3.
c. In Output Map , configure the following:
i. Select the Name from the list. This is the same name you gave to the output process variable.
ii. Select the Source of the output, which must be the Approval Status from the Approval Process.
The following video (7:30) demonstrates how to create an approval process.
https://youtu.be/s4RcufyJQJ8
To configure process variables for a self-approval process

Follow the same steps for creating self-approval process, except process variables and flow group .
1. To add process variables, i n the Variables section, click Add/Remove Variables and enter Input/Output Variables:

1.
Input Variables—The input process variables are usually record instances for which the approval process
is being defined.
Field Details
Variable Select Input/output Variable > Input.

Type
Variable Enter 57000. Since the self approval flow is run as a sub process within the approval process, the variable IDs ensures that the
ID correct information is passed to and from the self approval flow and the approval process.
Data Select Record.

Type
Record Select record instance for which you want to create the approval process.
Name
Output Variables—The output process variables define outcome of the approval process, for example
status of the request. These are usually text fields.
Field Details
Variable Select Input/output Variable > Output

Type
Variable Enter 57120. Since the self approval flow is run as a sub process within the approval process, the variable IDs ensures that the
ID correct information is passed to and from the self approval flow and the approval process .
Data Select Text.

Type
To configure process variables for chaining

When you chain a process, another process is triggered based on the outcome of the first process. To configure
chaining in an approval process, follow the same steps for creating an approval process, except the process variables.
You must define more than one input process variables.
1. To add process variables, i n the Variables section, click Add/Remove Variables and enter Input/Output Variables:
Input Variables—The input process variables are usually record instances for which the approval process
is being defined.
Field Details
Variable ID Enter 57000.
Data Type Select Record.
Record Name Select record instance for which you want to create the approval process.
Add another input variable with the following parameters:

Field Details

Field Details
Output Variables—The output process variables define outcome of the approval process, for example
status of the request. These are usually text fields.
Field Details
Variable Type Select Input/output Variable > Output
To cancel an approval request
2. Select the application or a bundle where you have created approval processes and for which you want to initiate
a cancellation process.
3. In the application, click the Processes tab, and select New.
4. To configure the process properties such as the name, description, and variables associated with the process, on
the Properties panel, click the icon and perform the following actions:
a. Enter a Name and Description for the cancellation service task.
b. To add process variables, in the Variables section, click Add/Remove Variables and enter Input/Output
Variables:
i. Input Variables—The cancellation process requires you to input two process variables—Record
Definition and Record Display ID:
Field Details
ii. Add another input variable with the following parameters:

Field Details
5. To configure the Cancel Approvals element properties, perform the following actions and click Save:
a.
5.
a. Select the Cancel Approvals service task element and then click the icon.
b. In Input Map, configure the following and click Save:
i. Record Definition: select the first process input variable.
ii. Record Display ID: select the second process input variable.

Action Reference
R egister the record definitions for which you want to create the approval flows. Registering a record (see page 543)
Related topic

Registering a record
Before you can configure approval flows, first you must register the record definition. The registration tab on the
approval wizard maps the record fields with the columns on the approval console.
Before you begin

Before you start registering a record, make sure you complete the following activities:
Create a record definition that you want to use in the approval process and set the scope as Public. If you do not
set the scope to public, the record definition will not be available to use when registering a record. Additionally,
you must set the Allow Customization property of the record definition to True. If you do not set the Allow
Customization property to True, you cannot customize your record definition in any way. For more information,
see Making definitions available for customization (see page 515) .
To register a record definition
2. S elect Approvals > Approval Configuration .

In the right side pane, the approval configuration screen is displayed.
3. On the Approval Configuration screen, click New.On the Registration tab, provide the following information and
then click Save:
Field Details
Record Definition Name Select the record definition that needs to be registered with the approval server.
Request ID Select the record field that contains the Request ID of the approval request.
Requester Select the field from the record definition or record associations that stores login ID information of the requester.
Note: Make sure that the selected field stores the login ID of requester. Level Up approvals require this information
to determine the approvers of this request.
Summary Select the field from the record definition or from the association that stores the description of the request.
Notes Select the record definition or associated record field that contains extra information (notes) from a request.
Extra information is displayed on comments section of the approval console.
Tooltip Select the record definition or associated record field where tooltip is required on the approval console.
Permissions (Optional) Select the security labels of the record definition to assign permissions for accessing the approval
request.
The permission field controls who can access the created request. Only users with assigned security label can
access the approval request. If you do not specify the security label, all users can access the approval request.
Justification Reason (Optional) Select a field to store the reason an approver rejects a request.
Only configure this field if a justification reason is required; otherwise, leave the field blank.
Additional Fields for Configure additional fields that you want to be displayed on the approval console.
displaying Approval Request Configure these fields with customized labels. You can configure four additional fields at the maximum.
Information
Field Labels Specify labels for any additional fields that you configured.

Note
Whenever an association is created, a field gets created and field permissions are set to admin only.
If these associations are used while registering a record definition, and a non-admin user tries to access such
approval configuration, the approval engine displays "no access to association" message. Therefore, the
created association field requires the field level user permission to be accessible to the non admin user.
The following video (2:56) demonstrates how to register a record definition.
https://youtu.be/Pzh9jgPyN9U

Action Reference
If you want to define an approval that is approved by automatically by the system, create a self-approval flow. Configuring self approval flows (see page 544)
If you wan to define an approval that is approved by an individual or group, create an approval flow. Configuring approval flows (see page 546)
Related topics
Viewing and responding to approval requests (see page 550)
Configuring self approval flows

After you have registered the record, the next step is to configure either self approval flows or approval flows that define
how the request gets approved. You might also or both and use them in chained process.
To configure self approval flows

In the right pane, the approval configuration screen is displayed.
3. On the Approval Configuration screen, click New.
4. On the Create Approval Flow screen, click Self Approval > New Condition.
5. To configure conditions, on the Define Expression screen, perform the following steps and then click Save:

5.
1. a. From the list of Available Values, click Record Definition.
b. Select the record field or associated record field on which you would want to build an expression.
Alternately, you can use Associations for creating the expressions. To use associations, expand
Associations and select the record data.
While building an expression, make sure that you select a Record Definition that has a GUID value.
c. To use Foundation data in the expression, click .

Define Expression screen is displayed with foundation data.
d. Select the foundation data.
e. To find approvers either by functional roles or by the relationships defined between people, location, or
support groups.
Any data selected from Define Expression screen the returns the GUID of the entity.
2. To define precedence and populate audit information, on the Select Process screen, perform the following
actions and click Save:
a. To define the order of approval flows, from the Precedence option, set a precedence value. Precedence
defines the order of flows. Precedence is used to choose the order of expressions while evaluation. If two
expressions are same and have different precedence, then the one with the higher precedence gets
executed.
b. To write a message to the audit log, in the Audit Information field, enter the audit information.
When the Self Approval flow runs and the Approval Process is marked as Approved, this message is
written to the audit log. These are added by the user. For example, "approval for floater request".
c. To execute a self-approval process, in the Self Approval Process Definition section, select the check box
next to the preferred process definition.
This field lists all self approval processes attached to the record. If the process is selected, the process will
get executed before the approval request is processed. If the process is not selected, the approval
request is automatically approved.
The following video (3:18) demonstrates how to create self-approval flows.

https://youtu.be/dzxE5es3sNg

Action Reference
Create notifications when an approval request is approved, an approval request is rejected, an approval request Creating approval notifications to notify
is reassigned, an error exists in approval signature, and so on. approvers (see page 549)
Related topic
Configuring approval flows

After you have registered the record, the next step is to configure either self approval flows or approval flows that define
how the request gets approved. An approval process varies depending on how your organization configures and
implements it.
To configure approval flows

In the right pane, the approval configuration screen is displayed.
3. On the Approval Configuration screen, click New.
4. On the Create Approval Flow screen, click Approval Flows > Add New Flow Group.
5. Enter a name for the New Flow Group.

A flow group a contains single or multiple approval flows. You can create one or multiple approval flow groups.
Note
Once the Flow Group is created, go to approval process and in the Element Properties > Flow Group
Name field, enter this flow group name. Ensure that the approval process (see page 537) is in enabled
state.
6. From the Add New Flow list, select one of the following:
Level Up Approval Flow (Manager Approval): If you want to create level up approval flow, specify the
following fields:
No of Levels—Enter the number of levels the approval request must go through.

Qualification — Define an expression.
On the Define Expression screen, perform the following actions and then click Save:
a. From the list of Available Values, click Record Definition.
b. Select the record field or associated record field on which you would want to build an
expression.
Alternately, you can use Associations for creating the expressions. To use associations,
expand Associations and select the record data.
While building an expression, make sure that you select a Record Definition that has a
GUID value.
d. Define Expression screen is displayed with foundation data.
e. Select the foundation data.
f. To find approvers either by functional roles or by the relationships defined between

people, location, or support groups.
Outcome—From the drop down, select the approval status: Approved, Rejected, or Errored.
ProcessName — From the list, select the process that you want to execute for the approval status
that you selected in the Outcome field.
General Approval Flow: If you want to create a general approval flow or process chaining, specify the
following parameters and then click Save:
All/One — Select one of the following:

One must sign Use this option when only one of the approvers needs to approve the request.
All must sign Use this option when all approvers must approve the request.
Qualification — Define an expression to configure conditions.

On the Define Expression screen, perform the following actions and then click Save:
a. From the list of Available Values, click Record Definition.
b.
b. Select the record field or associated record field on which you would want to build an
expression.
Alternately, you can use Associations for creating the expressions. To use associations,
expand Associations and select the record data.
While building an expression, make sure that you select a Record Definition that has a
GUID value.
d. Define Expression screen is displayed with foundation data.
e. Select the foundation data.
f. To find approvers either by functional roles or by the relationships defined between

people, location, or support groups.
Outcome—From the drop down, select the approval status: Approved, Rejected, or Errored.
Process Name — From the list, select the process that you want to execute for the approval
status that you selected in the Outcome field.
Approvers — Select approver/s by using the foundation data . Select the department/organization/
business unit depending on one must sign or all must sign. You can set multiple approvers for one
request. You can either select approvers by filtering specific approvers from department
/organization/business unit or define a qualification or both. This enables you to narrow your
selection by limiting the approvers and not select the entire group or organization.
a. To select the approver, click .

The “Select Approvers” screen is displayed. Only users with enabled status appear in the approver
list.
b. From the Select Approvers for Approval Flow, select the Approvers, and then click Next.
c. On the Define Expression tab, define the expression by using person (or its association) attributes.
You can either select approvers by filtering specific approvers from department
/organization/business unit or define a qualification or both.
The following video (4:43) demonstrates how to create approval flows.
https://youtu.be/6b5TWcQmzbc

Action Reference
Create notifications when an approval request is approved, an approval request is rejected, an approval request Creating approval notifications to notify
is reassigned, an error exists in approval signature, and so on. approvers (see page 549)

Related topic
Creating approval notifications to notify approvers

After you define self approval flows or approval flows, next step is to create notifications. This is an optional step.
You can create notifications when an approval request is approved, an approval request is rejected, an approval request
is reassigned, an error exists in approval signature, and so on.
To create an approval notification
1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab .
2. Select Approvals > Notification Configuration.
3. In the Approval Notifications screen, click New.
4. In the New Approval Notification window, enter the following details:

Field Details
Notification Name Enter a name for the notification.
Record Definition Select the appropriate record definition.
Notify On Select one of the following approval cycle event that triggers the notification:
New Signature - A new signature line is added to the approval request.
Approve - The approval request is approved.
Reject - The approval request is rejected.
Reassign - An approval is reassigned to a different approver.
Error- An error exists in the approval signature.
Cancel- An approval request is cancelled.
More Info Return- A request for more information is fulfilled.
Hold- An approval request is put on hold.
More Info- More information is requested by an approver.
Notification Expression To specify additional conditions that control when a notification is sent, click Select to Build an Expression.
The Approval Service uses these conditions in addition to the option you have selected in the Notify On field.
You can use the Foundation data to create the Notification Expression.
Notification Method Defaults to Email.

Email—Users are notified by email.
You can use this option to send notifications to users who are not using the BMC Remedy AR System server, to an
alias for
a group, or to an email address representing a program.

Field Details
Use Email based Approval Select the check box to use an email template for the notification.
template This check box is displayed only if you select the Email notification method and New Signature as value for the
Notify On
field.
Send To To specify the users to whom the notification is sent, select one of the following options:
All Approvars/Alternates - The approval service sends notifications to the default recipients for the
selected approval cycle
event.
When a request is approved or rejected, the notification is sent based on the Completion Criteria setting in
the
selected Wait for Approval Definition.
All Must Approve - The notification is sent to the defined approver and all the other approvers for
whom
signature lines have been created.
One Can Approve - The notification is sent only to that approver and not the other approvers in the
signature line.
Other - Specify an individual, a group, or a list of individuals or groups to whom the notification must be
sent.
Alternatively, click Select to Build an Expression to use record instance variables (for example,
$fieldName$) to
specify the recipients.
Subject Type a subject line for the notification message.

Alternatively, click Select to Build an Expression to include record instance variables in the subject line of the
notification
message.
Message Type the message text for the notification.

Alternatively, click Select to Build an Expression to include record instance variables in the message text.
5. To activate this notification configuration, select the Enabled box.
6. To save your changes and close the New Approval Notification window, click Save.
Related topic
Viewing and responding to approval requests

In BMC Helix Innovation Studio, Approval Console is available with the Approval Library (BMC Helix Innovation Studio >
Applications > Approval > Visit Deployed Application). The Approval Console displays all the approval requests of your
applications. You can update an approval request by using the Approval Console.
You can use the Approval Console to perform the following activities:
Searching for or filtering approval requests
Viewing approval request details
Approving or rejecting requests
Putting requests on hold

Reassigning a request to another approver
Creating or responding to More Information requests
Viewing approved, rejected, and cancelled requests
From the Approval Console, you can act on single or multiple requests at one time without opening each request
individually.
To use the Approval Console in your application

You can use the Approval Console in your application to create views for an approval process. You can use the Approval
Console in your application by creating a view definition that contains the Approval Console view component found in
the View designer.
To view or update an approval request

The following table provides information about working with approval requests by using the Approval Console:
Goal Actions
View details about an approval request In the Approval Console, click the appropriate tab (for example, Pending), and select a request
to view its details in the Request Details pane on the right side.
Update pending requests To process an approval request
1. In the Approval Console, click the Pending tab.
2. From the list of approval requests, select one or more requests.
3. Based on your requirements, click Approve, Reject, On Hold, or Reassign.
4. (Only if you click Reassign) In the Reassign Request dialog box, from the Reassign
Request To list, select another approver and click Save.
Based on your action, the requests are moved to the Approved, Rejected, or On Hold
tab. You can no longer see reassigned requests in the Approval Console.
To add a comment to an approval request

1.
Goal Actions
1. In the Approval Console, click the Pending tab.
2. From the list of approval requests, select the request about which you want more
information.
3. From the Activity Log section at the bottom, click Comments.
4. In the New Comment dialog box, enter the comment.

If required, you can also add an attachment.
5. Click Submit.
Create a More Information request to get additional details

before approving or rejecting an approval request 1. In the Approval Console, click the Pending tab.
2. From the list of approval requests, select the request about which you want more
information.
3. From the Activity Log section at the bottom, click Questions.
4. In the New Question dialog box, enter the user name and your question.
5. Click Submit.
The request is moved to the More Information tab.
Respond to a More Information request

1. In the Approval Console, click the More Information tab.
2. From the list of More Information requests, select the request to which you want to
respond.
3. In the Question and Response dialog box, enter your response.

4. Click Save.
View approved, rejected, or cancelled requests In the Approval Console, click More Views and then select Approved, Rejected, or Cancelled to
view the list of corresponding requests.
Related topics
Adding an approval process to an application (see page 536)
Adding cognitive capabilities to a custom application

BMC Helix Innovation Suite provides a cognitive service that enables you to use the advantages of Artificial Intelligence
(AI) and Machine Learning (ML) in your Digital Service applications. BMC Helix Innovation Suite Cognitive Service uses
the IBM Watson machine learning capability and IBM Watson Assistant Conversation Service . You can use the
capabilities provided by the cognitive service to automate your application workflow tasks, such as assignment and
categorization.
To understand the cognitive service use case, see Leveraging cognitive capabilities in your application (see page 281).

Workflow
The following graphic illustrates the end-to-end process for developing an application that uses the BMC Helix Innovation
Suite Cognitive Service. It describes the roles involved, steps required, and the tools used in the application development.
Development of an application that uses BMC Helix Innovation Suite Cognitive Service comprises of the following tasks:
Note
To use the cognitive service in your existing applications, you do not need to perform the task 1.
Task Role Action Reference
1 Developer Creates an application by using the Maven archetype.

Creating a Project using Maven and the Archetype (see
page 806)
2 Developer Creates the definitions for the application, builds, and deploys
Creating the definitions for a tailorable Digital Service
the application.
Deploying your Digital Service application for the first

time to start working in BMC Helix Innovation Studio (see
page 813)
3 Developer Creates a configuration for your application so an administrator

Enabling a custom application for cognitive service (see
can use the configuration to train the cognitive service.
page 554)
4 Developer (Optional) Creates a data set to train and test the cognitive
Types of data sets used to train and test the cognitive
service.
service (see page 559)

Task Role Action Reference
You can create a training data sets that either uses sample data
or uses data from your application to train the cognitive service.
5 Developer (Optional) Creates a Java program to use auto-assignment.

Creating a Java program to use auto assignment (see
page 570)
6 Developer Creates processes or rules that uses the cognitive service

Automating categorization and assignment of application
elements.
requests (see page 478)
7 Developer Exports the definitions and deploy the application.

Deploying the custom code-based applications to
development environments (see page 915)
8 Administrator Configures the BMC Helix Innovation Suite Cognitive Service.

Configuring cognitive service for a custom application
(see page 556)
9 Administrator Creates or updates the cognitive service training and test data
Types of data sets used to train and test the cognitive
sets.
service (see page 559)
10 Administrator Trains and tests the cognitive service.

Training and testing the cognitive service for a custom
11 Administrator Evaluates whether the cognitive service is predicting correct

categories, and updates the data set if required.
12 End user Uses the application that leverages the cognitive service.
The following video (3:57) provides the process overview to use the BMC Helix Innovation Suite Cognitive Service in your
application:
https://youtu.be/k72xCJlvqK8
Enabling a custom application for cognitive service

To create training data sets and train the BMC Helix Innovation Suite Cognitive Service, you must create a configuration
(of the type in-bundle setting) in your application.
To create a configuration
2. Select the application in which you want to create a setting.
4. Click New > In-bundle Settings.
5. In the New In-bundle Settings window, specify the required properties, and click Save.
Property Description Example values
Component name Indicates the name for the configuration that is the name of the in-bundle setting Cognitive training

Is View Component Opens a view definition in the application Not selected

You not need to select this property.
Registered Module Specifies the unique name of the registered module cognitive-training
Name Select the cognitive-training option from the drop down list.
Status Provides the status of the configuration Selected

You must select this property.
Available in Makes the configuration available in BMC Helix Innovation Studio Administration tab. Selected
Navigation Sidebar You must select this property.
Component Label Specifies the unique label for the configuration Cognitive Training
The label you provide appears as a setting in the Administration tab.
Show In Specifies whether you want to show the configuration in the application, or in BMC Helix In BMC Helix
Innovation Studio, or both Innovation Studio
You must select In BMC Helix Innovation Studio option or Both option (that is in BMC Helix
Innovation Studio and in application)
Permissions Defines the permissions associated with the setting Administrator group
You can add permissions for a group or a role.
First Menu Defines the first menu that gets displayed in BMC Helix Innovation Studio Administration tab. My application
Second Menu Defines the second menu that gets displayed in BMC Helix Innovation Studio Administration tab.
After you create the application configuration, it is displayed in the Settings section in the Administration tab. The
following image displays an example configuration created by using the example values:


Configuring cognitive service for a custom application

BMC Helix Innovation Suite Cognitive Service uses the IBM Watson machine learning capability. You require two
instances of IBM Watson Assistant — one for auto-categorizing and auto-assigning service requests, and one for the
chatbot application. To configure IBM Watson Assistant, you must obtain the IBM Watson license and then configure
BMC Helix Innovation Suite to communicate with IBM Watson.
SaaS administrators must configure the BMC Helix Innovation Suite Cognitive Service for a tenant to use it in an
application.
Best practice
To avoid errors, BMC recommends that only SaaS administrators configure the BMC Helix Innovation Suite
Cognitive Service, IBM Watson Assistant, and Chat session idle time.
To ensure that you can create unlimited cognitive service training data sets (see page 562), all existing and new
customers must provide the Cognitive Service Administration credentials in BMC Helix Innovation Studio.
After you subscribe to the BMC Helix Innovation Suite Service, BMC sends you an invite to join IBM Cloud as part of your
onboarding process. You must set your user name and password for IBM Cloud by using this invite, and enter the
credentials when you configure the Cognitive Service Administration credentials. The credentials are used when
provisioning Watson conversation workspaces in which you create the training data sets.
The following table provides information about the Watson licenses and configurations that you require to use the
cognitive service and the chatbot framework:
Service Requirement Additional configuration
Cognitive service in your IBM Watson Assistant license Cognitive service (see page 557) and Cognitive administration
application credentials (see page 557)
For more information, see IBM Watson Conversation in the
IBM Watson documentation.
Chatbot framework in IBM Watson Assistant license Watson Conversation (see page 558) and Chat Session Idle
your application Time (see page 558)
For more information, see IBM Watson Conversation in the
IBM Watson documentation.
Note
IBM Cloud is transitioning from using Cloud Foundry to using token-based Identity and Access Management
(IAM) authentication.
As an administrator, when you create new services, you will get an IAM API key to configure the cognitive
service in BMC Helix Innovation Studio. Existing services will continue to use user name and password as
service credentials for configuring the cognitive service i n BMC Helix Innovation Studio.
For more information, see IBM Cloud Release Notes documentation.

To configure the cognitive service

You must configure the instance of IBM Watson Assistant that you are using for auto-categorization and auto-
assignment capabilities. You get the IAM API key or username and password when you get your IBM Watson Assistant
license.
2. Select Configure My Server > Cognitive Service.
3. From the Configure list, select Cognitive Service Connections.
4. Expand the IBM Watson™ Assistant for Natural Language Classification section.
5. If you have received the IAM API key, click the API Key tab and enter the IAM API key, else enter the user name
and password in the Username & Password tab.
The following image shows the API Key and Username & Password tabs in the IBM Watson Assistant for natural
language classification section:
6. To test the connection, click Test.

If the connection fails, verify your username and password.
7. Save the connection.
To configure the cognitive service administration credentials

You must provide the IBM Cloud administrator credentials when you want to create unlimited cognitive training data
sets for auto-categorization and auto-assignment permitted by IBM Watson.
3. From the Configure list, select Cognitive Administration Credentials.
4. In the Cognitive Administration Credentials section, enter the username and password. You get the user name
and password when you join IBM Cloud.
5. Save the credentials.

To configure IBM Watson Assistant

You must configure the instance of IBM Watson Assistant that you are using for the chatbot application. You get the
Identity and Access Management (IAM) API key or username and password when you get your IBM Watson Assistant
license.
4. On the Cognitive Service page, go to the IBM Watson™ Assistant section.
The following image shows the API Key and Username & Password tabs in the IBM Watson Assistant section:

To configure a chat session idle time

You need to configure the idle timeout period after within which the chat session closes automatically. The default
timeout period is five minutes.
3. From the Configure list, select Chatbot.
4. In the Chatbot section, enter the value in the following field, and click Save.
Field Description
Chat Session Idle Time

4.
Field Description
Enter the time in seconds after which the chat session closes automatically.
Note: The server uses an idle default time period of five minutes (300 seconds) for a chat session timeout.
For example, you set the Chat Session Idle Time as 400 seconds, the chat session time out will occur between
400 to 700 seconds (that is 400 + 300).

Action Reference
Train the BMC Helix Innovation Suite Cognitive Service to learn to work with your data so that you can use Training and testing the cognitive service for a
auto-categorization and auto-assignment capabilities in your application. custom application (see page 562)
Configure a chatbot for your application so that your application can work with different chatbot provider Configuring a chatbot for your application (see
services such as Slack, Skype for Business, or Twilio. page 589)
Types of data sets used to train and test the cognitive service
BMC Helix Innovation Suite Cognitive Service provides auto-categorization, auto-assignment, and chatbot capabilities. To
utilize these capabilities in an application, you must train the IBM Watson Assistant Service to work with your data. A
developer might create a sample training data set for your application. An administrator updates the sample data set or
creates new training data sets. The administrator then uses the training data sets in existing or new processes or rules for
the application.
In addition to training the cognitive service, you can test whether the cognitive service is trained correctly so that it
predicts the desired categories. You can evaluate the cognitive service against the following test metrics:
Accuracy
Precision
Recall
F-score
For more information about the test metrics and how to use them to improve the training data set, see Leveraging
machine learning metrics to improve cognitive service data sets (see page 283). For more information about testing the
chatbot application, see Testing the chatbot training data to improve predictability (see page 602).
Training data set and test data set

After creating a CSV file, administrators can specify the percentage to split the rows into training data and test data. For
new data sets, by default, random 80% of the rows are used as training data and the remaining 20% are used as test data.
For existing data sets, by default, 100% of the rows are used as training data.
The following table explains the difference between training data sets and test data sets:
Training data set Test data set
Used to train the cognitive service so that the input

Used to test whether the cognitive service correctly categorizes the input text based on the
text is correctly categorized.
training data.
Can be a CSV file or runtime application data.

Is always a CSV file.

Training data set Test data set
The test results are generated in a CSV file or can be v iewed from BMC Helix Innovation
Studio.
For more information about testing the cognitive service, see Leveraging machine learning metrics to improve cognitive
service data sets (see page 283).
CSV data set and application data set

You can create a CSV file of data set or specify application data for training and testing BMC Helix Innovation Suite
Cognitive Service:
Type of data set Description Reference
CSV data set A CSV file is used to train and test the cognitive service. The CSV file contains an input
CSV data sets
text to be categorized and the category for the input text.
structure (see
The CSV file must have at least 5 and not more than 25,000 categories associated with page 560)
2,000 input texts.
Limit of CSV
training data sets
For applications that do not require continuous cognitive service training, you can
train and test the cognitive service by using data from CSV files. (see page 561)
Guidelines to
create a training
data CSV file
(see page 561)
BMC Helix Innovation Suite data set The application record definitions and record fields are used to train and test the Not applicable
cognitive service.
For applications that are used in a continuously changing business environment that
requires frequent training of the cognitive service, you can use application data to
train the cognitive service. This approach helps the cognitive service get updated data
and provide suggestions according to the business changes.
CSV data set structure

A CSV file that is used for training and testing the cognitive service should have the following structure:
A row represents a record.
The first column represents the input text to categorize.
The second column represents the category that applies to the input text to categorize:
If you have hierarchical categories, you must provide the leaf node as the category.
If you have multiple categories, you must separate them by using the pipe character.
For example, Hardware | Component | Memory
The length of the data must not exceed 512 characters. The data can contain all special characters.
If you are using a backslash (\) within the entered data, you must use four backslashes (\\\\) instead of one
backslash (\).
Example: <Text1>\\\\<Text2>\\\\<Text3>. Enter hardware\\\\software instead of
hardware\software.
Each row must contain an input text value to categorize and a category that applies to the input text.

Each record is terminated by an end-of-line character.
Examples of data sets

The following images provide an example of CSV data sets after they are split into training data and test data:
Example of CSV training data
Example of CSV test data
Limit of CSV data sets

The CSV data file must have at least 5 rows and not more than 25,000 input texts (intent examples) associated with 2000
categories (intents) . The maximum training data sets that you can create is based on your Watson Assistant Service
license as given below:
Watson Assistant Standard Service—40,000 CSV training data sets in shared mode.
Watson Assistant Premium Service—600 CSV training data sets in dedicated mode.
For more information about Watson Assistant Service licensing, see IBM Watson Conversation Service documentation
.
Guidelines to create a training data CSV file

When you create a training data CSV file, follow these guidelines:
Eliminate empty rows with blank text or blank categories.

Remove rows with exact duplicate examples.
Create balanced data sets with roughly similar number of examples for all the categories (roughly 20-30 examples
for each category). If you have lesser input texts, the test metrices for such categories is on the lower side.
Limit the length of input text to fewer than 60 words (1,024 characters).
The text that exceeds 1024 characters is truncated.
Limit the number of categories to several hundred classes.
Include multiple classes only if the text is vague and identifying a single class is not clear.
Limit the number of records to 25,000 associated with 2,000 classes.

The minimum number of records allowed is 5 and the maximum number of records allowed per workspace is
25,000.
For more information about the training data guidelines, see Using your own data in IBM documentation.

Training and testing the cognitive service for a custom application

To use BMC Helix Innovation Suite Cognitive Service for auto-categorization and auto-assignment, administrators must
train the cognitive service. You can update the sample data set or create new data sets and must use the data sets in
existing or new processes or rules for the application.
You can create data sets in the following ways:
By using a CSV file
By using application data
You must specify the percentage of data that can be used for training the cognitive service. By default, 80% of the data
set is used for training and 20% is used as test data.
Process for training and testing BMC Helix Innovation Suite Cognitive Service
The following image explains the tasks that an administrator must perform to train and test the cognitive service by using
a CSV data set or application data:

The following tables describes the steps to train and test the cognitive service:
Create data sets
Type of Task Description Reference

data set
CSV Create a CSV Create the CSV data set according to the defined structure and
Types of cognitive data sets (see page
data set guidelines.
559)
Upload the CSV Upload the CSV data and specify the percentage of rows that you want
To upload the CSV data file (see page
file to use as training data and test data. The system randomly splits the CSV
564)
file into training data set and test data set.
Application (Optional) To start the cognitive service training, initially you might not have
To create a sample CSV data set file, see
data Upload seed application data. In this case, the seed data acts a startup data for
Types of data sets used to train and test
data machine learning. The cognitive service learns by using the seed data
the cognitive service (see page 559)
initially and then picks up the application data.
To see the procedure to upload the
Note: The seed data is provided in a CSV file. sample CSV data set, see To upload
seed data (see page 565)
Specify the You must select the fields in the record definitions from which data is
To specify application data that you
application data used for training and test the cognitive service. To ensure that the
want to use for training (see page 566)
that you want to training data does not go beyond the limit specified by IBM Watson, you
use for training can define a condition to further filter the data.
Example: You select the Service request record definition, and the
Summary and Category fields in that record definition. You also define a
condition such as Status = Open and Priority = High so that only the data
which matches these conditions is used for training.

Create data sets
Train the BMC Helix Innovation Suite Cognitive Service
CSV Train the Select the CSV training data set that you uploaded earlier to train the
To train the cognitive service (see page
cognitive cognitive service.
567)
service
Application Select the application data that you specified earlier to train the
data cognitive service.
Evaluate the cognitive service training
CSV and Evaluate After you train the cognitive service, you can evaluate the cognitive
To evaluate the cognitive service training
Application whether the service training for auto-categorization or auto-assignment. For auto-
(see page )
data cognitive assignment, the cognitive service returns the login IDs of the assignee.
service is When you create assignment training data sets, you must ensure that
trained the assignee belongs to the Agents group in the Foundation library.
correctly.
Before you begin

Before you train or test the BMC Helix Innovation Suite Cognitive Service by using the CSV file or by using application
data, ensure that you have completed the following tasks:
To communicate with IBM Watson, administrators must add the Watson credentials in BMC Helix Innovation
Suite.
For more information, see Configuring cognitive service for a custom application (see page 556)
To be able to train or test IBM Watson, administrators must create an application configuration UI.
For more information, see and Enabling a custom application for cognitive service (see page 554).
If you want to use application data for training data sets, identify the record definition and fields that you want to
use for training and testing.
To upload a CSV file

After creating the CSV data set, perform the following steps to upload the CSV file:
2. Click the configuration that you created for training the cognitive service.
For example, select My application > Cognitive Training.
3. On the Auto-classification Training and Evaluation tab, in the Data Sets section, click New, and select CSV Data Set
.
The following image is an example of uploading CSV data sets:

4. Fill out the Data Set Name and Description fields.
5. In Training Type, t he IBM Watson Conversation for natural language classification option is populated
automatically. You cannot change this option.
6. In CSV File, select the CSV training data set file that you created earlier.
7. From the Locale list, select the locale of the training data set.
8. In Training Data, select the percentage of the CSV data that you want to use as training data.
9. In Testing Data, the percentage of CSV data that you want to use as test data is automatically calculated
according to the Training Data percentage.
10. Click Save.
To use application data in a training data set

Perform the following tasks when you want to use application data to train and test the BMC Helix Innovation Suite
Cognitive Service:
To upload seed data (see page 565)
To specify application data that you want to use for training and testing (see page 566)
To upload seed data
3. Click Configure Training Data Sets.
4. On the Training Data Sets section, click New, and select Innovation Suite Data Set.
5. Fill out the Data Set Name and Description fields.
6. In Training Type, t he IBM Watson Conversation for natural language classification option is populated
automatically. You cannot change this option.

7. In CSV File, select the CSV data set file that you created earlier.
8. From the Locale list, select the locale of the training data set.
9. In Record Definition Name , s elect the record definition that you want to use to provide data to the cognitive
service.
10. In Text Fields, click Add/Remove Text Fields and select one or more text fields that contain the text values for the
cognitive service to classify. If you select more than one text fields, the values are concatenated.
11. In Category Fields, click Add/Remove Category Fields and select one or more category fields to classify the values
in the text fields. If you select more than one text fields, the values are concatenated.
12. Click Save.
To specify application data that you want to use for training and testing
3. Click Configure Training Data Sets.
4. On the Training Data Sets section, select one of the following options:
If you have not uploaded seed data, click New, and select Innovation Suite Data Set.
If you have uploaded seed data, click the name of the data set in which you uploaded the seed data.
5. Modify the data set in which you have uploaded the seed data.
If you have uploaded the seed data
a. On the Edit Innovation Suite Data Set page, in Record Definition Name , s elect the record definition that
you want to use to provide data to the cognitive service.
b. In Text Fields, click Add/Remove Text Fields and select one or more text fields that contain the text values
for the cognitive service to classify.
c. In Category Fields, click Add/Remove Category Fields and select one or more category fields to classify
the values in the text fields.
d. (Optional) In the Data Split section, in Training Data, speciffy the percentage of data that you want to use
as training data.
For new data sets, by default, 80% of the CSV seed data is used as Training Data and remaining 20% is
used as Test Data. For existing data sets, 100% of the rows are used as training data.
The percentage of CSV data that you want to use as Test Data is automatically calculated according to
the Training Data percentage.
Specify the application data that you want to use for training.
If you have not uploaded the seed data
a.
a. On the New Innovation Suite Data Set page, fill out the Data Set Name and Description fields.
b. From the Locale list, select the locale of the training data set.
c. In Record Definition Name , s elect the record definition that you want to use to provide data to the
cognitive service.
d. In Text Fields, click Add/Remove Text Fields and select one or more text fields that contain the text values
for the cognitive service to classify. If you select more than one text fields, the values are concatenated.
e. In Category Fields, click Add/Remove Category Fields and select one or more category fields to classify
the values in the text fields. If you select more than one text fields, the values are concatenated.
f. In Data Split, in Training Data, change the percentage of data that you want to use as training data.
The percentage of Test Data is automatically calculated.
The new training data set is displayed in the Auto-classification Training and Evaluation section. An administrator
can delete the training data set or create a copy of the existing training data set.
6. Click Save.
To train and test the cognitive service

After you have uploaded the CSV data set or selected the application data, you can train and test the cognitive service.
3. In the Auto-classification Training and Evaluation section, select the training data set that you want to use for
training, and click Train and Test.
The data set is randomly split into training data set and test data set based on the percentage that you specified
earlier.
The status of the training data is changed to Training and when the training is completed successfully, the status
of the training data set is changed to Trained.

Related topic
Testing the chatbot training data to improve predictability (see page 602)
Evaluating the cognitive service test results

As an administrator, you can test and evaluate the BMC Helix Innovation Suite Cognitive Service to ensure that the
cognitive service correctly auto-categorizes service requests raised by the end users. The test results provide the exact
problem area when the data sets do not predict the appropriate categories, so that administrators can rectify the data
sets.

For more information about the test metrics, see Leveraging machine learning metrics to improve cognitive service data
sets (see page 283).
Before you begin

After uploading the CSV data set or selecting the application data that you want to test, ensure that you have trained and
tested (see page 562) the data set.
To view the test metrics
3. On the Auto-classification Training and Evaluation tab, select Test Results.

The test metrics—accuracy, precision, recall, and F-score are displayed.
The following image shows the test metrics for each test data and the CSV file of test results:
4. In the Results column, select the CSV file corresponding to the data set for which you want to view the test
results.
The following image is an example of the CSV test results file:
Tip
To delete the test results that are no longer required, you can create a process (see page 457) by using the
Delete record element.

To evaluate the cognitive service from the BMC Helix Innovation Studio UI
3. On the Auto-classification Training and Evaluation tab, select Test Results > Interactive Evaluation.
4. On the Auto-classification Interactive Evaluation page, from the Trained Data Set list, select the data set that you
want to evaluate.
5. In Text, enter the input text from the data set that you want to categorize.
6. Click Classify.
The input text is categorized and the results are displayed on the screen.
To download and rectify the data sets

The CSV data set that you uploaded is split into training data and test data. The test data shows the input texts that were
not categorized as desired.
1. To download the test results, perform the following steps:
a. Log in to BMC Helix Innovation Studio and navigate to the Administrator tab.
b. Click the configuration that you created for training the cognitive service.
c. On the Auto-classification Training and Evaluation tab, select Test Results.
d. In the Test Data column, select and download the test data CSV file corresponding to the data set that
you want to rectify.
e. In the CSV test data file, in the Match column, view the rows that have the value N.
2. To rectify the data set, add more input texts for the corresponding categories or remove email addresses, email
signatures, saultations, or any other information that is not relevant for categorization.
Related topics

Testing the chatbot training data to improve predictability (see page 602)
Creating a Java program to use auto-assignment

Developers can implement the auto-assignment capability in applications that use the BMC Helix Innovation Studio
Cognitive Service.
To implement auto-assignment capability that uses the BMC Helix Innovation Studio Cognitive Service in your
application, you must create a Java program that acts as an interface to work with the Suggest Assignee element in your
application process. The Java program implements an assignment calculator class and methods to provide information
to the assignment process. You can implement methods that provide the information, such as the assignee availability,
workload, effort, and last assign time. The assignment process requires this information to assign the appropriate
assignee for a task .
The assignment process returns an assignee login ID that belongs to the Agent in the Foundation library. BMC Helix
Innovation Studio provides a default assignment calculator implementation (AgentAssignmentCalculator) to check the
availability of agents. You can extend the AgentAssignmentCalculator code to add custom logic. For example, you can
extend the code to include logic to check an agent's PTO requests.
For information about Foundation library, see Foundation data library and data model (see page 641).
Auto-assignment steps
The following image describes the runtime assignment steps when the Suggest Assignee element in a process is
triggered:
Note
You must implement methods to sort the agents by the assignment type, such as Round Robin, Load Balanced
By Number, Load Balanced By Capacity, and By Skill Level.
To create a Java program to use auto-assignment
1. In your application bundle project pom.xml file, add the dependencies of the Assignment library and the
Foundation library.
For example:
<dependency>
<groupId>${rx-sdk.groupId}</groupId>
<artifactId>com.bmc.arsys.rx.assignment</artifactId>
<version>${rx-sdk.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>${rx-sdk.groupId}</groupId>

<artifactId>com.bmc.arsys.rx.foundation</artifactId>
<version>${rx-sdk.version}</version>
</dependency>
2. Create a Java class that extends the AgentAssignmentCalculator class.

For example:
package com.example.bundle;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Calendar;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Random;
import java.util.concurrent.ThreadLocalRandom;
import com.bmc.arsys.rx.assignment.business.domain.AgentAssignmentCalculator;
import com.bmc.arsys.rx.foundation.domain.Agent;
/**
* This class implements the Agent Assignment Interface provided by
* Cognitive Services.
* Developer is supposed to provide following methods to help the assignment
* engine to pick the right assignee.
*
*/
public class AssignementCalc extends AgentAssignmentCalculator {
public List<Agent> applicationAgents = new ArrayList<Agent>();
3. Register the assignment calculator by passing the following parameters:
Record definition name (fully qualified) which is the same record definition that you provide in the
Suggest Assignee action of your process or rule.
The calculator object just created in step 2.
For example:
/**
* Used for registering with Assignment Calculator for Cognitive Services.
*/
import com.bmc.arsys.rx.application.common.ServiceLocator;
import com.bmc.arsys.rx.assignment.business.AssignmentService;
import com.bmc.arsys.rx.services.bundle.BundleService;
/**
* Rx Web Activator class.
*/
public class MyApplication extends RxBundle {
/* (non-Javadoc)
* @see com.bmc.arsys.rx.business.common.RxBundle#register()
*/

@Override
//
// TODO: Register static web resources and framework extensions.
//
// registerService(new MyService());
//
registerStaticWebResource(String.format("/%s", getId()), "/webapp");
/**
* Registering with Assignment Calculator for Cognitive Services.
*/
BundleService bundleService = ServiceLocator.getBundleService();
AssignmentService assignmentService = (AssignmentService) bundleService.getService(
AssignmentService.class.getName());
AssignementCalc AssignementCal = new AssignementCalc();
assignmentService.registerAgentAssignmentCalculator("com.example.testassginment:test",
AssignementCal);
}
}
4. Extend the AgentAssignmentCalculator class to add the methods that provide information to the assignment
process.
Sample code
The following code snippet illustrates a sample implementation of the assignment calculator. In the sample code, the
loginIds arrayList is a list of login IDs that belong to Agents in the Foundation library.
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Calendar;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.Random;
import java.util.concurrent.ThreadLocalRandom;
import com.bmc.arsys.rx.assignment.business.domain.AgentAssignmentCalculator;
import com.bmc.arsys.rx.foundation.domain.Agent;
/**
* This class implements the Agent Assignment Interface provided by
* Cognitive Services.
* Developer is supposed to provide following methods to help the assignment
* engine to pick the right assignee.
*
*/
public class AssignementCalc extends AgentAssignmentCalculator {
public List<Agent> applicationAgents = new ArrayList<Agent>();
/** List of agents login Ids that should exist in Agent foundation record definition */
public List<String> loginIds = Arrays.asList("Jason Wen", "Ashish Ghumnar", "calvin", "hobbes");
/** The priorities. Smaller number represents higher priority. */

public List<Integer> priorities = Arrays.asList(0, 1, 2, 3);
/**

* Creating an agent list (used for demo purposes). Those agents should exist in Agent
* foundation record definition.
*/
public AssignementCalc() {
for (String loginId : loginIds) {
Agent agent = new Agent();
agent.setLoginId(loginId);
applicationAgents.add(agent);
}
}
/**
* This method overrides the method from the Cognitive Assignment interface. It is supposed to
* send back a list of Agents, sorted by their skill level.
*
* This implementation is for the assignment type "by skill level".
*
* @param agents
* List of agents provided by the assignment engine. It merely contains their login
* ID.
*
* @return List of Agents, sorted by their skill level as List<Agent>
*/
@Override
public List<Agent> rankAgentsBySkillLevel(List<Agent> agents) {
// As an example we just shuffle the list.
Collections.shuffle(agents);
return agents;
}
/**
* send back a list of Agents loginIds and their typical effort (in hours) by Priority. This
* will be used to assess which developer should be assigned to a task but weighting with the
* task priority.
*
* @param agents
* ID.
*
* @return List of Agents loginIds, with a List of their typical efforts per priority as
* Map<String, Map<Priority, Float>>
*/
@Override
public Map<String, Map<Integer, Float>> getEffortsByPriorityAndByAgents(List<Agent> agents) {
// As an example we just build a list with random values.
Map<String, Map<Integer, Float>> effortsByPriorityAndByAgents = new HashMap<String, Map<Integer,
Float>>();
for (Agent agent : agents) {

Map<Integer, Float> effortPriority = new HashMap<Integer, Float>();
for (Integer currentPriority : priorities) {

effortPriority.put(currentPriority, (float) getRandomValue(0, 50));
}
effortsByPriorityAndByAgents.put(agent.getLoginId(), effortPriority);
}
return effortsByPriorityAndByAgents;
}
/**
* send back a list of Agents loginIds with their last assignment date.
*
* This implementation is for the assignment type "round robin".

*
* @param agents
* ID.
*
* @return List of Agents loginIds with their last assignment date as Map<String, Date>.
*/
@Override
public Map<String, Date> getAgentsLastAssignTime(List<Agent> agents) {
// As an example we just build a list with random date values.
Map<String, Date> agentsLastAssignTime = new HashMap<String, Date>();

agentsLastAssignTime.put(agent.getLoginId(), getRandomDate());
}
return agentsLastAssignTime;
}
/**
* send back a list of Agents loginIds with their current number of assigned tasks.
*
* This implementation is for the assignment type "by number".
*
* @param agents
* ID.
*
* @return List of Agents loginIds with their with their current number of assigned tasks as
* Map<String, Integer>.
*/
@Override
public Map<String, Integer> getAgentNumberOfAssignedTasks(List<Agent> agents) {
Map<String, Integer> agentNumberOfAssignedTasks = new HashMap<String, Integer>();

agentNumberOfAssignedTasks.put(agent.getLoginId(), getRandomValue(0, 10));
}
return agentNumberOfAssignedTasks;
}
/**
* This method overrides the method from the Cognitive Assignment interface. It
* sends back a list of Agents loginIds with their actual capacity.
*
* This implementation is for the assignment type "by capacity".
*
* @param agents
* ID.
*
* @return List of Agents loginIds with their with their actual capacity as Map<String, Float>.
*/
@Override
public Map<String, Float> getAgentCapacity(List<Agent> agents) {
Map<String, Float> agentCapacity = new HashMap<String, Float>();

agentCapacity.put(agent.getLoginId(), (float) getRandomValue(0, 100));
}
return agentCapacity;
}

/**
* send back a list of Agents loginIds with the amount of their available time between the
* current Date and a date provided by the assignment engine. This amount, in hours, could be
* determined by their usual schedule, PTO and current assignments.
*
* @param agents
* ID.
*
* @return List of Agents loginIds with their with their amount of available time (hours) as
* Map<String, Float>.
*/
@Override
public Map<String, Float> getAvailableWorkHours(List<Agent> agents, Date date) {
Calendar cal = Calendar.getInstance();

cal.add(Calendar.DATE, -8);
int hoursDifference = getDateDifference(date, cal.getTime());
Map<String, Float> availableWorkHours = new HashMap<String, Float>();
for (Agent agent : applicationAgents) {

availableWorkHours.put(agent.getLoginId(), (float) getRandomValue(0, hoursDifference));
}
return availableWorkHours;
}
/**
* Generate a random Date.
* https://stackoverflow.com/questions/11016336/how-to-generate-a-random-timestamp-in-java
*
* @return a random Date in Date format.
*/
private Date getRandomDate() {
Random r = new Random();
long unixtime = (long) (1293861599 + r.nextDouble() * 60 * 60 * 24 * 365);
return new Date(unixtime);

}
/**
* generate a random number in the provided range
* https://stackoverflow.com/questions/363681/how-do-i-generate-random-integers-within-a-
* specific-range-in-java
*
* @param min
* Minimum value for the random number.
* @param max
* Maximum value for the random number.
*
* @return random number as an int.
*/
private int getRandomValue(int min, int max) {
return ThreadLocalRandom.current().nextInt(min, max + 1);
}
/**
* Get difference between two dates, in hours.
* https://stackoverflow.com/questions/2003521/find-total-hours-between-two-dates
*
* @param date1
* Begin date

* @param date2
* End date
* @return difference between both dates in hours.
*/
private static int getDateDifference(Date date1, Date date2) {
final int MILLI_TO_HOUR = 1000 * 60 * 60;

return (int) (date1.getTime() - date2.getTime()) / MILLI_TO_HOUR;
}
}

Automating categorization and assignment of application requests (see page 478)
Adding a chatbot and conversational capabilities to your application

BMC Helix Innovation Studio provides a chatbot framework that enables you to add a chatbot and include conversational
capabilities in your application. The chatbot framework uses the IBM Watson Assistant capability and a user
communication client such as Slack, Microsoft Office 365 Skype for Business, and SMS, which uses Twilio.
When an end user uses a chatbot application, the user need not learn how to use a specific application; because all the
interaction is done through conversations. The chatbot framework helps your application to interact with users through
natural language; to understand the conversation context; and to perform tasks on behalf of the user. By eliminating
human intervention for certain tasks and by providing easy-to-find information, the framework helps reduce your
company's costs and resources.
To understand the chatbot framework use case, see Leveraging conversation capabilities in your application (see page
282).
To understand the chatbot framework architecture, see Chatbot framework architecture (see page 578).
Workflow
The following image illustrates the end-to-end process for using the chatbot framework in your application. It describes
the personas involved, steps required, and the tools for using the chatbot framework.

Adding a chatbot to your application involves the following tasks:
1 Create a conversation workspace by using the IBM Watson Assistant tool. Creating a conversation workspace (see page
579)
2 (Optional) Integrate with a collaboration service that provides chatbot. Integrating with a collaboration service (see
page 585)
3 (Optional) Create a chat listener and register the listener to receive chat context. Creating a chat context listener (see page 586
)
4 (Optional) Create process and actions that can be called in a dialog defined in the IBM Watson Creating processes and actions for dialogs
Assistant workspace. (see page 587)
5 Create a configuration for your application so an administrator can use the configuration to configure Creating a chatbot configuration for an
your chatbot application. application (see page 588)
6 Test your application by performing step 8 so that you can verify your chatbot application is working None
with user communication client services, such as Slack, Skype for Business, and SMS, which uses
Twilio.
7 Package and deploy your application. Deploying the custom code-based

applications to development environments
(see page 915)
8 Configure a chatbot for your application so that your application can work with user communication Configuring a chatbot for your application
client services, such as Slack, Skype for Business, and SMS, which uses Twilio. (see page 589)
9 (Optional) Test the chatbot to ensure that it correctly auto-categoriozes service requests that are Testing the chatbot training data to improve
raised on behalf of the end-users. predictability (see page 602)

To enable RSSO OAuth 2.0 in your chatbot application

See Enabling Remedy SSO OAuth 2.0 authentication for your application (see page 976).
Chatbot framework architecture

BMC Helix Innovation Suite platform contains a chat framework that manages the interaction between an external
collaboration service (such as Slack) and a machine learning provider (such as IBM Watson).
For example, if you are using the Slack collaboration service, the BMC Helix Innovation Studio chat domain performs the
following tasks:
Allows Open Authorization (OAuth) for the Slack service.
Sends message events through the Slack service.BMC Helix Innovation Suite Cognitive Service uses the Watson
machine learning capability.
Maps users between the Slack service and BMC Helix Innovation Suite.
Imports and exports the Watson Assistant workspace.
Invokes actions that are required by Watson.
The following example illustrates the chatbot framework architecture and provides an overview of how BMC Helix
Innovation Suite interacts with a collaboration service and a machine learning provider :

Related topic
Creating a conversation workspace

To add conversation capabilities in your application, you must create a conversation workspace by using the IBM Watson
Assistant tool. You can use the conversation workspace in your chatbot application. Based on your application use case,
you must provide data (intents, entities, and dialogs) to Watson that a chatbot needs to interact with your application
user. Watson analyzes the context of the conversation with the application user and from that data, provides a useful
response to the application user.
A conversation workspace consists of the following artifacts:
Intent—defines the action to perform such as create a ticket, find an issue.
Entity—is a class of object on which the action should be performed such as tickets and issues.
Dialog—uses the intents and entities to interact with an application user.
For information about intents, entities, and dialogs, see Planning your intents and entities in the IBM Watson
documentation.
Process to create a conversation workspace

The process of creating a conversation workspace comprises the following tasks:
Task Reference
Create a conversation workspace See Getting started tutorial in the IBM Watson documentation.
Create intents See Defining intents in the IBM Watson documentation.
Create entities See Defining entities in the IBM Watson documentation.
Create dialogs See Building a dialog in the IBM Watson documentation.
Format chatbot responses in a dialog To ensure that the chatbot responses are optimal for different communication clients supported by BMC
Helix Innovation Suite, you must format the chatbot responses. For more information, see To format
chatbot responses in a dialog (see page 579) in this topic.
Configure the chat actions in a dialog To ensure that based on the conversation between the chatbot and your application user, Watson sends an
action to your application to be performed on behalf of the user, you must configure the chat actions. For
more information, see To configure the chat actions in a dialog (see page 580) in this topic.
To format chatbot responses in a dialog

BMC Helix Innovation Suite enables your chatbot application to connect with different user communication clients (such
as Slack, Microsoft Office 365 Skype for Business, and SMS, which uses Twilio) and provides various interfaces for the
users to interact with your chatbot. When you create dialogs, you must define the code to format the chatbot responses
so that the user can view the response in the way that is optimal for the user interface. For information about how to
format chatbot responses, see Formatting chatbot responses to support multiple messaging interfaces (see page 583).

To configure the chat actions in a dialog

Based on the conversation between the chatbot and your application user, Watson sends an action to your application
to be performed on behalf of the user. In the conversation workspace dialog, define these chat actions to call the
process definitions or custom actions that you create for your application.
BMC Helix Innovation Suite supports the following types of chat actions in a dialog:
Starting a process
Executing a custom action
For example, if a user wants to create an issue, based on the conversation with the user, the machine learning provider
sends an action to create an issue to your BMC Helix Innovation Suite application. In this case, you can configure the chat
action to start a process that creates a new issue in your application.
The following example illustrates a dialog chat action configured to start a process:
The following JSON illustrates the dialog response that contains a chat action to start a process:
{
"output": {
"text": {
"values": [
"$user, Thanks for reporting the issue for $product_name on $product_version. The issue ID is
${actionResult.536870915}."
],
"selection_policy":"sequential"
},
"action": {
"inputMap": {
"536870912":"$product_name",

"536870913":"$product_version",
"536870914":"$issue_summary"
},
"outputMap": {
"issueID": "${actionResult.536870915}"
},
"processDefinitionName":"com.guicecat.issuefix:Create issue Process"
"waitForActionExecution": true
}
}
}
The following JSON illustrates the dialog response that contains a chat action to execute an action:
{
"context": {
"name": "developer"
},
"output": {
"text": {
"values": [
"Hello $name. your issue is ${actionResult.output.1}"
]
},
"action": {
"actionTypeName": "getRecord",
"inputMap": {
"recordDefinitionName": "com.guicecat.issueFix:issue",
"recordID": "AGGI08B9E3F9AAOT6IU1OSKCXKHI6P"
},
"outputMap": {
"issueID": "${actionResult.output.1}"
}
}
}
}
To clear a chat context

You can clear a chat context to remove all the chat variables so that a user can submit similar requests multiple times.
For example, in an issue fix application, a user want to create more than one issue request. In this case, the previous chat
context needs to be cleared so that a chatbot can process the new request.
Use the Clear Context action to clear a chat context.
The following sample code illustrates the Clear Context action:
{
"output": {
"action": {
"actionTypeName": "clearContext"
}
}
}

User identification by a chatbot

When a user starts a conversation with the chatbot, the chatbot identifies the user through the BMC Helix Innovation
Suite chatbot framework, which restricts the chatbot to perform only actions to which the user has permission to
perform. If a user is not permitted to perform an action, the chatbot returns an error to the user in the chat UI. For
example, in an issue fix application, if a user wants to create a new issue. The chatbot first identifies the user, and checks
whether the user has permissions to create a new issue, and then creates a new issue.
Note
User identification is only required when you use the communication clients Slack and Office 365 Skype for
Business.
When a conversation between a chatbot and a user starts, the chatbot responds with a Verify BMC Cloud account
button. The chatbot identifies the user based on the user's login credentials. The following image illustrates the user
identification process:


Integrating with a collaboration service (see page 585)
Formatting chatbot responses to support multiple messaging interfaces

BMC Helix Innovation Suite enables your chatbot application to connect with different user communication clients
services such as Slack, Skype for Business, and SMS, which uses Twilio. Users can interact with a chatbot through various
interfaces. For example, if you have configured your chatbot application to work with Slack and Twilio, your application
users can interact with your application chatbot by using the Slack user interface or they can send SMS by using mobile
devices.
During user interaction, the chatbot response messages must be displayed correctly on the user interface. As a
developer, you must format the responses so that the users can view the responses in the way that is optimal for their
interfaces.
Before you begin

Ensure that you have created a conversation workspace for you chatbot application. See Creating a conversation
workspace (see page 579).
Syntax to format a chatbot response

BMC Helix Innovation Suite supports the Hyper Text Markup Language (HTML) for formatting chatbot responses so that
a user communication client service can take the HTML syntax and convert the messages suitably for the user interface.
Supported HTML markup tags to format a chatbot response

The following HTML markup tags are supported for formatting chatbot responses. Blank cells indicate no support.
Tag Supported on SMS Supported on Slack Supported on Skype for Business
Structure tags
Paragraph <p>
Linebreak <br>
List <ul>, <li>
Table <tr>, <th>, <td>
Ordered List <ol>, <li>
Style tags
Text color <p style= " color:blue ;">
Smaller text <small>
Italic text <i>
Bold text <b>
Quotation <blockquote>

Tag Supported on SMS Supported on Slack Supported on Skype for Business
Link tags
Hyper text: <a href="url">link text</a>
Image: <img src="url">
To format chatbot responses

You must provide the formatted chatbot response messages when you define the dialogs for your application.
1. In IBM Watson Assistant tool, navigate to the conversation workspace that you created for your application.
2. In the conversation workspace, navigate to the dialog in which you want to format a response.
3. Modify the response in the dialog by using the HTML syntax and save the changes.
Example of using the HTML table tag in a chatbot response

The following table provides the HTML code to display an example chatbot response that contains links to knowledge
articles:
Chatbot response Code
How do I reset my password?
Number of Views: 45 <html>

<table>
45% marked as Useful <tr>
<th/>
Updated: Jan 29, 2018 <th>Number of Views</th>
<th/>
Reset your password with a text message
<th>Updated</th>
Number of Views: 40 </tr>
<tr>
29% marked as Useful <td><a href="url">How do I reset my
password?</a></td>
Updated: Jan 20, 2018 <td>45</td>
<td>45% marked as Useful</td>
<td>Jan 29, 2018</td>
</tr>
<tr>
<td><a href="url">Reset your
password with a text message</a></td>
<td>40</td>
<td>29% marked as Useful</td>
<td>Jan 20, 2018</td>
</tr>
<table>
</html>
Do not provide the labels such as Number of Views and Updated in each table cell tag (<td>). You can define such labels
in the table header tag (<th>).

Related topic
Integrating with a collaboration service

To create a chatbot for your application, BMC Helix Innovation Suite provides an open architecture to integrate your
application with third-party collaboration services such as Facebook Messenger, Skype, and so on. You must implement a
chat event handler for the collaboration service to integrate your application with a collaboration service (other than
Slack, Skype for Business, and Twilio). After you implement and configure the chat event handler, the BMC Helix
Innovation Suite platform interacts with the collaboration service by passing the chat messages through the chat event
handler.
For information about how to create a chatbot by using the Slack collaboration service, see Enabling Slack in a chatbot
application (see page 590).
For information about how to enable Skype for Business for a chatbot application, see Enabling Skype for Business in a
chatbot application (see page 594).
For information about how to add SMS capability in a chatbot application by using Twilio, see Enabling an SMS chatbot
conversation in an application (see page 597).
To implement a chat event handler
1. In your BMC Helix Innovation Suite application project, create a class to implement a chat event handler by using
the following code:
public interface ChatEventHandler<T extends ChatEvent> {
/**
* gets the chatbot provider (i.e. Slack) of this event handler.
*
* @return the chatbot provider
*/
String getChatbotProvider();
/**
* Handle the event.
*
* @param chatbotApplicationConfiguration
* the configuration to be used to handle the event
* @param chatEvent
* the chat event
* @return the response string
*/
String handleEvent(ChatbotApplicationConfiguration chatbotApplicationConfiguration, T chatEvent);
/**
* Convert the event JSON to a ChatEvent.
*
* @param eventJson
* the event payload.
* @return the converted chat event.
*/
T convertToChatEvent(String eventJson);
/**
* Post the message to a chat recipient, which can be an individual, a chat group or a chat

* channel.
*
* @param chatbotApplicationConfiguration
* the configuration to be used to post the response messagse
* @param chatRecipientName
* it is the name of an individual, a chat group or a chat channel
* @param textMessage
* the text message to be posted
*/
void postMessage(ChatbotApplicationConfiguration chatbotApplicationConfiguration,
String chatRecipientName, String textMessage);
/**
* Return JSON of field values to configure this specific chatbot provider.
* <p>
* For Slack chat, it requires "bot user access token" and "verification token" in the
* configuration, so those two field values are returned for Slack Event Handler. If there is a
* default value for the field, please enter the default value. Otherwise, please leave the
* value as an empty string.
*
* @return the chatbot application descriptor json
*/
String getChatbotApplicationDescriptorJson();
}
2. In your BMC Helix Innovation Suite application project, register the chat event handler with the collaboration
service by using the following code:
package com.bmc.arsys.rx.services.chat;
public
interface ChatService {
/**
* Register chat event handler.
*
* @param ChatEventHandler the chat event handler
*/
void register ChatEventHandler (ChatEventHandler chatEventHandler);
...
}

Creating a chat context listener (see page 586)
Creating a chat context listener

You may need to know the conversation between your application user and chatbot for auditing purposes or to verify
that the chatbot is performing tasks properly. For example, for a create bug application, you might want to check that a
bug is created according to the details provided by the user.
By creating a chat context listener, you can configure your application to receive a chat context. After you register the
listener, it transfers all of the conversations between a user and a chatbot to your application.
To create a chat context listener
1. In your BMC Helix Innovation Suite application project, create a chat context listener for your application.
package com.bmc.arsys.rx.services.chat.domain;

1.
public interface ChatContextListener {
/**
* Gets the bundle id.
*
* @return the bundle id
*/
public String getBundleId();
/**
* Publish the chat context to the bundle.
*
* @param chatContext the chat context
*/
public void publishChatContextToBundle(ChatContxt chatContext);
}
2. In your BMC Helix Innovation Suite application project, register the chat context listener with the chatbot
collaboration service.
package com.bmc.arsys.rx.services.chat;
public interface ChatService {

/**
* Register chat context listener.
*
* @param chatContextListener the chat context listener
*/
void registerChatContextListener(ChatContextListener chatContextListener);
...
}

Creating processes and actions for dialogs (see page 587)
Creating processes and actions for dialogs

To add conversation capabilities to your application, you need to create a IBM Watson Assistant workspace. The
workspace consists of dialogs that are used by Slack bot user to interact with your application user. Based on the
conversation, Watson sends an action to your application that needs to be performed on the behalf of the user. In the
conversation workspace dialog, you can define these actions to call the process definitions or custom actions that you
create for your application.
For example, if a user wants to create a bug, based on the conversation with the user, the machine learning provider
(Watson) sends an action of bug creation to your BMC Helix Innovation Suite application. In this case, you can configure
this action to start a process that creates a new bug in your application.
For information about how to create a conversation workspace, see Creating a conversation workspace (see page 579).
For information about the how BMC Helix Innovation Suite interacts with external collaboration service and machine
learning provider , see Adding a chatbot and conversational capabilities to your application (see page 576).
The following table describes how to create processes and actions for dialogs:

Task Description
To create You can create process definitions for your application by using BMC Helix Innovation Studio and then configure the dialogs in the conversation
a process workspace to use these process definitions.
See Defining the application business logic through processes (see page 421).
You can also use the Cognitive and Assignment elements to add auto categorizations and auto assignments in your process definitions. See
Automating categorization and assignment of application requests (see page 478) and Adding cognitive capabilities to a custom application (see
page 552).
To create You can create custom actions (Java actions) for your application and then configure the dialogs in the conversation workspace to use these
a custom actions.
action
See Creating a custom service in Java (see page 823).

Creating a chatbot configuration for an application (see page 588)
Creating a chatbot configuration for an application

You must create a configuration (of the type in-bundle setting) in your application that can be used to configure your
chatbot.
To create a chatbot configuration
2. Select the application in which you want to create a setting.
4. Click New > In-bundle Settings.
5. In the New In-bundle Settings window, specify the required properties, and click Save.
Component name Indicates the name for the configuration that is the name of the in-bundle setting Chatbot configuration
Is View Component Opens a view definition in the application Not selected

You do not need to select this property.
Registered Module Specifies the unique name of the registered module cognitive-chatbot
Name Select the cognitive-chatbot option from the list.
Status Provides the status of the configuration Selected

You must select this property.
Available in Makes the configuration available in BMC Helix Innovation Studio Administrator tab Selected
Navigation Sidebar You must select this property.
Component Label Specifies the unique label for the configuration Chatbot configuration
The label you provide appears as a setting in the Administrator tab.
Show In Specifies whether you want to show the configuration in the application, in BMC Helix Innovation In BMC Helix
Studio, or both Innovation Studio
You must select In BMC Helix Innovation Studio option or Both option (that is in BMC Helix
Innovation Studio and in application).

Permissions Defines the permissions associated with the setting Administrator group
You can add permissions for a group or a role.
First Menu Defines the first menu that gets displayed in the BMC Helix Innovation Studio Administrator tab My application
Second Menu Defines the second menu that gets displayed in the BMC Helix Innovation Studio Administrator
tab
After you create the application configuration, it is displayed in the Settings section in the Administration tab. The
following image displays an example configuration created by using the example values:
Related topics
Configuring a chatbot for your application (see page 589)
Configuring cognitive service for a custom application (see page 556)
Configuring a chatbot for your application

You must configure a chatbot for your application so that your application can work with different user communication
clients such as Slack, Microsoft Office 365 Skype for Business, and SMS, which uses Twilio.
For example, you might want to provide Short Message Service (SMS) chatbot conversation facility to your application
users. To provide the SMS facility, you must configure your chatbot to work with Twilio so that your application users
can interact with a chatbot by sending text messages through their mobile devices.
You can also use more than one communication client in an application, such as Office 365 Skype for Business, to enable
conversation through Office 365 Skype for Business and Twilio to enable conversation through SMS.

This section provides information about how to configure your chatbot to work with Slack, Office 365 Skype for
Business, and Twilio:
Action Reference
Create a chatbot for your application by using the Slack collaboration service. Enabling Slack in a chatbot application (see page 590)
Enable Office 365 Skype for Business channel for a chatbot application. Enabling Skype for Business in a chatbot application (see page 594)
Enable a SMS chatbot conversation in an application by using Twilio. Enabling an SMS chatbot conversation in an application (see page 597)
Enabling Slack in a chatbot application

To add conversation capability in your application by using Slack, you must create an application in Slack, and configure
the Slack application to interact with BMC Helix Innovation Suite. The Slack application consists of a chatbot that you can
configure to work with your BMC Helix Innovation Suite application. For information about chatbot framework
architecture, see Chatbot framework architecture (see page 578).
The process of creating a Slack application and configuring it to work with your BMC Helix Innovation Suite application
comprises the following tasks:
Task Reference
Create a team in Slack See Create a Slack workspace and Inviting new member to your Slack team in the Slack
documentation.
Create an application in Slack See Building Slack applications in the Slack documentation.
Creating an application in Slack consists of the following tasks:
Creating a chatbot for your application

See Bot users in the Slack documentation.
Configuring your Slack application to work with BMC Helix Innovation Suite and IBM Watson.
See To configure a Slack application (see page 590).
Configuring your Slack application to add interactive elements to messages from your
application (see page ).
Install your Slack application to your Slack team See Installing applications in the Slack documentation.
Configure your BMC Helix Innovation Suite chatbot See To configure an Innovation Suite chatbot application (see page ).
application
To configure a Slack application

You must configure the events, endpoints, and permissions of your Slack application so that when a chatbot interacts
with your BMC Helix Innovation Suite application user, Slack can send the user messages to BMC Helix Innovation Suite
and then BMC Helix Innovation Suite can work with IBM Watson.
1. In your Slack application, navigate to Add features and functionality > Event Subscription.
2. In the Enable Events section, enable events and enter the Request URL such as
https://{{serverName:port}}/api/rx/application/chat/event/slack/{{TenantID}}
3.
3. In the Subscribe to Workspace Events section, add a workspace event of the type message.im.
The following image illustrates an Event Subscriptions configuration example:
4. Navigate to Add features and functionality > Permissions and provide the following permissions:
Permission Description
chat:write:bot Allows the bot user to post messages in the conversation channel.
channels:history Allows BMC Helix Innovation Suite to receive events when Slack team members send messages to a conversation channel.
im:history Allows BMC Helix Innovation Suite to receive events when a message is posted in the conversation channel.
To configure an BMC Helix Innovation Suite chatbot application

To configure your BMC Helix Innovation Suite chatbot application, you must configure the IBM Watson Assistant service
credentials and configure your chatbot application to work with Slack by using BMC Helix Innovation Studio.
To configure the IBM Watson Assistant service credentials

5.

You can also set the chat session idle time for your application by using BMC Helix Innovation Studio; see To configure
chat session idle time (see page 558).
To configure your Slack application to add interactive elements
1. Log in to https://api.slack.com/apps with your Slack user account, and select the application that you want to
use.
2. Select Features > Interactive Components.
3. In Request URL, specify the WebHook URL.
4. Click Save Changes.
For more information, see Readying your application for interactive messages in the Slack documentation.
To configure a chatbot application to work with Slack
2. Click the configuration that you created for configuring your chatbot application. See Creating a chatbot
configuration for an application (see page 588).
For example, select My application > Chatbot Configuration.
Note
If your application contains the Watson workspace and you have configured the Watson Assistant
service credentials, the Conversation Workspace ID field value is populated automatically. Else, you
must add the Conversation Workspace ID value manually.
3.
3. In the Chatbot Service, from the Add Chatbot Provider Settings list, select Slack.
4. In the Slack Settings section, enter values for the following fields, and click Save.
Field Description
Chatbot Application Enter the description that provides details about the setting.
Description
Slack Application ID Enter the Slack Application ID. You can find the Slack Application ID in the Slack application console URL. See Using OAuth
in the Slack documentation.
Slack Bot User Auth Enter the user authentication token for Slack. To get the token value, in your Slack application, navigate to OAuth Tokens &
Access Token Redirect URLs, and copy the Bot User Auth Access Token value.
For example:
Slack Verification Enter the verification token for Slack. To get the token value, in your Slack application, navigate to Basic information > App
Token Credentials, and copy the Verification Token value.
For example:
Webhook URL (Information only) This field is populated automatically.

Webhook URL is the Request URL that you provide when you configure your Slack application.

Related topic
Enabling Skype for Business in a chatbot application

You can use Microsoft Office 365 Skype for Business as one of the communication clients for chatbot applications so
that the application users can interact with a chatbot by using the Office 365 Skype for Business channel.
To utilize this channel, you must use the Microsoft Azure Bot Service.
The following video (3:56) provides the process overview to enable Microsoft Office 365 Skype for Business as a
communication channel in a chatbot application:
The process of enabling the Office 365 Skype for Business channel for a chatbot application comprises of the following
tasks:
1 Register your chatbot with the To register a chatbot with the Azure Bot Service (see page 594)
Azure Bot Service.
2 Enable Office 365 Skype for To enable Office 365 Skype for Business channel (see page 595)
Business channel by using
Azure.
3 Configure your chatbot To configure a chatbot application (see page 595)

application by using BMC Helix
Innovation Studio.
4 Test the chatbot with Web To test a chatbot with Web Chat (see page 596)
Chat by using Azure.
5 Connect the chatbot to Skype To connect a chatbot to Office 365 Skype for Business (see page 596)
for Business by using Office
365 administrator credentials.
Before you begin

You must be subscribed to Microsoft Office 365 with Skype for Business online and Microsoft Azure Bot Service .
To register a chatbot with the Azure Bot Service
1. Log in to Microsoft Bot Framework .
2. In the Bot Framework tab, click Create a bot or skill.
3. Select Create a bot with the Azure Bot Service and click Create.
4. In Azure Bot Service portal, register your chatbot with the Azure Bot Service.
See Register a bot with Bot Service in Microsoft documentation.
When you register your chatbot with the Azure Bot Service, you must enter the following field values for
Messaging endpoint and Application Insights fields:
a.
a. Messaging endpoint:
https://{{serverName:port}}/api/rx/application/chat/event/skype/{{TenantID}}
After you configure the messaging endpoint, you must not modify the endpoint at any later stage.
b. Application Insights: Off
After you register a chatbot, you will receive a Microsoft Application ID and password that you can use to configure your
chatbot application by using BMC Helix Innovation Studio
To enable Office 365 Skype for Business channel

See Enable Skype for Business channel in the Microsoft documentation.
To configure a chatbot application

credentials and configure your chatbot application to work with Office 365 Skype for Business by using BMC Helix
Innovation Studio.
To configure the Watson Assitant service credentials


You can also set the chat session idle time for your chatbot application by using BMC Helix Innovation Studio. See To
configure chat session idle time (see page 558).
To configure a chatbot application to work with Office 365 Skype for Business
2. Click the configuration that you created for your chatbot application. For more information, see Creating a
chatbot configuration for an application (see page 588).
Note
If your application contains the Watson workspace and you have configured the Watson Assistant
must add the Workspace ID value manually.
3. In the Chatbot Service, from the Add Chatbot Provider Settings list, select Skype for Business.
4. In the Skype for Business Settings section, enter values for the following fields, and click Save.
Field Description
Description Enter the description that provides details about the setting.
Microsoft App ID Enter the Microsoft application ID that you get after you register your chatbot with Microsoft Bot Azure Service.
Microsoft App Password Enter the Microsoft application password that you get after you register your chatbot with Microsoft Bot Azure Service.

Webhook URL is the messaging endpoint URL that you provide when you register a chatbot with Azure Bot Service.
To test a chatbot with Web Chat

After you configure your chatbot application in BMC Helix Innovation Studio, you can test the working of your chatbot
with Web Chat and ensure that the messaging endpoint URL is correct by using Azure Bot Service.
See Test a bot in the Azure Portal with Web Chat in the Microsoft documentation.
To connect a chatbot to Office 365 Skype for Business

See Adding a bot to Skype for Business and Skype for Business Bot - Common Errors in the Microsoft
documentation.
When you add your chatbot to Office 365 Skype for Business, you must provide the following values:
You must provide the Office 365 administrator credentials when you run the shell commands.
You must provide the Uri in the following format:

-Uri sip:bothandle@yourdomain.com
bothandle is the unique name of your chatbot with no spaces and all characters in lower-case.
yourdomain.com is the domain name that you use in Office 365.

Related topic
Enabling an SMS chatbot conversation in an application

BMC Helix Innovation Suite provides an Short Message Service (SMS) conversation capability for chatbot applications so
that the application users can interact with a chatbot through text messages by using their mobile devices. To utilize this
capability, you must use the Programmable SMS service provided by Twilio.
The process of enabling an SMS chatbot conversation in an application comprises the following tasks:
You must perform the process to add the SMS conversation capability to a chatbot application.
To create a Twilio account

Sign up for Twilio Programmable SMS .
After you sign up for Twilio, you receive an email that contains your Twilio account credentials, Account SID and Auth
Token.
To create a messaging service

You must create a separate messaging service for each chatbot application.
1. Log in to Twilio .
2. Create a new project that includes the Programmable SMS feature.
3. In your project, navigate to Programmable SMS > Messaging Services, and click Create new Messaging Service.
4.
4. Enter the Messaging Service name, select the USE CASE value as Chat Bot/Interactive 2-Way, and click Create.
5. In the Configure pane, enter the properties, and click Save.
Note
In Inbound Settings, you must enable the PROCESS INBOUND MESSAGES option and enter the
REQUEST URL value in the following format:
https://{{serverName:port}}/api/rx/application/chat/event/twilio/{{TenantID}}
For example:
To associate phone numbers

You must associate phone numbers with each messaging service for an application so that your application users can
send messages to these phone numbers.
2. Navigate to your project for which you want to configure phone numbers for a messaging service.
3.
3. In your project, navigate to Programmable SMS > Message Service > Numbers, and add phone numbers for the
messaging service.
For more information about the Programmable SMS, see Programmable Messaging in Twilio documentation.
To set call forwarding

You can also set up call forwarding for your Twilio phone number, so that a call coming to your Twilio phone number
can be forwarded to any other number.
2. Navigate to your project for which you want to set call forwarding for a phone number.
3. Search for TwiML Bins, in the RUNTIME section, select TwiML Bins.
4. In TwiML Bin, click Create new TwiML Bin.
5. Enter the values for the following fields, click Create, and save the changes.
Field Description
FRIENDLY NAME Enter a name that describes to whom you are forwarding a call such as Forward messages to Jayant.
TWML Enter the following code by replacing +1xxxxxxxxxx with phone number to which you want to forward calls:
<?xml version="1.0" encoding="UTF-8"?>

<Response>
<Dial>
+1xxxxxxxxxx
</Dial>
</Response>
You must provide your company support contact number or your company phone number.
6. Navigate to Console Dashboard, in Phone numbers section, click Manage Numbers.
7.
7. Select the phone number which is associated with your application and in the Voice & Fax section, update the
fields A CALL COMES IN and PRIMARY HANDLER FAILS.
For more information about call forwarding, see Setting up call forwarding in Twilio documentation.
To configure a chatbot application

credentials and configure your chatbot application to work with Twilio by using BMC Helix Innovation Studio.
To configure the Watson Assistant service credentials
6.

You can also set the chat session idle time for your application by using BMC Helix Innovation Studio; see To configure
chat session idle time (see page 597).
To configure a chatbot application to work with Twilio
2. Click the configuration that you created for configuring your chatbot application. For more information, see
Configuring cognitive service for a custom application (see page 556).
Note
If your application contains the IBM Watson workspace and you have configured the Watson Assistant
must add the Conversation Workspace ID value manually.
3. In the Chatbot Service, from the Add Chatbot Provider Settings list, select Twilio.
4. In the Twilio Settings section, enter values for the following fields, and click Save.
Field Description
Description Enter the description that provides details about the setting.
Twilio Enter the Service SID of the messaging service created in Twilio.
Message For example:
Service ID
Twilio Enter the Twilio Account SID that you receive when you create a Twilio account.
Account ID
Twilio Enter the Twilio Auth Token that you receive when you create a Twilio account.
Authentication
Token

Field Description

Webhook URL is the REQUEST URL that you provide when you configure a messaging service in Twilio.
The process for enabling SMS conversation for your application is now complete.
Note
To use the SMS conversation capability, the users must be registered as agents in Foundation data and the
users must have the Primary Contact Information as mobile numbers in the following format:
+ <country code> <mobile number> such as +14085461010
For information about creating agents, see Creating or modifying Person data (see page 664).
Related topic
Testing the chatbot training data to improve predictability

As an administrator, you can test whether the chatbot application is able to understand the conversation context and
provides appropriate responses when interacting with users in natural language, and perform tasks on behalf of end
users. You must create a CSV data set to test the chatbot application. The test results provide the exact problem area
when the chatbot does not respond appropriately so that administrators can rectify the chatbot intents, entities, and
dialogs (that serve as training data). The tests are particularly important when you are implementing a new data set or if
you have made major changes to the data set. For more information, see Testing the cognitive service data sets to
improve predictability. (see page 283)
CSV data set structure for a chatbot application

You must create a CSV file to test a chatbot application. The CSV file should have the following structure:
A row represents a record.
The first column represents the natural language text to which the chatbot responds.
Example: Vacation time
The second column represents the intent that the chatbot understands and responds to.
Example: For vacation time as the natural language text, the chatbot should understand the intent as PTO.
Each row contains a natural language text and the intent that applies to the text.
Example of a test CSV file

The following image given an example of a CSV test data file for chatbot:

Before you begin
Ensure that you have created IBM Watson Assistant and created intents, entities, and dialogs. For more
information, see Creating a conversation workspace (see page 579) .
Ensure that you have created the CSV test data file.
If you have configured your chatbot application for localization, ensure that your test data locale matches with
the workspace locale.
To test and rectify chatbot data
Example: My Application > Cognitive Training
3. Expand the Chatbot Evaluation tab.
4. Upload and test the CSV test data file.

To upload and test the CSV data file
a. On the Data Sets tab, click New.
b. On the New CSV Data Set page, provide the Data Set Name and Description.
c. In CSV File, select the test data file that you created.
d. In Locale, select the locale of your test data file.
e. Click Save.
f. Select the test data file and click Test .
5. View and download the test results.

To view and download the test results
a.
5.
a. On the Test Results tab, you can view the score of all the test metrics—accuracy, precision, recall, and F-
score.
b. To download the test results CSV file, in the Results column, click the test results file.
6. Rectify the chatbot training data.

To improve the chatbot training data
a. From the test results CSV file, view the input texts for which the chatbot could not identify the intent
correctly.
a. Add more entities for these intents and test the chatbot again to view the results.
Tip
To delete the test results that are no longer required, you can create a process (see page 457) by using
the Delete record element.
Related topics
Leveraging machine learning metrics to improve chatbot predictability
Integrating with REST services in a codeless way

Developers can connect applications to REST API services without writing code or using connectors, directly from the
the BMC Helix Innovation Studio UI. For example, if you have an Integration Platform as a Service (iPaaS), you can define
the REST communication between BMC Helix Innovation Suite and the integration middle ware, without having to write
code or run an integration controller. Instead, you define a one-time configuration for each RESTful service that you
want to connect to and create web requests for various HTTP methods such as GET, PUT, POST, or DELETE.
Points to consider before connecting to RESTful service in a codeless way

Consider the following supported and unsupported technologies before connecting to RESTful service in a codeless way:
Supported authorization and authentication—Basic Auth, OAuth 2.0 (client credentials grant type), and Remedy
Single Sign-On (Remedy SSO).
Supported content types—JSON

REST web definitions—Once deployed as part of an application or library, administrators will not be able to
modify these by using the Customization layer.
Scenario: Connecting to the JIRA REST API service

Your organization has a custom self-service application developed on BMC Helix Innovation Suite that employees use to
create service requests, access knowledge articles, and so on. Your organization also uses Atlassian JIRA for project-
tracking. As a developer of the self-service application, you want to connect the application to the JIRA REST service
from the BMC Helix Innovation Studio UI so that you can get details about a JIRA issue in your application. To connect
the JIRA REST service in a codeless way, you must perform the following tasks:
Create the JIRA REST service definition in BMC Helix Innovation Studio and create a web request to get the issue
details from JIRA.
Configure the authentication connection for the JIRA REST service and map the web request to the appropriate
connection.
To use the JIRA issue details in the self-service application, configure the Web Request element in the Process
designer.
After the process is triggered, end users can see the JIRA issue details.
The following video (8:43) shows how you can integrate with JIRA REST API service to extend BMC Helix Chatbot:
https://youtu.be/n2X0YUTJ_68
Process for connecting to a REST API service

The following images represents the tasks in the process of connecting to a REST service:
Note
After deploying an application in the production environment, you do not need to create the REST API service
definition and configure the REST service web request in a process. Administrators can directly configure the
authentication connection and map the REST API web request with the connection.

Before deploying an application in the production environment
After deploying an application in the production environment
The following table explains the tasks in the process of connecting to a REST service in a codeless way:

1 Create a REST service definition along with web requests for the required methods Creating a REST API web service request definition (see page
such as GET, POST, PUT, and DELETE. 607)
2 Configure the authentication connection for the REST service definitions. Configuring the authentication credentials of REST API web
services (see page 609)
3 Configure the Web Request element in a process. Configuring web requests in a business process (see page 612)
4 Map the REST API web request with the appropriate authentication connection. Mapping the REST API web service request alias to an
appropriate connection (see page 614)
Related topic
Integrating with another application by using a connector (see page 615)
Creating a REST API web service request definition

Developers can connect to RESTful services in a codeless without installing an IDE, writing Java code, or running and
managing an integration controller. You must create a one-time RESTful service definition and create web requests for
the required methods such as GET, POST, PUT, and so on. This is the first task in the process for connecting to a RESTful
service (see page 604).
For example, if you want to connect to a JIRA RESTful service, you must create a one-time service definition for the JIRA
REST API and create web requests, such as Create JIRA issue (with PUT method) or Assign JIRA issue (with POST
method).
Before you begin

To ensure that the REST API request body (for PUT and POST methods) and the response (for GET method) is provided,
you must create a document definition. For more information, see Defining document definitions (see page 497).
To create a web service request definition
2. From the Workspace tab, select the application from which you want to connect to a RESTful service.
3. Click the Web APIs tab and click New.
4. On the Properties tab, provide a name for the RESTful Service, such as JIRA API.
5. On the New Web API page, perform one of the following steps:
To add a web request to an existing Web API, click the Web API name.
To create a new Web API, click New.
6. On the Settings tab, fill out the following fields:

Field Description Example
Name Type a name for the web request. Create

Issue

Request Select the HTTP method of the web request. POST

Method
Path Specify the URL path on which the method is invoked. /rest/api
Format of the URL: /rest/api /latest
/issue/
(Optional) From the list, select the Document Definition that you created earlier from which you want to copy the body in JSON None
Body format. Typically, this is need for the POST or PUT methods, but might not be required for other methods.
(Optional) From the list, select the Document Definition that you created earlier from which you want to copy the response in None
Response JSON format.
(Optional) Add the headers for this web request. None

Add Headers
(Optional) Add the query parameters for this web request. None
Query
Parameters
Add Path The values are auto-populated and are non-editable. None
Parameters
7. Click Save.
The following image is an example of creating a web request definition for JIRA:


Configuring the authentication credentials of REST API web services (see page 609)
Configuring the authentication credentials of REST API web services

BMC Helix Innovation Suite allows you to connect you application with the REST API web services of another application
in a codeless way. After creating a one-time REST API web service definition, you must configure the authentication
credentials of the REST API web services to which you want to connect in a codeless way. For example, if you want to
connect to a JIRA REST API web service, you must configure the authentication credentials of JIRA service.
BMC Helix Innovation Suite supports Basic Authentication (Basic Auth), Open Authorization 2.0 (OAuth 2.0) with
client_credentials grant type, and Remedy Single Sign-On (Remedy SSO).
Before you begin
Ensure that you have the authentication credentials of the REST API web service that you want your application
to connect to.

Ensure that you have created the RESTful web service request definition. For more information, see Creating a
REST API web service request definition (see page 607).
For example, if you want to provide the authentication credentials of JIRA REST service, you must create the JIRA
web service request definition.
If you want to use Remedy SSO, ensure that the OAuth client is registered in Remedy Single Sign-On (RSSO).
When registering OAuth 2.0, ensure that you copy the Client ID and Client secret. To see the steps to register a
client, see Configuring OAuth 2.0 authentication in Remedy Single Sign-On online documentation.
Click here to view the details to be pasted
To configure the authentication credentials
2. Click Web API Connection and click New.
3. On the General tab, in the Name field, type a meaningful name for the REST API web service connection, such as
JIRA connection.
4. In Host Name, provide the host name from which the connection is established, such as jira.com .
5. Fill out the Port and the Protocol fields.
6. In Authentication, select one of the supported types: Basic Auth, OAuth 2.0, or RSSO.
7. To add the authentication credentials, click Next.

The following image is an example of configuring authentication credentials for JIRA REST API:

(If you selected Basic Auth)

On the Authentication tab, enter the Basic Auth credentials by using the following steps:
a. In Login, enter the basic authorization user name of the REST API web service.
b. In Password, enter the password of the basic authorization protocol.
c. (Optional) If the REST API web service requires custom headers to establish a connection, in
Headers, add the headers and the values.
(If you selected OAuth 2.0)

On the Authentication tab, enter the OAuth 2.0 credentials by using the following steps:
a. In Access Token URL, enter the resource of the URL from which access tokens are generated for
the REST service.
Example: If the URL is http://api.jira.com/oauth2/token, in the Access Token URL field, type /oauth2
/token.
b. In Client ID, enter the client ID of the REST API service.
c. In Client Secret, enter the client secret of the REST API service.
d. (Optional) In Scope, specify the restricted scope of access for these credentials.
e. (Optional) In Authorization Server Endpoint, specify the server name.
f. (Optional) If the RESFful service requires custom headers to establish a connection, in Headers,
add the headers and the values.
(If you selected RSSO)

On the Authentication tab, enter the RSSO credentials by using the following steps:
a. In Login Name, enter the Remedy SSO user name.
b.
b. In Access Token URL , enter the resource of the URL from which access tokens are generated for
the REST service .
Example: If the URL is http://api.servername.com/rsso/oauth2/token, in the Access Token URL field,
type /rsso/oauth2/token.
c. In Client ID and Client Secret, enter the details that you obtained when registering the OAuth client
(see page 610).
d. (Optional) In RSSO Server Endpoint, select one of the following options:
Default—If the Remedy SSO server is the same as the Hostname provided on the General tab.
Enter RSSO Server Endpoint—If the Remedy SSO server is different that the one specified as the
Hostname provided on the General tab, enter the RSSO server endpoint in the following format:
https:/servername:port
a. (Optional) If the RESFful service requires custom headers to establish a connection, in Headers,
add the headers and the values.
8. Click Save.

Configuring web requests in a business process (see page 612)
Configuring web requests in a business process

You can connect your application with the REST API web services of another application in a codeless way. After creating
the RESTful web service request definitions and configuring the authentication credentials for the REST API service,
developers can manage the data that comes from a web request or is sent to a web request. You must configure the
Web Request element in the BMC Helix Innovation Studio Process designer to invoke web API requests as required by
the application's business logic.
For example, if you want to connect to a JIRA RESTful service to get details of a JIRA issue in your application, you must
configure the Web Request element to use the required values from the body of the JIRA REST API.
Before you begin
If you want to use the PUT or POST methods, ensure that you have configured the Create Document element in
the Process designer. The Create Document element enables you to use the object metadata from the
appropriate document definition as input to the web request.
For more information, see Creating a document instance (see page 488)
Ensure that you have created the RESTful web service request definition.
For more information, see Creating a REST API web service request definition (see page 607)
Ensure that you have configured the authentication credentials of the RESTful web service.
For more information, see Configuring the authentication credentials of REST API web services (see page 609)
To configure the Web Request element in a process

2. From the Workspace tab, navigate to the application that you want to connect to a REST API web service.
3. Perform one of the following tasks:
If you want to add the Web Request element to a new process, select Processes > New.
If you want to add the Web Request element to an existing process, click the Processes tab and click the
name of process.
4. From the Palette, on the canvas, drag the Web Request element to the canvas at that point in the process where
you want to invoke the web API request.
Note
If you are using the PUT or POST method, typically, you place the Web Request element after the
Create Document element.
5. In the Element properties tab, in the Label field, type a meaningful name for the web request, such as
Create Issue.
6. In the INPUT MAP section, from the Connection list, select the connection that you want to use for this web
request, such as JIRA.
7. From the Web API list, select the REStful web service request definition that you created earlier, such as JIRA APIs
.
8. From the Request list, select the web request that you created in this web service request definition, such as
Create Issue.
9. (Ony for PUT or POST methods) In Document, click Click to build an expression, and from the Web Request
node, select the request body.
10. Click Save.
Best practice
After configuring the Web Request element in a process, BMC recommends that you test the process by using
the Manage Processes dashboard for the following aspects:
Check the logical flow.
Troubleshoot the process is a task results in a system error.
For more information, see Managing processes by using the Manage Processes dashboard (see page 474).
After you save the process, an alias is created for the web service request. An alias is a placeholder for a tenant-specific
configuration and is required to map with the appropriate Web API connection.


Mapping the REST API web service request alias to an appropriate connection (see page 614)
Mapping the REST API web service request alias to an appropriate connection
You can connect your application to the REST API web service of another application without using code or connectors.
After configuring web requests in a business process, an alias is created for the web request. An alias is a placeholder for
tenant-specific configurations. To ensure that the appropriate authentication credentials are used when a RESTful web
service is invoked from the business process, administrators must map the alias with the appropriate web API
connection.
For example, if you want to connect to a JIRA RESTful service, you must map the JIRA Web API alias with JIRA
connection. Administrators should have already configured the JIRA connection with authentication credentials.
Before you begin
Ensure that you have created the REST APl web service request definition. For more information, see Creating a
REST API web service request definition (see page 607).
Ensure that you have configured the authentication credentials of the REST web service. For more information,
see Configuring authentication credentials of a RESTful web service (see page 609).
Ensure that you have configured the web request in a business process. For more information, see Configuring
web requests in a business process (see page 612).
To map the web request alias with an appropriate web API connection
2. Select Configure My Server > Connection Mappings > Web API.
3. From the Select Application list, select the application from which you want to connect to the REST API web
service.
Note
If you have not created the REST API web request definition in any application, the list is blank.
A list of web request aliases that you configured for the selected application are displayed as Connection Target.
Example: JIRA
4.
4. In Connection Configuration, select the appropriate authentication credentials for the web request alias.
5. Click Save.
After you have completed all the tasks, when the process in which you have configured the web request is triggered, a
connection is established between your application and the REST API web service.
Related topics
Expression Editor (see page 499)
Integrating with another application by using a connector

BMC Helix Innovation Suite enables you to integrate the application with third-party system or application by using
Connectors. The process of using connectors involves steps like adding connector configurations, adding connector
element in Process or Rule designer, and creating alias mapping of the connectors. Following section gives information
about connectors and connector actions.
Connectors
A connector can be used to connect and configure BMC Helix Innovation Suite based applications with a third-party
application.
For more information about connectors, see Connectors overview (see page 50).
Connector Actions
A connector action is an activity triggered to connect BMC Helix Innovation Suite with a third-party application, by using
a connector. You can trigger the connector actions in two ways:
You can provide a unique alias to each connector action and map the application to BMC Helix Innovation Suite.
You can create and configure an alias for each connector action.You can provide a value for an alias for each
connector action. In the application, the value gets exported within the environments. You can also configure the
aliases and create connector configurations.
For more information about creating aliases, see Creating alias mapping of the connectors (see page 623) .
Literal is another option to create mapping of connector actions. The only difference between using aliases and
literal is that in literal, an administrator does not get the flexibility to change the name of connector
configuration. While using aliases, you can change the name of the connector action as per requirement and
usability.
Alias mapping is a preferred and recommended way of setting up and using connector actions.
Example of extending BMC Helix Chatbot by using connectors

The following video (9:17) demonstrates how to alter the conversation flow in BMC Helix Chatbot by using data from an
external application such as JIRA:
https://youtu.be/qDxSOeS9I6w


Action Reference
Create new connector configurations and provide details of the connector configurations like Adding connector configurations (see page 616)
Name, Type, Configuration, and so on.
Use Connector element in Process designer to integrate application with a third-party application. Integrating applications using process connector
element (see page 617)
Use Connector element in Rule designer to integrate application with a third-party system. Integrating applications using rule connector element
(see page 620)
Perform mapping of aliases with connector configurations for connector actions. Creating alias mapping of the connectors (see page 623
)
Perform troubleshooting of connectors. Troubleshooting integration service connection issues

(see page 991)
Adding connector configurations

You can create connector configurations and then map the configurations to the connector actions in the Process or
Rule designer. Mapping is required for exporting the connector configurations across the environments. The connector
configurations are tenant-specific.
Before you begin

While adding connector configurations, ensure that you provide BMC Integration Service credentials including
Username, URL and Password in Administration > Configure My Server > Integration Service > Authentication.
To add connector configurations
2. Select Configure My Server > Integration Service > Connector Configuration.
3. Click New and enter the details described in the following table:
Property Description Example
Name Enter name of the Connector element. The connector will be saved with this name. Jira
Connector Select the connector from the list of connectors.The list has all the connectors developed in BMC Integration Service. JIRA
Type connector
Configuration Select the connector configuration. A connector configuration contains information about third-party application or Jira on
service such as the protocol, server host name, and server port. Connector configurations are already created in the AWS
system.
Profile Select the connector profile. A connector profile is an account created for the connector in BMC Integration Studio Jira
and contains the details required to connect to the external system such as user credentials and so on. Admin
4. Click Save.


Creating alias mapping of the connectors (see page 623)
Integrating applications using process connector element

From Process designer in BMC Helix Innovation Studio, use the Connector element to integrate your application with a
third-party service or application. Connector element invokes the actions defined for a connector. Y ou add one or more
actions to a process, but each action is defined by a single Connector element.
Note
Any connector processes built using BMC Helix Innovation Studio 18.5.0 must be upgraded to BMC Helix
Innovation Studio 18.11.0.
For information about the connector development process and out-of-the box connectors, see Connectors overview
(see page 50).
To add connector in a process
1. Log in to BMC Helix Innovation Studio and navigate to t he Workspace tab.
4. Click the process name where you want to add connectors.

5. As per your requirements, add the input and output variables required for the process.
6. Drag the Connector element to the canvas and place it where you want to add it in the process and provide the
input and output connections.
Select the Connector element and enter the values for the following properties:
GENERAL
Label Enter the label for the Connector element.
Description Describe the details about the connector, such as the applications which will be integrated by using this connector,
other properties, and so on.
Connection Name Enter the same name as entered for the Connection tab for this connection.

INPUT MAP
Connection Select the name from the list. The list includes all the connectors that are configured in Connector Configurations
from Administration tab.
Use as alias Enable the option if you want to use the connector element as an alias. For more information about processes
related to aliases, see Adding connector configurations (see page 616) and Creating alias mapping of the connectors
(see page 623)
Action Select the connector action.

An action is a task that you want to perform by using the connector.
OUTPUT MAP
Name Select the process output from the list and map it with the action output. The process output is already created as a
part of process.
Source Enter the value based on the Action you choose in the INPUT MAP. The value in this field varies depending upon the
Action you select.
MULTI INSTANCE LOOP
Loop Type Select Parallel or Sequential from the list. For information about Multi instance loop, see Creating process steps or
activities (see page 434).
7. Enter the values for the parameters as described in the table above.
You can add the optional parameters by using the Add/Remove Parameters property.
Example: Process to create record instance for a JIRA issue by using JIRA connector
The following process integrates an application with JIRA services. The process adds a comment to a JIRA issue, creates
a new record instance, and adds the comment to the Description field of the record instance. The process consists of a
Connector element, a Create Record element, and a process input variable inputComment.
When you run the process, the process performs the following tasks:
1. The process variable inputComment (input parameter of the process) provides input to the JIRA Connector.
2. JIRA Connector adds the comment to the JIRA issue by using the parameter Issue Key.
The inputComment details are added as a comment in the JIRA issue.
3. JIRA Connector passes the inputComment details to the Create Record element.
4. Create Record element creates a new record instance of the selected record definition and populates the
Description field with the inputComment details.

General properties sample values

The following table illustrates sample values for the General properties in the process example:
Property Sample value
GENERAL
Name Demo Rule
Description Rule to create a JIRA issue
Enabled Selected
Run as Administrator
RECORD DEFINITIONS
Add/Remove Record Definitions Demo Record (primary record definition)
PERMISSIONS
Edit Demo Set
JIRA connector sample values

GENERAL
Label JIRA Connector
Description Process to create JIRA issue
Connection Name JIRA Configuration
INPUT MAP
Connection JIRA Configuration
OUTPUT MAP
Name From the list
Source Action specific
MULTI INSTANCE LOOP
Loop Type Parallel
Create Record sample values

GENERAL
Action Type Name Create Record
Label Create Record
Description Record specific
Run as Current user
INPUT MAP
Record Definition Name Task
OUTPUT MAP

Name From the list
Source Action specific
MULTI INSTANCE LOOP
Loop Type Parallel
Related topics
Troubleshooting integration service connection issues (see page 991)
Integrating applications using rule connector element

From Rule designer in BMC Helix Innovation Studio, use the Connector element to integrate your application with a third-
party service or application. Connector element invokes the actions defined for a connector. You add one or more
actions to a rule, but each action is defined by a single Connector element.
For information on the connector development process and out-of-the box connectors, see Connectors overview (see
page 50).
To add connectors in a rule
2. Select the application in which your rule exists.
3. In the application, click Rules.
4. Click the rule name where you want to add connectors.

The system opens the Rule designer and displays the process diagram on the canvas.
5. Drag the Connector element to the canvas and place the connector where you want to add the connector in the
rule and provide the input and output connections.
6. Select the Connector element and enter the values for the following properties:
GENERAL
Label Enter the label for the Connector element.
Connection Name Enter the same name as entered for the Connection tab for this connection.
INPUT MAP
Connection Select the name from the list. The list includes all the connectors that are configured in Connector Configurations from
Administration tab.
Use as alias Enable the option if you want to use the connector element as an alias. For more information about processes related
to aliases, see Adding connector configurations (see page 616) and Creating alias mapping of the connectors (see page
623).

Action Select the connector action.

An action is a task that you want to perform by using the connector.
OUTPUT MAP
Name Select the process output from the list and map it with the action output. The process output is already created as a
part of process.
Source Enter the value based on the Action you choose in the INPUT MAP. The value in this field varies depending upon the
Action you select.
7. Enter the values for the parameters of the selected action.

For example, enter a value for Issue Type. By default, only the required parameters are displayed. You can add the
optional parameters by using the Add/Remove Parameters property.
8. Save the rule.
Example: Rule to create a JIRA issue by using JIRA connector

The following rule integrates an application with JIRA services. The rule uses the JIRA connector to create a JIRA issue
when a new record instance for a record definition is created. The record definition is a regular definition that consists of
a text field JIRA Issue Key, along with the default fields. To store the issue key of the JIRA issue that is created by using
the rule, the JIRA Issue Key field is mapped to the connector output.
When a new instance of the record definition is created (On Create record event), the rule is triggered and performs the
following tasks:
1. Connector gets input from the Description field of the record instance.
2. Connector creates a new issue in JIRA and the JIRA issue is populated with the details of the Description field of
the record instance.
3. Connector provides the new JIRA issue key as an output and the JIRA issue key is stored in the JIRA Issue Key
field of the record instance.
General properties sample values

The following table illustrates sample values for the General properties in the rule example:

GENERAL
Name Demo Rule
Description Rule to create a JIRA issue
Enabled Selected
RECORD DEFINITIONS
Add/Remove Record Definitions Demo Record (primary record definition)
Rule Applies To Demo Record
Trigger sample values

The following table illustrates sample values for the Trigger element in the rule example:
GENERAL
Trigger Type Record event
Record Event On Create
OPTIONS
Execution Order 500
Connector sample values

The following table illustrates sample values for the Connector element in the rule example:
GENERAL
Label Connector
Connection Name JIRA Configuration
INPUT MAP
Connection JIRA Configuration
OUTPUT MAP
Name JIRA Issue Key
Source Issue Key
Related topics
Troubleshooting integration service connection issues (see page 991)
Rule designer elements (see page 491)

Creating alias mapping of the connectors

You can create connector configurations and perform mapping of aliases. You can export or deploy aliases used in an
application bundle to the production environment. Thus, an alias is created for every tenant in the production
environment.
In the development environment, an alias gets generated when an application bundle gets imported or while saving a
process in the Process or Rule designer.
An alias is a placeholder for a tenant specific configuration. If a tenant has multiple applications, every application will
have a unique alias for a connector action. By using aliases, an administrator can export the applications from one
environment to the other. The tenant database will store all the aliases created for different connector actions.
To map connector action and connector configuration by using an alias
2. Select Configure My Server > Manage Mapping .
3. On the Manage Alias Mapping screen, select an application from the list of applications.
4. Select Connection Target and Connection Configuration from the list. The list has all the Connector Targets
which are created in connector configurations.
For more information about connector configurations, see Adding Connector Configurations (see page 616).
5. Click Save.
Related topics
Enabling automatic record assignment in an application

You can automatically assign the application requests by configuring them in BMC Helix Innovation Studio. This capability
enables you to:
Process the application requests faster, thereby reducing the turnaround time.
For example, configuring a service desk application to automatically assign help desk requests to the correct IT
agents.
Ensure that no request remains unassigned.

Additionally, users are satisfied because their requests are addressed right away.
BMC Helix Innovation Suite uses foundation data to identify the assignees, for example, organization, categorization,
criteria, and location data. According to the assignment rules, the requests are assigned to a group of assignees or an
individual assignee.

To configure automatic assignment of requests, you define the rules for assigning requests in an assignment policy, and
trigger the policy from assignment processes.
How does automatic assignment work

The following workflow provides information about the automatic assignment of requests:
1. You define the rules for assigning requests in an assignment policy, and trigger the policy from assignment
processes.
2. When a request is created, the relevant assignment process get triggered, which calls the assignment policy to
facilitate action on the submitted request.
3. The rules associated with the assignment policy are executed sequentially to select the correct assignee for the
request.
4. If there are multiple assignees, predefined assignment methods configured in the rule are used to identify an
assignee for the request.
The automatic assignment is a two-level process. BMC Helix Innovation Suite first identifies the support group for
assigning the request. If an individual assignee is configured,BMC Helix Innovation Suite identifies an assignee from the
support group and assigns the request to that individual.
For example, if Laptop not working request is created in a Change Request application, BMC Helix Innovation Suite
identifies IT Helpdesk - India as the support group. If an individual assignee is configured, BMC Helix Innovation Suite
assigns the request to IT agent A or IT agent B as per the assignment method.
Methods for assigning requests

If multiple assignees are identified for a request, a specified assignment method is used to identify an assignee. You can
specify any one of the methods for assigning requests to individuals:
Method Description Example
Round robin Assigns the request to the person who has gone the If IT agent A was last assigned a request at 9:00 A.M., and IT agent B
longest since receiving an assignment. was assigned a request at 11:30 A.M., the next request will be assigned
to IT agent A.
Load balancer by Assigns the request to the person who has the fewest If IT agent A is assigned 2 requests and IT agent B is assigned 3
Number number of request assignments. requests, the next request will be assigned to IT agent A.
Load balancer by Assigns the issue to the person who has the lowest If IT agent A has a capacity rating of 10 and is assigned 5 issues, then
Capacity capacity ratio. the capacity ratio is 5/10=0.5 (Assigned issues/Capacity rating=Capacity
ratio).
Similarly, if IT agent B has a capacity rating of 20 and is assigned 8

issues, then the capacity ratio is 8/20=0.4. In this case, person B is
selected because of the lowest capacity ratio.
But if IT agent A and IT agent B have a capacity rating of 10 and are

assigned 10 issues, in this case, the next open issue is assigned to the
person who has gone the longest since receiving an assignment.
Note

For the Load Balance by Number and Load Balance by Capacity assignment methods, one more than one
agent could qualify for a request. In such cases, the assignment occurs according to the sequence in which the
records are fetched; the assignment does not occur in an alphabetical or random order. This sequence is
determined by the sort order on the assignee record definition, if specified; otherwise, the sequence is the
order in which the records are created.
To configure applications to automatically assign requests

The following diagram depicts the stages for configuring applications to automatically assign requests:
The following table describes the details of each of the stages involved in this process:
Task Action Description
1 Define an assignment You can define an assignment policy to specify the sequential rules for autoassigning requests.
policy (see page 625)
The assignment rules are based on foundation data. As per the assignment rules, BMC Helix Innovation Suite identifies
the correct assignee for the request.
2 Define an assignment You can define an assignment process to trigger the assignment policy.
process (see page 629)
Based on the assignment rules, BMC Helix Innovation Suite automatically assigns the request to the correct assignee.
Defining assignment policies to specify rules for assignment
You can define an assignment policy to specify the sequential rules for automatically assigning the application requests.
The assignment rules are based on foundation data, for example, organization, categorization, criteria, and location data.
As per the assignment rules, BMC Helix Innovation Suite identifies and assigns the request to the correct assignee. If
multiple assignees are available, the predefined assignment methods (see page 624) are used to identify an assignee for
the request.
Before you begin

Before you create an assignment policy, ensure that the relevant foundation data is available. For example, if you want to
assign the requests to an individual assignee, ensure that the Person foundation data is available.
To create individual entries of foundation data, see Populating common data elements through Foundation library (see
page 661). For loading foundation data in bulk quantities, see Loading Foundation data in bulk (see page 684).

To create an assignment policy
2. Select Assignment > Assignment Policies.
3. Click New Policy.

The Create New Policy dialog box is displayed.
4. In the Introduce Policy tab, provide the following information:

Field Description
Policy Name, Description Enter a name and short description for the assignment policy.
Status Select to view the status of the assignment policy after it is created, for example, active or inactive status.
Select Record Definition Select the record definition on which the assignment rules must be applied.
Select field for group assignment Select the field that must be used for assigning requests to a group of assignees.
Return code field Stores the code for success or failure of the assignment. This field can be used for debugging purposes.
For example, the return codes such as 0, 1, 2, 3, 4, and 5.
For more information about using return codes for debugging purposes, see Troubleshooting automatic
assignment issues (see page 988).
Enable assignment at individual level Select to enable configuring the assignment at individual level. When enable,BMC Helix Innovation Suite
assigns the request to the support group, and then to the person within the support group.
After you select to enable assignment at individual level, you can specify the assignment method, such as
Round Robin, Load balancer by Number, and Load balancer by Capacity.
Select field for individual assignment Select the field that must be used for assigning requests to an individual assignee. By default,BMC Helix
Innovation Suite uses Person foundation data for assigning requests to individual assignees.
Return Code Description Stores the successful Assignment Rule ID and the Assignment Qualification ID if the assignment was
successful, or an error code if the assignment failed. This field can be used for debugging purposes. For
example, the return code descriptions such as Support group and individual assignee are assigned.
For more information about using return code descriptions for debugging purposes, see Troubleshooting
automatic assignment issues (see page 988) .
The following image shows a completed Introduce Policy tab:

5. Click Next.
6. In the Add/Prioritize Rules tab, create one or multiple assignment rules.

If there are multiple assignment rules, the assignment is performed according to the sequence of the rules.
To create an assignment rule, perform the following tasks:
a. Click New Rule.
b. In the Add/Prioritize Rules tab, provide the following information:

Field Description
Rule Name, Enter a name and short description for the assignment rule.
Description
Select Assignee Select the support group to whom the requests should be automatically assigned to:
Group
i. Click the icon.
ii. From the Support Groups list, click Select beside the support group that you want to assign the requests
to.
Note: You can select only one support group.
iii. Click Save.
Select Assignment Select the method for assigning requests. If multiple assignees are identified for a request, the specified
Method assignment method is used to identify an assignee. For more information, see Methods for assigning requests (see
page 624).
Create Condition Build the expression to create a filter condition. BMC Helix Innovation Suite assigns the request only to the
assignee that matches the condition during runtime.

The following example shows a completed Add/Prioritize Rules tab:
c. To save the assignment rule, click Add.

The newly-created assignment rule is displayed in the Add/Prioritize Rules tab.
d. If you created multiple assignment rules, you can specify the sequential rules for automatically assigning
requests by moving the assignment rule up or down.
7. Click Save to create this policy.

Note
If you do not click Save, the assignment rules are not saved and the assignment policy is not created.
The newly created assignment policy is displayed in the Assignment Policies list. You can then define assignment
processes (see page 629) to trigger the assignment rules.
Related topic
Enabling automatic record assignment in an application (see page 623)
Defining assignment processes to trigger the assignment policies
You can define the assignment processes. When an application request is submitted, the assignment process triggers the
assignment rules to identify the assignee, and automatically assigns the request to the correct assignee.
In BMC Helix Innovation Studio, you can use the Call Assignment Policy element in the Process designer to define an
assignment process.
Before you begin

Before you create an assignment process, ensure that the following actions are completed:
1. The application for which you want to add the assignment process is deployed (see page 813) and can be viewed
in the Workspace area in BMC Helix Innovation Studio.
Ensure that you have specified dependency on the Assignment library in the pom.xml file located in the bundle
project. Otherwise, the Call Assignment Policy element is not displayed in the Process designer of your
application. For more information, see Using components from another developer's Digital Service application or
library (see page 815).
2. The record definition for which you want to add the assignment process is created.
For more information, see Working with record definitions (see page 324).
3. The assignment policy that you want to trigger from the assignment process is created. For more information,
see Defining assignment policies to specify rules for assignment (see page 625).
To create an assignment process
2. Select the application in which you want to use the Call Assignment Policy element.
4.
To add the assignment process to an existing process, click that process.
To create a process and then add the assignment process, click New.
5. (Applicable only for a new process) To enter the process information, click the icon in the Properties pane
on the right side and perform the following actions:
a. Enter the Name and Description of your process.
b. To enable the process, click the Enabled check box.
c. From the Run as list, select a user who should be able to run the process.
d. To add new parameters, click Add/Remove Variables in the Variables section.
e. In the Add/Remove Variables dialog box, click Add Variable and enter the following details:
Field Description
Name
Variable ID Specify a unique ID to identify the variable; this value must be numeric. You can use the variable ID in other processes.
Variable Specify if the variable is an input/output parameter or a local variable. For an input parameter, if you select the Variable Type
Type as Input Required and Data Type as Record, a context key is set automatically.
Process input parameters and output parameters are the interface of a process. When starting a process, data is passed to
the input parameters and when the process is complete, data is received from the output parameters. The only exception is
Record data type.
Description Provide a description that clearly indicates the purpose of the variable.
Data Type From the list, select Record data type and then specify the request record definition that you want to use for automatic
assignment.
f. To add another parameter, click Add Variable and enter details about the parameter.
g. Click Save.
6. To add the assignment process variable, drag the Call Assignment Policy element from the palette onto the
canvas.

7. Select the Assignment Process element, click the icon in the Properties pane on the right side, and specify
the following information:
Field Description
Name
Label Specify a suitable label for the parameter.
Run as Select a user who can run the process according to the permissions inherited from the process or permissions of the selected user
role. For example, if you specify Administrator, only those users that have the administrator permissions can run the assignment
process.
Input map Select the record definition that you selected earlier for the process variable. BMC Helix Innovation Suite performs automatic
assignment on the application that is associated with the record definition.
For information about adding input process variables, see Defining the application business logic through processes (see page 421).
Policy Specify the assignment policy that should be triggered when an application request is submitted.
name
8. Click Save.
The assignment process is created.
To trigger the assignment process by using a rule

To trigger the assignment process, you must create a rule and use the assignment process in the rule.
1. On the Rules tab, click New.

The Trigger element appears on the canvas by default.
2. In the Properties pane, in the General tab, enter the name for the rule.
3. Select the Trigger component > Settings pane and specify the following parameters:
a. From the Trigger Type list, select Record Event.
b.
3.
b. From the Record Event list, select After Create.
4. Select the Process component > Settings pane and specify the following parameters
a. Enter the label for the process.
b. In the Process to Start list, select the assignment process that you want to initiate.
5. Save the rule.
After a record instance is created in the request record definition, BMC Helix Innovation Suite triggers the assignment
process. For more information, see Creating rules (see page 493).
Related topics
Defining assignment policies to specify rules for assignment (see page 625)
Administering
An administrator manages a tenancy, which is a group of customers of SaaS service providers or managed service
providers (MSPs) that share a common access and permissions to a software.
Action Reference
Understand the roles and permissions level for each role. Roles and permissions (see page 743)
Customize the appearance of your applications that suit your organization's branding. Tailoring the application skin and brand (see page
633)
Set up data in your application to create a Foundation business model that can be used by your Setting up Foundation data for custom
applications or load Foundation data in bulk. applications (see page 641)
Address the personal data protection and privacy requirements associated with the General Data Addressing data privacy requests (see page 739)
Protection Regulation (GDPR).
Set up user accounts and grant access to manage and maintain the system. Managing user access and permissions (see page
742)
Configure incoming and outgoing mailboxes, and the steps to create templates. Configuring incoming and outgoing email (see
page 750)
Configure additional FTS settings to refine the search results. Configuring full-text search to refine the search
results (see page 754)
Updating centralized tenant configuration settings to store the tenant's configuration data at a common Updating centralized tenant configuration settings
location that can be accessed across multiple servers. (see page 756)
Assign application licenses to users, so that the users can legally use the application. Assigning application licenses to users (see page
759)
Create deployment packages to deploy codeless applications in development, test, or production Deploying codeless applications (see page 763)
environments.
Upgrade to new version of an application. Consuming a new version of an application (see

page 779)
Submit user reported errors along with the steps that resulted in the error to Customer Support. Submitting user reported issues to BMC
Customer Support (see page 782)

Tailoring the application skin and brand

BMC Helix Innovation Studio enables you to customize the appearance of your Digital Service applications that suit your
organization's branding. Using the Administration tab in BMC Helix Innovation Studio you can do the following
customization:
Configure the skin for an application – Change the appearance of components (such as panels, links, borders, or
text) on a view of an application without having to modify the application.
Configure the logo for an application – Customize the look and feel of the application by uploading the tenant's
brand-related image files and messages.
To configure the skins for applications
2. Select Configure My Server > Skinning and Branding > Define Application Colors.
3. In the right pane, configure the parameters for colors and logo images and save your changes.
The following table provides a list of available parameters for each area:
Area List of Parameters
Inputs
Input Background Color
Input Border Color
Input Text Color
General
Main Background Color
Main Border Color
Main Text Color
Heading Color
Notification
Notification Error Background Color
Notification Info Background Color
Notification Successful Background Color
Notification Text Color
Notification Warning Background Color
Tooltip Background Color
Tooltip Text Color
Buttons
Primary Background Color
Primary Border Color
Primary Button Text Color
Secondary Background Color
Secondary Border Color
Secondary Text Color

Area List of Parameters
Images
Small Logo (against a dark background)
Small Logo (against a light background)
Large Logo (against dark background)
Large Logo (against light background)
Favorites Icon
Panels
Default Panel Background
Default Panel Text Color
Selected Panel Background Color
Selected Panel Text Color
Links
Link Color
Nav Background Color
Nav text color
Nav selected text color
To revert the changes to the default values, click Reset to Default.
Notes
On a shared system, you can manage themes only for your applications and not for all available
applications.
The customizations made by the administrator are applied to all the applications that are added in the
tenancy after the changes are made.
The existing tenants and users are not affected by the customizations.
To add logo images
2. Select Configure My Server > Skinning and Branding > Define Application Colors.
3. In the right pane, in the Images section, upload the logo and click Save. You must use upload only PNG, JPEG, or
SVG images.
Fields Example
Small logo
(against a
dark
background)

Fields Example
Large Logo
(against
dark
background)
Favorites
Icon

Fields Example
After you receive a message that theme is generated, the changes are applied to the logo images.
Embedding BMC Helix Innovation Suite views in external applications

You can now embed BMC Helix Innovation Suite views in external applications that are not running on BMC Helix
Innovation Suite, for example, BMC Digital Workplace Advanced and BMC Remedy with Smart IT are considered external
applications for BMC Helix Innovation Suite. You can embed multiple BMC Helix Innovation Suite views in both cloud and
on-premises applications of BMC Digital Workplace Advanced and BMC Remedy with Smart IT.
Embedding an BMC Helix Innovation Suite view in an external application provides the following benefits:
Leverages BMC Helix Innovation Suite's capabilities in any application that is not running on BMC Helix Innovation
Suite.
Provides seamless navigation to BMC Helix Innovation Suite.

If both the external application and BMC Helix Innovation Suite use Remedy Single Sign-On (Remedy SSO), users
can access the BMC Helix Innovation Suite view without providing the login credentials again.
To embed an BMC Helix Innovation Suite view in an external application, an HTML Inline Frame element (iFrame) which
contains the view is added to a page in the external application. If the embedded view creates or modifies any record
instances, they are created or modified in BMC Helix Innovation Suite. If the embedded view is modified in any way in
BMC Helix Innovation Suite, the changes are visible after the page is refreshed in the external application.
The following image is an example of an BMC Helix Innovation Suite view that is launched from the admin console of
BMC Helix Digital Workplace Advanced:

Workflow to embed BMC Helix Innovation Suite views in external applications

The following table described the actions that a developer and an administrator performs to embed BMC Helix
Innovation Suite view in external applications:
Task Role Product Action Reference
1 Developer or BMC Helix Innovation Studio Create a view in a codeless application or use an To prepare a view for
Application existing view, and customize the view according to external applications (see
business your business requirements. page 638)
analyst
2 Administrator BMC Helix Innovation Studio Add trusted URL of an external application, so that To enable an Innovation
the BMC Helix Innovation Suite view can be loaded Suite view to load in
in the iFrame of an external application. iFrame of external
3 Administrator External application To configure the external

Update the hosts file with tenant Virtual
application to embed BMC
Host Name and map it to the IP address of
Helix Innovation Suite view
BMC Helix Innovation Studio and IP address
(see page 639)
of target RSSO, if required.
Build the URL for accessing the BMC Helix

Innovation Suite view by using JavaScript.
The JavaScript points to BMC Helix
Innovation Suite server and the contains
the BMC Helix Innovation Suite view
properties.

Task Role Product Action Reference
Enable the integration with BMC Helix

Innovation Suite.
Place the BMC Helix Innovation Suite view

on a custom page of the application's
console.
Before you begin

Configure Remedy SSO OAuth 2.0 authentication for both BMC Helix Innovation Suite and your external application, so
that the external application's users are automatically authenticated and do not need to log in separately to access the
embedded View.
For configuration information, see Using authorization REST APIs to consume BMC Remedy Single Sign-On (see page 911
).
To prepare a view for external applications

In a codeless application, create a view or use an existing view and customize it to suit your business needs. The view can
then be embedded in an external application.
2. For a codeless application, create a view or use an existing view.

The view can contain both out-of-the-box view components and custom view components.
For more information about developing codeless applications, see Developing codeless applications (see page 794
).
For more information about creating and customizing views, see Defining the user interface through view
definitions (see page 376).
3. Format the view such that it is consistent with the external application's style.
For more information about customizing the skin and logo of the view, see Tailoring the application skin and
brand (see page 633).
To enable an BMC Helix Innovation Suite view to load in iFrame of external application
Specify the trusted URL of an external application, so that the BMC Helix Innovation Suite view can be loaded in the
iFrame of an external application. You can add multiple external application URLs to permit multiple applications to
contain the embedded views.
2. Select Configure My Server > Innovation Suite > iframe Security.
3. From the iframe Security page, click Add URL, and enter the address of the external application where you want
to embed the BMC Helix Innovation Suite view.
The following are a few examples of acceptable URLs for external applications:
http://host.com, view.host.com:443, https://view.host.com, or http://182.167.1.1 .
Note

Do not include any wildcard character, such as asterisk (*) in the URL.
The following image shows a completed iframe Security page:
4. Click Save.
The BMC Helix Innovation Suite view can now be embedded in the external application. If you modify the embedded view
in BMC Helix Innovation Suite, the changes are available after you refresh the external application's console. Any record
instances that get created by using the BMC Helix Innovation Suite view from the external application are saved in BMC
Helix Innovation Suite.
To configure the external application to embed the BMC Helix Innovation Suite view
External applications use inline frame (iFrame) HTML element to launch the embedded BMC Helix Innovation Suite view,
because out-of-the-box BMC Helix Innovation Studio view components cannot be launched from cross-origin requests.
By using the iFrame HTML element, BMC Helix Innovation Suite communicates with the external application and provides
access to the embedded view.
The external application's administrator must perform the following actions:
1. Update the hosts file with tenant Virtual Host Name and map it to IP address of Innovation Studio and IP address
of target RSSO, if required.
2. Build the URL for accessing the BMC Helix Innovation Suite view by using JavaScript.
The JavaScript points to BMC Helix Innovation Suite server and the contains the BMC Helix Innovation Suite view
properties.
Click here to know the procedure.
a. Create an BMC Helix Innovation Suite URL.

Do not include the Shell navigation items such as the header and navigation, because the external
application has its own header and navigation.
To create the URL, perform the following tasks:
i. In BMC Helix Innovation Studio, navigate to the view that you want to embed.
ii. Copy the URL of the view from the browser.
iii.
iii. Edit the URL by replacing the text view with iview.
For example, URL https://example.on-bmc.com/innovationsuite/index.html#/com.example.
CustomApp/view/com.example.CustomApp:TestRun becomes https://example.on-bmc.com
/innovationsuite/index.html#/com.example.CustomApp/iview/com.example.CustomApp:TestRun
b. Construct the RSSO cross launch URL to use it as the src URL for the iFrame tag. The RSSO cross launch
URL enables you to use RSSO and authenticate the users that currently logged in to the external
application, so that they are not prompted to log in again.
To construct the RSSO cross launch URL, perform the following tasks:
i. Follow the instructions on the RSSO Cross Launch Instructions page to construct the RSSO cross-
launch URL.
ii. Use the BMC Helix Innovation Suite view URL as the goto URL in the RSSO cross-launch URL.
For example, URL https://rsso-cloud-server/rsso/cross-sso?goto=<view-url>#jwt=<jwt> becomes
https://rsso-cloud-server/rsso/cross-sso?goto=https://example.on-bmc.com/innovationsuite/index.
html#/com.example.CustomApp/iview/com.example.CustomApp:TestRun#jwt=<jwt>
3. On the page in the external application to which you want to embed the view, add script tags <script></script>
within the body of the page.
4. Add the following JavaScript code within the open and close script tags:
<iFrame src=<rsso-cross-launch-url> width="200" height="200">
</iFrame>
5. Replace the string <rsso-cross-launch-url> with the RSSO cross-launch URL you just constructed.
6. Enable the BMC Helix Innovation Suite application feature.
7. Place the BMC Helix Innovation Suite view on a custom page of the external application's console.
For information about how to configure the external application for embedding the BMC Helix Innovation Suite view, see
Embedding custom pages from Innovation Suite application .
To remove access to an embedded view

When you remove an external application's URL from the iFrame Security section of the Administration area in BMC
Helix Innovation Studio, the embedded views are no longer visible in the external application.
2. Select Configure My Server > Innovation Suite > iframe Security.
3. From the iframe Security page, click the Cancel icon beside the external application's URL for which you
want to remove the embedded view.
The embedded view is removed from the external application. Ensure that you also remove the custom page of
external application that connects with the BMC Helix Innovation Suite view.
The embedded view is no longer visible in the external application. As a best practice, you must remove the JavaScript
code from the external application's page that contains the iFrame code.

Setting up Foundation data for custom applications

Applications use Foundation data as a source of information about the people in your company and their attributes, such
as organization, location, geography, and other shared characteristics that you might need to categorize. The Foundation
data can be used to drive business processes and rules. It consists of common data elements, such as people,
organization, locations, categorizations, and geography, that can be used by multiple applications in an organization to
satisfy different requirements.
For example, if you use BMC Helix Innovation Studio to create an onboarding application and a service desk application
for your organization, you can use the people and location data elements in both of these applications for different
purposes. You do not need to re-create this data multiple times.
This section provides information on Foundation data concepts and how to load Foundation data in bulk in BMC Helix
Innovation Suite:
1 Understand the concepts of the out-of-the-box data elements in Foundation library.

Foundation data library and data model (see
page 641)
Foundation data reference (see page 643)
2 Create Foundation data one at a time in your custom application by using BMC Helix Creating or modifying Foundation data (see page 661)
Innovation Studio.
3 Load the Foundation data in bulk quantities by using a Data Management Console Loading Foundation data in bulk (see page 684)
application.
4 Load existing Foundation data from BMC Remedy IT Service Management to BMC Helix Loading ITSM Foundation data in bulk (see page 691)
Innovation Suite to expedite the onboarding process.
Foundation data library and data model

BMC Helix Innovation Suite Foundation library provides a Foundation Common Data Model (CDM), also referred to as
Foundation data. The Foundation data model is a way for applications in BMC Helix Innovation Studio to represent
common data elements, such as person, organization, location, categorization, and geography. The Foundation library
uses out-of-the-box data elements along with the extended data elements to store Foundation data . Each data element
is represented by a record definition in the Foundation library.
Foundation record definitions

Foundation data is the data created within the following record definitions and their extended record definitions:
Out-of-the-box record definitions Extended record definitions
Person No extended record definitions
Organization
Primary Organization
Secondary Organization
Business Unit
Department
Support Group
Location

Out-of-the-box record definitions Extended record definitions
Region
Site
Site Area
Categorization
Operational category
Product category
Resolution category
Root Cause
Geography
Country
State/Province/District
City
Postal Code
Time Zones
Note
You cannot delete the out-of-the-box data elements, the fields provided in the out-of-the-box data elements,
and the out-of-the-box association definitions.
When to use the extended Foundation record definitions

The Foundation CDM consists of out-of-the-box record definitions and the extended record definitions that you can use
to build your application.
Best practice
BMC recommends that you use the extended record definitions that are provided in Foundation library.
You should only create an extended record definition for the following situations:
You cannot use a type value to further classify the out-of-the-box data elements.
Example: The Department record definition uses the Type field to distinguish between the business and support
departments.
The new record definition has distinct attributes that cannot be shared with any out-of-the-box data elements.
The data within the extended record definitions will not have to coexist with other extended record definition
from the same base record definition.
You can create new record definitions or create new extended record definitions to suit your business needs. For more
information, see Defining record definitions to store and manage data (see page 324).

Related topic
Foundation data reference

BMC Helix Innovation Suite Foundation data consists of the following data elements:
Person – Represents both users and non-users of an application.
Organization – R epresents a group of people with a particular purpose.
Location – Represents a physical place or site as well as a collection of sites or geographical regions.
Categorization – Represents a means of classifying people or objects who have shared characteristics.
Geography – Represents the geographic location of an organization or person by identifying the country, state,
province, and city. This information is used by Locations data element to represent the physical location of an
organization or person.
The following image succinctly describes the role of each Foundation data element:
This section provides the following topics:
Organization data (see page 644)
Person data (see page 650)
Location data (see page 654)
Categorization data (see page 657)
Geography data (see page 658)

Organization data
Organization data represents a group of people with a common purpose to the business. The first step in creating a
standard data model for your application is to create an organization. Everything else that you create belongs to
organization.
You can include the following examples of information in Organization data:
An internal support organization
An external support provider
A consumer of support services
A manufacturer of products that you use
A supplier of products that you use
A type of contact
Business units
Departments
Supported Organization types

You can specify the following types of organization data in BMC Helix Innovation Suite:
Primary organization
The primary organization consists of organization records that can exist without a parent organization record definition.
The basic function of the primary organization is to define users that use the applications developed on BMC Helix
Innovation Suite. The hierarchy in primary organization is no longer applicable. You cannot inherit and extend primary
organizations. An organization can be defined as multiple of organization, such as customer, partner, and vendor.
Important
You do not need to create separate record definitions for Primary Organization data and its types, such as
Service Provider, Operating organization, Vendor organization, and Manufacturer. The types of Primary
Organization are now stored as the Type field in a single Primary Organization record definition.
The following table describes the types of Primary organizations:
Organization Description Example

type
Holding A holding organization is the parent or umbrella entity. It is a Calbro Global Inc. is the umbrella organization of all its subsidiaries.
Organization logical grouping of other organization types. A holding
organization cannot have persons or secondary
organizations, but can have support groups and child
organizations.
Operating An organization, such as a company that receives services or Calbro Services is one of the operating organizations under Calbro Global Inc.
Organization provides services to its employees.
Customer A business that purchases or subscribes to your services. ABC is a customer of Calbro Services.

Organization Description Example

type
Generic A generic contact is an external reference for an General Cars is a car rental company, which is not a part of Calbro, but is
Contact organizations. It is used to track information anout people in frequently contacted by employees of Calbro for promotions. The employees
that organization. or representatives of General Cars can be associated with an organization of
type generic contact called as General Cars car rental company.
Leasing An organization that provides products, services, or XYZ Securities is a leasing organization that provides security personnel for
employees to another organization. Calbro Services.
Maintenance A maintenance organization provides services to enable its Matters Consultancy is a maintenance organization that provides IT
parent organization to achieve its objectives. maintenance services to Calbro Services.
Manufacturer An organization that manufacturers a product identified in Globex Computers is a manufacturer of IT peripherals that are listed in the
the product catalog. product catalog of Calbro Services.
Out Sourcer A company that provides specialized goods or services to a Optima Services outsources its Accounting-related services to Calbro Services.
usually larger company.
Partner An alliance between one commercial entity and another. Propel Tech is a partner organization of Calbro Services.
Service An organization that is contracted to provide services to an Sheldon Wi-Fi Services is a service provider contracted to provide Wi-Fi
Provider Operating organization. services to Calbro Services.
Supplier An organization that provides products or services to Green Suppliers provides landscaping products and services to Calbro Services
another business entity. .
Vendor An enterprise that contributes goods or services to another Vehement Foods is a vendor organization to provide office meals to the
business entity. employees of Calbro Services.
Secondary organization
The basic function of the secondary organization is to define the different types of organizations, such as a business unit,
department, or support groups. A secondary organization exists only with a direct association to a parent organization. A
secondary organization must have a direct association, which means the secondary organization is associated to one
parent organization. Foundation library supports the following secondary organizations:
Organization Description
type
Business Stores organization records that are subordinate to primary organization records. A Business Unit s hould always be at the top of a Secondary
Unit organization model hierarchy.
The Business Unit is further classified into the following types:
Accounting
Marketing
Production
Sales
Research and Development
Support
Other
Department Stores organization records that are subordinate to primary organization records or other secondary organization records. A Department s
hould always be at the middle of a Secondary organization model hierarchy.
The Department is further classified into the following types:
Support
Business

Support Stores organization records that are subordinate to other secondary organization records specifically for assignment and notification. A
Groups Support Group s hould always be at the bottom of a Secondary organization model hierarchy.
The Support Groups is further classified in to following types:
Service Desk
Engineering
Line of business
Level 1
Level 2
Level 3
Other
For each organization, you must create the following data:
Person
Location
Support groups
Organization data associations

You can leverage the organization data and its association definitions to form a data model for your application. The
Organization record definition stores data related to an organization that includes the support organization, service
provider, the consumer of those support services, a manufacturer of products that you use, a supplier of those products,
departments within an organization, or another type of contact.
After you create all the foundation data elements—organization, person, location, categorization, and geography—you
can associate the organization data with other types of organizations or other foundation data elements.
Supported associations for Organization data

You can associate Organization data with only specific Foundation data elements. The following table describes the
associations that are supported for Organization data:
Supported association Description
Organization to Creates hierarchy within an organization from the top-level organization to the smallest unit in the organization.
Organization
Examples:
The Service Provider organization Calbro Services consists of business units such as Sales and Marketing and Technical
support.

The departments Data Center Support and Network and Communications Management are a part of the Research and
Development business unit.
Primary organization Creates a relationship between a Primary organization of one type and another Primary organization of another type.
supports Primary
Example: The Primary organization of type Service Provider Calbro Services supports the ABC, CBS, and NBC primary
organization
organizations of the type operating organization.
Location to Organization Creates a relationship between the organization record and the site where the organization is located.
For example, Global Operations and Support are departments in Calbro Services that are located at Operations Headquarters.

Person to Primary Creates a relationship between a Person of any type and a Primary organization of any type (except Global organization).
organization Persons associated to a Primary organization type get access to data of that primary organization type.
Example: Maria, Clint, and Nick are employees of the Operating Organization Calbro Services.
Whereas, Tony, Steve, and Bruce are employed by a Primary organization of type Vendor ABC.
Person to Secondary Creates an indirect affiliation between a person and a support organization, such as Support Groups, and provides access to the
Organization data of the support organization. This association implies that the associated person does not work or report to the manager of
the support organization but does perform tasks for that support organization.
Example: The support agents Tony and Clint are members associated with Field Operations Support Group and perform the
tasks required for Field Operations.

Primary organization of Creates a relationship between the Primary organization of type Vendor or Manufacturer that will be used by another type of
one type uses Primary Primary organization.
organization of another
type Example: The Primary organization of type Vendor ABC provides services to the Primary organization of type Operating
Organizations CBS and NBS.
Primary Organization uses Creates a relationship between the categories that will be used by the organization.
Categorization
Example: The Primary organization of type Service Provider Calbro Services uses products like Hardware, Software, and Services
.
Related topics
Creating or modifying Foundation data (see page 661)
Creating or modifying Organization data (see page 662)

Person data
Person data defines the data for users and non-users of your application. Application users require a login ID,
permissions, and licenses, such as Employees, and they must belong to an organization. The non-users, such as Customer
and Vendor, are people that work for your company or who would require services or render services to your
organization.
The first step in creating a standard data model is to create an organization. Everything else that you create belongs to
organization. For more information about organizations, see Organization data (see page 644).
Important
You do not need to create separate record definitions for Person data and its types, such as Employee, Agents,
Customer, and Vendor. The types of Person data are now stored as a Type field in a single Person record
definition.
BMC Helix Innovation Suite enables you to create data for the following out-of-the-box Person types:
Person type Description
Employee Represents an employee of the organization. An Employee is further classified into following types:
Contractor
Ex-Employee
Full time
Part time
Pre-Starter
Retiree
Other Employee Type
Agents Represents the support staff that provides service to other employees or customers.
Customer Represents a person for whom a service is offered. A Customer is further classified into following types:
Existing
Prospect
Other
Vendor Represents a person or a company that offers services. A Vendor is further classified into following types:
Partner
Supplier
You can use the out-of-the-box Person types or c reate new Person Type (see page 668) .
Supported Person data associations

You can leverage the person data and its associations to form a data model for your application. The Person record
definition stores data for employees, agents, vendors, or customers. After you create all the Foundation data elements—
organization, person, location, categorization, and geography, you can associate the person data with other types of
Foundation data elements.

The following table provides a list of all the supported associations for Person data:
Supported Description
association
Person to Creates a relationship between a person and their home address.

Home
Example:
Address
Nick is an employee residing at 123 Main Street.
Person to Creates a relationship between a person and the primary location or address where the person works.
Primary Site
Example:
Maria and Nick are employees of Calbro Services, which is located at Calbro Services' primary site, Data Centre.
Person to Creates a relationship between a person and a secondary organization, such as a business unit, support group, or a department in which the
Secondary person works.
Organization
Examples:
Maria and Clint are employees of Calbro Services, and they work for the Sales business unit.
Nick and Phil are employees of Calbro Services, and they work in the Global Operations department.

association
Steve and Tony are employees of Calbro Services in the Customer Support group.
Person to Creates an indirect affiliation between person and support organization such as Support Groups, and provides access to the data belonging to the
Associate support organization. This association implies that the associated person is not an employee, or report to the manager of the support organization
Secondary but does perform tasks for that support organization.
Organization
Example:
Agents Tony and Clint are members associated to Field Operations and perform Field Operations tasks.
Manager to Creates a person-to-person relationship. The Person can be of type employee, vendor, agent, or a customer.
Person
Examples:
Mary, Phil, and Maria are employees working for an organization, and Mary is the manager for Phil and Maria.

association
Similarly, Tony and Clint are agents working for an organization, and Tony is the manager for Clint.
Person to Creates a relationship between a person and the primary organization the person is employed.
Primary
Example:
Organization
Maria, Clint, and Nick are employees working for Calbro Services.
Related topics
Creating or modifying Person data (see page 664)

Location data
Location data represents an organization's physical and logical locations.
A physical location represents a site with a physical address or a geographical region. For example, both an office building
or warehouse are considered physical locations because they have an address. The East Coast and West Coast of the
United States are also considered as physical locations because they represent geographical regions.
A logical location represents an area that has meaning to the business. For example, the Western Sales Region and the
Eastern Sales Region. This location provides a meaning to the business where the boundaries are clearly defined only to
the business.
You can specify different types of locations, such as the following, when you create a location or import an existing
location data:
Location types Description
Region Represents both physical and logical areas. An organization can have several regions, depending on how many sites it has and where the sites
are located.
For example, Pacific, Northwest.
Site Stores the physical address for an organization. The Site record definition is further classified in to the following types:
Business
Residential
Site Area Contains a direct association to a Site and is used to further categorize a Site to the following areas:
Desk
Office
Gates
Supported Location data associations

The following table describes the supported associations for Location data:
Type of Description
association
Region to This association creates a relationship between regions. This association defines a parent-child hierarchy within the regions.
Region
Example:
East Coast, West Coast, and Central are the regions available under the parent region North America.

Type of Description
association
Region to This association creates a relationship between Region and Site where multiple sites can be located in a single region.
Site
Example:
Calbro Services headquarters and the Bay Area Sales site are located in the Pacific region.
Site to Site This association creates a relationship between Site and Site Area to further categorize a Site.
Area
Example:
The site Data Center consists of multiple areas such as North Gate A and South Gate B.
Location to This association creates a relationship between the organization record and the site where the organization is located.
Organization
Example:

Type of Description
association
Global Operations and Support are departments in Calbro Services that are located at the Operations Headquarters site.
Person to This association creates a relationship between the people record and the primary location or address of the organization where the person is working.
Primary Site
Example:
Maria and Nick are employees working for the Holding organization which is located at Data Center.
Person to This association defines a relationship between a person record and home address of the person.
Home
Example:
Address
Nick is an employee residing at 123 Main Street.

Type of Description
association
Related topics
Creating or modifying Location data (see page 668)
Categorization data
Categorization data classifies and organizes sets of common items, such as, configuration items, support tickets, incident
requests, or change requests.
BMC Helix Innovation Suite supports the following types of categorizations:
Categorization type Description
Operational Represents all the operational services that are provided by an organization.
Categories
Example: Adding a user account, changing a server password, application failure, network failure, and so on.
Product Categories Represents all of an organization's products. Each product category must be unique.
Example: Email, Skype for business, intranet, and so on.
Resolution Represents the determining factor used to resolve or complete ticketing records.
Categories
Example: Sending a knowledge document, assigning an agent to work on the issue, assigning permissions, and so on.
Root Cause Represents the root cause of the ticketing record.

Categories
Example: A ticket is created for an unresponsive email server. However, the root cause of this could be insufficient disk memory on the
email server.
Supported Categorization data associations

The following table describes the supported associations for Categorization data:
Type of Description
association
This association creates a relationship in which a category is associated to itself. This association creates a parent-child type of relationship. The
categorization record can be operational, product, resolution, or root cause.

Type of Description
association
Categorization Example:
to
Categorization Smart Phone, Tablet are product types of a parent product category Mobile Device.
Organization This association is used to identify which categories will be used by the Primary Organization. This association provides a list of categories to a user of
uses an application which is related to a given Primary Organization.
Categorization
Example:
The Service Provider Calbro Services uses product, such as Hardware, Software, and Services.
Related topics
Creating or modifying Categorization data (see page 669)
Geography data
Geography data defines the location of your organization or person by identifying the country, state, province, city, and
time zone.

BMC Helix Innovation Suite provides sample geography data in template Microsoft Excel spreadsheets. You can can
access the sample Geography data from the Data Management Console, load the data in bulk quantities, and use it to
capture the physical location of your sites. For more information, see Loading Foundation data in bulk (see page 684).
BMC Helix Innovation Suite supports the following types of geography:
Geography types Description
Country Stores the details of the country for an organization or person.
State/Province/District Stores the details of the state/province/district for an existing country record.
City Stores the details of the city for an existing country or state/province/district record.
Postal Codes Stores the details of the postal codes for an existing city record.
Time Zones Stores the details of all available time zones.
Geography data associations

The following table describes the supported associations for Geography data:
Type of Description
association
Country to This association creates a relationship in which a geographic location is associated to itself. This association creates a parent-child type of relationship.
State The geography record can be a country, city, state/province/district, postal code, or time zone.
/Province
Example:
/District
A country record United States consists of geographic State/Province/District, such as California, Florida, and Texas.
State This association creates a relationship between the state/province/district and the city present in that state/province/district.
/Province
Example:
/District to
City The State/Province/District record of California consist of city record, such as San Francisco, Los Angeles, and San Diego.

Type of Description
association
City to This association creates a relationship between the city and postal codes of the city.
Postal
Example:
Codes
City record San Francisco consists of Postal Codes, such as 94101, 94102, and 94103.
City to This association creates a relationship between city and its related time zone.
Time Zone
Example:
City record San Francisco is in the Pacific Standard Time zone.

Related topics
Creating or modifying Geography data (see page 671)
Filtering Foundation data by domain

BMC Helix Innovation Studio enables you to filter the Foundation data by defining Domain data tags.
A domain tag is a label that you associate with different types of Foundation data. The domain tag determines to which
domain the Foundation data belongs. For example, you can add HR domain tag for HR-related data and IT domain tag for
Hardware-related data.
You can use domain data tags to perform the following tasks:
Control visibility and filter Foundation data within your applications.

For example, in your HR services application, you can apply HR domain tag to HR support groups, incident
requests, or support tickets to retrieve and show data related to HR only.
Skip unwanted data and use only the relevant data for your application.
Search in your application for data related to one domain.
You can use domain tags to label only the Organization, Categorization, and Location data.
To create domain data tags
2. Select Foundation Data > Domain Data Tags.
3. On the Domain Tag Registry page, click Add.
4. On the Create Domain Tag page, enter the information for the following fields:
Field Description
Domain Tag Name of the domain tag.
Bundle ID Select the application for which you want to create the domain data tags.
5. Click Save.
To apply the domain data tags to the Foundation data, select the tags from the Domain Tag field while creating
Foundation data.

Creating or modifying Foundation data elements (see page 661)
Creating or modifying Foundation data

As an administrator, you can build the Foundation data in your custom applications by using any of the following
methods:

Create individual Foundation data
Load Foundation data in bulk
Load existing Foundation data from Remedy ITSM
To know about the Foundation data library, data model, and different types of Foundation data, see Foundation data
library and data model (see page 641).
This section provides information about how to create individual data elements of Foundation data in BMC Helix
Innovation Suite:
1 Define Organization data to represent a collection of people with a common purpose specific to Creating or modifying Organization data (see
the business and to support requirements. page 662)
2 Define Person data to represent an employee, an agent, a customer, or a vendor. Creating or modifying Person data (see page 664
)
The Person data also includes information about the person, such as their company and
organization, site, contact information, roles, login information, and permissions.
3 Define Location data to represent an organization's physical such as office building or Creating or modifying Location data (see page
warehouse, or logical location such as sales region. 668)
4 Define Categorization data to classify and organize sets of common items, such as, configuration Creating or modifying Categorization data (see
items, support tickets, incident requests, change requests. page 669)
5 Define Geography data to represent the physical location of your sites by identifying the Creating or modifying Geography data (see page
country, state or province, and city. 671)
6 Define Foundation associations to manage relationships between data in the Foundation library. Creating or modifying Foundation data
associations (see page 673)
Related topics
Setting up Foundation data for custom applications (see page 641)
Loading Foundation data in bulk (see page 684)
Loading existing Foundation data from Remedy ITSM (see page 691)
Creating or modifying Organization data

Organization data represents a group of people with a common purpose specific to a business. The first step in creating
a standard data model for your application is to create an organization. Everything else that you create in the data model
belongs to the organization. In BMC Helix Innovation SuiteFoundation library, you can create primary organizations and
sub-organizations or secondary organizations. For more information about the types of Organization data, see
Organization data (see page 644).
To create a primary organization
2. Select Foundation Data > Manage Organizations > Primary Organizations and click New.
The following image shows the navigation to create a new primary organization:

2.
3. To create primary organization, on the New Primary Organization page, in the General tab, fill out the following
fields:
a. In Organization Name, provide a meaningful name for the organization.
b. From the Primary organization type list, select the types that the primary organization belongs to. You
cannot create new types of primary organizations.
c. From the Status list, set the status for the organization. This indicates the organization's activity level,
such as Enabled or Obsolete.
d. In the Notification Email List field, enter a semi colon -s eparated list of email addresses.
e. From the Domain tag list, select the domain-specific tags for your organizations. This restricts the
organization data to the specified domains. For more information about domain tags, see Filtering
Foundation data by domain (see page 661).
4. (Optional) In the Other Details tab, fill out the required fields.
5. Click Save.
To create a secondary organization

After creating primary organization, you can create secondary organizations that are business units, departments, or
support groups. You cannot create new types of secondary organizations.
2. Select Foundation Data > Primary Organizations.
3. Select the primary organization for which you want to create secondary organizations.
4. On the Edit Organization page, click Advanced.

4.
5. On the Child Organizations tab, select the appropriate type of secondary organization: New Child Business Unit,
New Child Department, or New Child Support Group.
6. Flll out the fields for the secondary organization type.
7. Click Save.
The Organization data is created. You can proceed to create other Foundation data elements such as Person,
Categorization, Location, and Geography.
Related topics
Creating or modifying Foundation data associations (see page 673)
Creating or modifying Person data

In Foundation library, you create data for various person types, such as employee, agent, customer, and vendor. You can
also create new person types and add data for the new person types. For more information about the types of Person
data, see Person data (see page 650).
Before you begin

Ensure that you have added Organization data. For more information, see Creating or modifying Organization data (see
page 662).
To create Person data
2. Select Foundation Data > Manage People, and click New.

2.
3. To add a new person data, enter information in the appropriate fields.

General
Person Select the type of person for Employee

Type which you want to enter the
data, such as Employee,
Customer, or Vendor.
Note: You can use the out-of-
the-box Person types or create a
new Person type. To create a
new Person type, see Create
new Person Type (see page 668)
.
Employee Select the type of employee you Full time

Type want to add, such as Contractor,
Part-time, and so on.
the-box employee types or
create a new employee type. To
create a new employee type, see
Create new Person Type (see
page 668).
Customer Select the type of customer that Existing

Type you want to add, such as
Existing, Prospect, and Other.
the-box customer types or
create a new customer type. To
create a new customer type, see
Create new Person Type (see
page 668).
Vendor Select the type of vendor that Partner

Type you want to add, such as Partner
or Supplier.
the-box vendor types or create a
new vendor type. To create a

new vendor type, see Create

new Person Type (see page 668)
.
Agent Select Yes if you want to mark Yes

the person as an Agent.
Access Details
Functional Select a functional role based on

FoundationRead
Roles the roles provided to the user in
your application. For more Unrestricted Access
information about functional
roles, see Functional role (see
page 45).
Application Select the application licenses InnovationSuite User Named

Licenses that should be assigned to the
user to view the required
applications. The list displays all
the licensed applications.
Tenant Select the toggle to specify the

Admin user as an administrator. Only if
you are an administrator you
can access BMC Helix Innovation
Studio. All the other users have
access only to the applications if
they are assigned specific
application licenses.
Note: The Application Business
Analyst option is removed when
you select this option.
Application Select the toggle to specify the

Business user as a business analyst . An
Analyst Application Business Analyst
customizes application as per
business requirements. For
more information about
Application Business Analyst, see
User goals and features (see
page 275).
Notes:
You will be able to select

Business Analyst , only if
you do not select Tenant
Admin for a user.
If you select Application

Business Analyst ensure
that you select BMC
Helix Innovation Suite
User Named licenses
from Application Licenses
field.
Bundle
Access

After you select the Application

Business Analyst toggle, select all
application bundles that the
Application Business Analyst
should view or modify.
Other Details (The fields in this section indicate a person's attribute. An application built on BMC Helix Innovation Suite can derive values from these
fields.)
PIN Create a Personal Identification

Number (PIN) value for a
requester's authentication and
validation. A PIN value can be
alphanumeric with a maximum
length of 30 characters. For
more information about how a
PIN is validated, Validating and
verifying a PIN value (see page
486) .
VIP Select Yes to mark the person as Yes

VIP. This field is used by the
support agents while attending
the tickets to check if the person
is VIP and expedite the process
of the ticket.
Sensitivity Select the option to mark the Standard

person as VIP. This field is used
by the support agents while
attending the tickets to check if
the person is VIP and expedite
the process of the ticket.
Notification Select the language for English (United States)

Language notifications that are sent to the
user.
Assignment Configuration (The fields in this section are for Person of type Agent and are used by Assignment Engine to manage assignments.)
Assignment Select Yes based on an agent's Yes

Availability availability to take up a new
assignment.
Number Add the maximum number of 5

Assigned tickets that should be assigned
to an agent.
Capacity Add the capacity of an agent 10

Rating based on which a new
assignment can be allocated to
the agent.
Last Ticket Maintain a record of when an

Assign agent was assigned the last task
Time or case.

4. Click Save.
To create a new Person type

When creating Person data, you can use the out-of-the-box Person types or define your own. To define new person
types, perform the following steps:
2. Select Foundation Data > Define Menu Items.
3. To create a new Person type, click Add, and enter the information in the following fields:
Field Description
Menu Type Enter the new menu type that you want to create, or enter an existing menu type for which you want to create a sub-type. For
example, you want to create a new sub-type Intern for Person data of type employee.
Localized Click Localize, and in the Value field, enter the name of the new menu type that you want to create.
Menu Item
Status Set the activity level for the menu type, such as Enabled or Obsolete.
Short Enter details for the new menu type.

Description
Bundle Id Select the application for which you want to create the new menu type.
4. Click Save.
After you create a new Person type, the details are visible under the Person Type menu in the Create Person
page.
The Person data is created. You can proceed to create other Foundation data elements such as Organization,
Categorization, Location, and Geography.
Related topics
Creating or modifying Location data

Create Location data (see page 654) to represent an organization's physical such as office building or warehouse, or
logical location such as sales region. The Location data is further extended to a Region, Site, and Site Area. Location data
represents an organization's physical and logical locations.
To create Location data
2. Select Foundation Data > Manage Locations and perform the following steps based on the location you want to
create:
Task Action
To create
Region a. Select Region, click New, and enter information in the appropriate fields:

i.
a.
Task Action
i. In Region Name, provide a meaningful name for the organization.
ii. From the Region Type list, select the types that the primary organization belongs to. You cannot create new types
of primary organizations.
iii. From the Status list, set the status for the organization. This indicates the organization's activity level, such as
Enabled or Obsolete.
iv. From the Domain tag list, select the domain-specific tags for your organizations. This restricts the organization
data to the specified domains.
b. Click Save.
To create Site
a. Select Sites, click New, and enter information in the appropriate fields:
i. In Site Name, provide a meaningful name for the organization.
ii. From the Site Type list, select the types that the primary organization belongs to. You cannot create new types of
primary organizations.
iv. From the Domain tag list, select the domain-specific tags for your organizations. This restricts the organization
data to the specified domains.
b. Click Save.
To create Site
Area a. Select Sites.
b. From Manage sites page select the Site for which you want to create site area, click New Site Area, and enter information
in the following fields:
i. In Site Area Name, provide a meaningful name for the organization.
ii. From the Site Area Type list, select the types that the primary organization belongs to.
c. Click Save.
Related topics
Creating or modifying Categorization data

Categorization data (see page 657) classifies and organizes sets of common items, such as, configuration items, support
tickets, incident requests, change requests.

To create Categorization data
2. Select Foundation Data > Manage Categorizations and perform the following steps based on the categorization
type:
Task Action
To create Operational
Categories a. Select Operational Categories, click New, and enter information in the appropriate fields:
i. In Operational Category Name, click Localize, and in the Value field, enter the name of the new operational
category that you want to create.
ii. From the Status list, set the status for the category. This indicates the category's activity level, such as
iii. From the Domain tag list, select the domain-specific tags for your operational category. This restricts the
categorization data to the specified domains.
b. Click Save.
To create Product
Categories a. Select Product Categories, click New, and enter information in the appropriate fields:
i. In Product Category Name, click Localize, and in the Value field, enter the name of the new product
ii. From the Status list, set the status for the product category. This indicates the product category's activity
level, such as Enabled or Obsolete.
iii. Select the Visible to All Organizations toggle to make the product category accessible in all organizations.
iv. From the Domain tag list, select the domain-specific tags for your product category. This restricts the
b. Click Save.
To create Resolution
Categories a. Select Resolution Categories, click New, and enter information in the appropriate fields:
i. In Resolution Category Name, click Localize, and in the Value field, enter the name of the new product
ii. From the Status list, set the status for the resolution category. This indicates the resolution category's
activity level, such as Enabled or Obsolete.
iii. Select the Visible to All Organizations toggle to make the resolution category accessible in all
organizations.
iv. From the Domain tag list, select the domain-specific tags for your resolution category. This restricts the
b. Click Save.
To create Root Cause

Categories a. Select Root Cause Categories, click New, and enter information in the appropriate fields:

i.
a.
Task Action
i. In Root Cause Category Name, click Localize, and in the Value field, enter the name of the new root cause
ii. From the Status list, set the status for the root cause category. This indicates the root cause category's
activity level, such as Enabled or Obsolete.
iii. Select the Visible to All Organizations toggle to make the root cause category accessible in all
organizations.
iv. From the Domain tag list, select the domain-specific tags for your root cause category. This restricts the
b. Click Save.
Related topics
Creating or modifying Geography data

The geographic data defines the physical location of your sites by identifying the country, state or province, and city. You
can use the Geography data (see page 658) to create a Foundation business model that can be used by the Digital
Service applications. You can extend the Geography data to create the following Geography types:
Country
City
Postal Code
States/Province/District
Time Zone
BMC Helix Innovation Suite provides out-of-the-box (OOTB) Geography data in the Foundation data . You can use the
OOTB Geography data in your application or create Geography data as per your application requirements.
Out-of-the-box Geography data

BMC Helix Innovation Suite provides OOTB Geography data for Countries and States/Province. You can use the OOTB
Geography data in your applications, so that you do not need to manually create the data. You can also modify or delete
the OOTB Geography data as per your requirements.
BMC Helix Innovation Suite provides prepopulated City data in Excel spreadsheets that you can use to load the City
Foundation data. Both world city data and sample city data are provided, to minimize the impact of loading data. You can
use the required spreadsheet and remove the city data that are not required for your organization. For more information
about the City Excel spreadsheets, see Downloading the template Excel spreadsheets (see page 685).
For information on how to handle the Geography data created by using an earlier version of BMC Helix Innovation Suite
SDK , see Handling Geography data created on an earlier version (see page )

To create Geography data
2. Select Foundation Data > Manage Geography.
3. Select the appropriate geography type: Countries, State/Province/District, Cities, Postal Codes, or Time Zones.
4. Perform the following tasks based on your preferences:
Note
It is important that you create a Country before you create a State, City, or Postal Code.
a. To create a State/Province/District:
i. Navigate to Foundation Data > Manage Geography > Countries.
ii. From Manage Countries, select the country for which you want to create a State/Province/District,
and then click New State/Province/District.
b. To create a City:
i. Navigate to Foundation Data > Manage Geography > Countries.
ii. On the Manage Countries UI select the country for which you want to create a City, and click New
Cities.
Note: This creates a city without a state, province, or a district. To create a city with a state,
navigate to Foundation Data > Manage Geography > State/Province/District and then select the
state for which you want to create a city.
c. To create a Postal Code:
i. Navigate to Foundation Data > Manage Geography > City.
ii. From Manage Countries, select the city for which you want to create a postal code, and click New
Postal Codes.
d. Click New to create a record instance and enter information in the appropriate fields.
5. Click Save.
Handling Geography data created on an earlier version

After you upgrade BMC Helix Innovation Suite SDK to version 17.5.0, to avoid conflicts with the previous Geography data
(created using an earlier version of BMC Helix Innovation Suite SDK) and the new OOTB Geography data, the previous
Geography data is renamed.

For example, if you have created a country Canada and a child province Ontario, by using an earlier version of BMC Helix
Innovation Suite SDK. After you upgrade BMC Helix Innovation Suite SDK to version 17.5.0, Canada is renamed as
Canada_OLD and Ontario is renamed as Ontario_OLD.
If you have such Geography data in your applications (as associations, named lists, and so on), perform the workaround
depending on the following criteria:
Criteria Workaround
If you want to bundle the Geography data with your Correct the Geography data.
application
For example, in the named list of the data record, select the out-of-the-box value of Canada to
replace Canada_OLD.
If you do not want to bundle the Geography data with No changes required.
your application
Related topics
Creating or modifying Foundation data associations

An association allows you to define and manage relationships between data elements in the Foundation library. In the
Foundation CDM, BMC Helix Innovation Suite provides out-of-the-box associations that you can use for your data model,
or you can create new associations to support your data model.
You can define a data model for an application by using association definitions. These association definitions are created
by associating two records with association roles.
For example, the Organization model is defined by creating following associations:

The Support Group Applications Support is associated to the Department Data Center Support.
Similarly the Department Data Center Support is part of the Business Unit Research and Development.
And the Business Unit Research and Development is associated to the Operating Organization Calbro Services.
An association can be of following types:
Direct association
A direct association is a direct relationship between two records, such as one-to-one or one-to-many relationships.
Multiple fields of one record and multiple fields of other records can be a part of the association. Use this association
whenever there is a parent-child type of relationship; for example, Vendor Organization to Business Unit association is an
example of a direct association.
If you delete a parent record with the Cascade Delete flag set to True, the child records are automatically deleted also. If
you delete the parent records with the Cascade Delete flag set to False, the child records are not deleted; however, the
foreign key in child records is set to NULL.
Indirect association
An indirect association defines an indirect relationship between two records in an association; the records can be related
to each other by using a third record in many-to-many relationship. Use this association to define a peer relationship or a
loose relationship, such as an Employee to Department association is an example of a indirect association.

Self association
A self association defines a relationship in which a self record definition is associated to itself. The relationship can be
direct or indirect. In an Employee to Manager association, a manager belongs to the manager role and also to an
employee role.
For more information on creating associations, see Creating record associations (see page 342).
The following topics explain how to create associations for Foundation data:
Associating Organization data with other types of Foundation data (see page 675)
Associating Person data with other types of Foundation data (see page 677)
Associating Location data with other types of Foundation data (see page 679)
Associating Categorization data with other types of Foundation data (see page 681)
Associating Geography data with other types of Foundation data (see page 682)
Related topic
Foundation data library and data model (see page 641)
Associating Organization data with other types of Foundation data

You can leverage the organization data and its association definitions to form a data model for your application. The
Organization record definition stores data related to an organization such as the support organization, service provider,
the consumer of those support services, a manufacturer of products that you use, a supplier of those products,
departments within an organization, or another type of contact.
You can associate the organization data with other types of organizations or other foundation data.
Before you begin
Ensure that you have created all the Foundation data elements: Organization, Person, Location, Categorization,
and Geography. For more information, see Creating or modifying Foundation data (see page 661).
Review the supported associations (see page 646) for Organization data.
To associate Organization data
2. Select Foundation Data > Manage Organizations.
3. Select the Organization Name for which you want to create associations.
4. On the Edit Organization page, click Advanced.
Note
Only supported associations for the selected Organization type are displayed.

5. Associate the Organization data by performing the steps indicated in the following table:
Association Steps
Organization with People (If you want to associate an organization with

employees or support agents). a. Click People.
i. (If you want to associate the organization with

employees) On the Employed By tab, select Add.
ii. (If you want to associate the organization with

support agents) Click the Supporting Agents tab
and click Add.
b. From the list of employees or agents, select the check box

corresponding the employees or customers that you
want to associate the organization with.
You can select only one check box at a time.
c. Click Select.
d. Click Cancel.
Organization with Categories (Out of all the categories that you have, if you
want to associate specific categories to this organization. The list of tier 1 a. Click Categories and click Add.
categories are listed. When you associate an organization with tier 1 category,
all child tier categories are visible in that organization). b. From the list of catgeories, select the check box
corresponding the category that you want to associate
with the organization.
c. Click Select.
d. Click Cancel.
Organization with Sites (If you want to associate multiple sites created as a
location of this organization). a. Click Sites and click Add.
b. From the list of sites, select the check box corresponding

the site that you want to associate the organization with.
c. Click Select.
d. Click Cancel.
Organization with Vendors and Manufacturers (If you want to associate

vendors or manufacturers for this organization) a. Click Associated Organizations and click Add.
b. From the list of vendors or manufacturers, select the

check box corresponding to the vendor or manufacturer
that you want to associate with the organization.
c. Click Select.
d. Click Cancel.
6. Click Close.

The Organization data model is now ready. You can proceed with creating associating Person, Categorization, Location,
and Geography data.
Related topics
Leveraging Remedy ITSM Foundation data (see page 278)
Associating Person data with other types of Foundation data

Each employee, vendor, or customer that is stored as Person data can perform different roles, report to different people
in an organization, and reside in different geographic locations. To create a data model for your application, it is
important that you associate the people data with its corresponding organization, location, or geographic data.
Foundation library provides a list of associations to create a relationship between the available Foundation data.
Before you begin
Review the supported associations (see page 650) for Person data.
To create associations for Person data
2. Click Foundation Data > Manage People .
3. Select the Person data for which you want to create associations.
4. To associate a person with a location, on the Edit Person page, click Basic > Locations and perform the following
steps:
a. From Primary Sites, click Associate, and select the primary sites that you want to associate with the
Person.
b. From Secondary Sites, click Associate, and select the secondary sites that you want to associate with the
Person.
c. From Home Address, click Associate, and select the address that you want to associate with the Person.
or click Create New to create new address and then associate with the Person.
d. Click Close.
5. To associate person with business units, department, organizations, or support groups, on the Edit Person page,
click Advanced and perform steps indicated in the following table:
Association Description Steps
Person with Business Units or

Departments a. Click Business Units.

If you want to create an b. To add new business units, click Add Business Units, and select the business
association between units that you want to associate with the person.
person and business units
or departments. c. To add new department, click Add Departments, and select the
departments you want to associate with the person.
d. Click Select
e. Click Close.
Person with Employees If you want to create an

association between a. Click Employees.
persons, such that the
associated person is the b. To add new employees, click Add, select the employees you want to add,
manager of the selected and click Select.
employees. You can select only one check box at a time.
c. Select the employees you want to associate with the person.
d. Click Close.
Person with Organization If you want to create an

association between a. Click Associated Organizations.
person and organization,
such that the associated b. From the Supported Organizations tab, select the organizations that the
person does not mahas person can access.
access to specific data of
the organization. c. To add new organizations, click Add, and select the organization.
d. Click Close.
If you want to create an

association between a. Click Associated Organizations.
such that the associated b. From the Managed Organizations tab, select the organizations that the
person is the manager of person can manage.
the selected organization.
c. To add new organizations, click Add, and select the organization.
d. Click Close.
Person to Support groups If you want to create a

direct affiliation between a. Click Support.
such that the associated b. From the Support Members tab, select the organizations that you want to
person works for, or associate with the person.
reports to the manager of
the organization and c. To add new departments, click Add Departments, and select the
performs task for that organization.
organization.
d. To add new support groups, click Add Support Groups, and select the
organization.
e. Click Close.

Person to associated Support If you want to create an

group indirect affiliation between a. Click Support.
such that the associated b. From the Associated Support Members tab, select the support
person does not work for, organizations with which the person is associated.
or reports to the manager
of the organization but c. To add new organizations, click Add, and select the organization.
performs task for support
organization. d. Click Close.
6. Click Save.
The Person data model is now ready. You can proceed with creating associations for Organization, Categorization,
Location, and Geography data.
Related topics
Associating Location data with other types of Foundation data

The Location record definition stores the physical and logical location for an organization. The Foundation library
provides a list of associations that helps to define relationships between the organization, different locations of the
organization, and the people working for the organization. For more information, see Location data (see page 654).
Before you begin
Review the supported associations (see page 654) for Location data.
To create associations for Location data
2. Click Foundation Data > Manage Locations.
3. Associate the Location data by performing the steps indicated in the following table:
Association Steps
Region to Region (If you want to define a parent-child hierarchy within the
regions.) a. Click Regions.
b. Select the region that you want to associate with region

to create an hierarchy.
c. On the Edit Region page, scroll to the Associate Region,

and click Associate.

d.
Association Steps
d. Select the regions from the list.
e. Click Save.
Site to Region (If you want to associate multiple sites for this region).
a. Click Regions.
b. Select the region that you want to associate to the site.
c. On the Edit Regions page, scroll to the Sites located in

this Region section, and click Associate.
d. Select the sites from the list, and click Select.
e. Click Save.
Site with Organizations (If you want to associate multiple organizations located
at this site). a. Click Sites.
b. Select the site that you want to associate with an

organization.
c. On the Edit Sites page, scroll to the Organizations located

in this Site section, and click Associate.
d. Select the organizations from the list that are located in

the site.
e. Click Save.
Person to Primary Site (If you want to associate a person with the primary
location or address of the organization where the person is working.) a. Click Sites.
b. Select the site that you want to associate to the person.
c. On the Edit Sites page, scroll to the People located in this

Site as their Primary Site section, and click Associate.
d. Select people from the list that are located in the site.
e. Click Save.
After you create associations for Location data, you can perform any of the following tasks:
Associating Organization data with other types of Foundation data (see page 675)
Associating Categorization data with other types of Foundation data (see page 681)
Associating Geography data with other types of Foundation data (see page 682)
Related topics

Location data (see page 654)
Creating or modifying Location data (see page 668)
Associating Categorization data with other types of Foundation data

The Categorization data classifies common items such as, c onfiguration items, operational services, support tickets,
incident requests, or change requests. For more information, see Categorization data (see page 657). The associations
for categorization data helps to identify the types of services, products, configuration items, or incident requests that are
used by an organization.
Before you begin
Review the supported associations (see page 657) for Categorization data.
To create associations for Categorization data
2. Click Foundation Data > Manage Categorizations.
3. Associate the Categorization data by performing the steps indicated in the following table:
Association Steps
Categorization to Categorization (if you want to define a parent-child type of relationship. The
categorization record can be operational, product, resolution, or root cause.) a. Select the category data for which you
want to create associations.
b. Click Child Categories.
c. Click Associate and select the

categorization data that you want to
associate.
d. Click Save.
Categorization to Organization (If you want to identify which categories will be used by the
organization.) a. Click Product Categories.
b. Select the category data that you want to

associate with the organization.
c. On the Edit Product Category page, click

Organizations.
d. Select the organizations from the list, or

click Associate to add additional
organizations.
e. Click Save.

After you create associations for Categorization data, you can perform any of the following tasks:
Create associations for Person data (see page 677)
Create associations for Organization data (see page 675)
Create associations for Location data (see page 679)
Create associations for Geography data (see page 682)
Related topics
Categorization data (see page 657)
Creating or modifying Categorization data (see page 669)
Associating Geography data with other types of Foundation data

You can leverage the Geography data and its association definitions to form a data model for your application. The
Geography Country is the top-level parent record definition that stores data related to a country such a state, province,
district, city, pin codes, or time zones.
You can associate the Geography data with other types of geography data or other Foundation data.
Before you begin
Review the supported associations (see page 659) for Geography data.
To associate Geography data
2. Select Foundation Data > Manage Geography.
3. Associate the Geography data by performing the steps indicated in the following table:
Association Steps
Country with State/

Province/ District a. Click Countries.
b. Select the country that you want to associate with a state, province, or district.
c. On the Edit Country page, scroll to the State, Provinces or Districts for this country section, and click New.
i. On the New State, Province or District page, enter the name of the state, province, or district that you
want to associate with the country.
ii. In Status, set the status for the newly added state, province, or district, such as Enabled or Obsolete.
d. Click Save.

Association Steps
State/Province/District with
City a. Click Countries.
b. Select the country in which you have created the state, province, or district.
c. On the Edit Country page, scroll to the State, Provinces or Districts for this country section.
d. Click the check box that corresponds to the state, province, or district that you want to associate with a city.
e. Click New City.
i. On the New City page, enter the name and description of the city.
ii. In Status, set the status for the newly added city, such as Enabled or Obsolete.
f. Click Save.
City with Postal Codes

a. Click Cities.
b. Select the city that you want to associate with a postal code.
c. On the Edit City page, scroll to the Zip/ Postal Codes for this city section.
d. Click New.
i. On the New Zip/ Postal Code page, enter the postal code that you want to associate with the city.
ii. In Status, set the status for the newly added postal code, such as Enabled or Obsolete.
e. Click Save.
City to Time Zone

a. Click Cities.
b. Select the country that you want to associate with a time zone.
c. On the Edit City page, in the Time Zone section, click Associate.
d. From the list, click the check box that corresponds to the time zone you want to associate with the city, and
click Select.
On the Edit City page, in the Time Zone section, under Pending Asociations, you can see the list of time zones.
e. Click Save.
The times zones under Pending Associations are associated with the city.
The Geography data model is now ready.
Related topics
Geography data (see page 658)
Creating or modifying Geography data (see page 671)

Loading Foundation data in bulk

BMC Helix Innovation Suite enables the administrators to load Foundation data in bulk. Bulk data loading is the process
of copying the Foundation data sets from Microsoft Excel spreadsheets and loading the data sets to BMC Helix
Innovation Suite. This capability makes the Foundation data available to the consuming applications and ensures
onboarding of users in the organization.
To load the Foundation data in bulk, BMC Helix Innovation Suite provides a Data Management Console application.
For more information about Foundation data, see Creating or modifying Foundation data (see page 661).
List of Foundation data that can be loaded in bulk

You can load the following Foundation data in bulk by using template spreadsheets:
Cities
Location
Organization
Categorization
People data
Support group
Direct or indirect Foundation associations
Workflow for loading Foundation data in bulk

The following table describes the details of each of the stages involved in this process:
Task Description Reference
1 You can download and use the Excel spreadsheets provided by BMC Helix Innovation Suite to enter the Download the template Excel
Foundation data. spreadsheets (see page 685)
2 You can update the downloaded Excel spreadsheets with relevant Foundation data. You must update the Update the template spreadsheets
spreadsheets in a specific format so that your Foundation data is validated for further processing. with Foundation data
3 You can upload the updated Excel spreadsheets to BMC Helix Innovation Suite so that the Foundation data is Upload the updated spreadsheets
available for processing. (see page 686)
4 You can run the data load job to process and load the Foundation data from the Excel spreadsheets to BMC Run the data load process (see page
Helix Innovation Suite. 688)
Related topics

Downloading the template Excel spreadsheets

BMC Helix Innovation Suite provides a few Microsoft Excel spreadsheets that you can use to enter the Foundation data.
Download the Excel spreadsheets spreadsheets and update them with relevant Foundation data.
Different template spreadsheets are available for loading different types of Foundation data.
The following table provides information about the available spreadsheets and their purpose:
Foundation Name of the Use

data spreadsheet or
ZIP folder
Category Categories.zip Load the category data.
The ZIP folder contains separate spreadsheets for operational, product, resolution, and root cause categorization data.
Location Location Data Load location-specific data such as region, site, and site area. The template contains different tabs for loading location data
Template.xlsx and location-specific associations.
Organization Organization Load the organization data such as operating companies and service providers.
Template.xlsx
Person Person Load person data such as employees, customers, agents, and vendors.
Template.xlsx
Foundation Associations. Load all the associations between foundation data structures such as person to organization, and person to support group.
associations zip
Cities All Cities.xlsx Load the city data. The spreadsheet is prepopulated with the data of world cities, but you can only use the entire file on a
licensed server. You can remove the cities of the countries that you do not require, and load data from a maximum of 3000
cities on an unlicensed server.
Sample Cities. Load a small set of the city data. The spreadsheet is prepopulated with a small set of city data. You can use this file on a
xlsx licensed or unlicensed server.
To download the Excel spreadsheets
1. Log in to BMC Helix Innovation Suite and navigate to the Workspace tab.
2. Click the Data Management Console application.
3. Click Visit Deployed Application.
4. From the Templates tab, click Download ( ) corresponding to the Excel spreadsheet or ZIP file.
Note
Ensure that you download the templates belonging to the latest version of BMC Helix Innovation Suite.
The ZIP folder contains multiple spreadsheets for a specific Foundation data.

The spreadsheet or the ZIP folder is downloaded to the default download location of your web browser.

Updating spreadsheets with Foundation data
Uploading the Foundation data spreadsheets
You can upload the updated Excel spreadsheets and upload them to BMC Helix Innovation Suite so that the Foundation
data is available for processing.

The details for the Data Management Console application are displayed.

4. Click Data Load.

A list of uploaded spreadsheets and their load status is displayed.
5. Click Upload New.

The Upload Data File dialog box is displayed.
You must upload the Foundation data in the following order:
category data > location data > organization data > person data > association data > city data.
Enter values for the following fields:
Element Description
Attachment Specify the name of the spreadsheet that contains the updated Foundation data.
name
File Provide a description for the updated spreadsheet.

Description

Element Description
Attachment Specify whether you want to upload a .xlsx file or a ZIP folder.
Type
Attachment To upload a .xlsx file, browse and select the updated .xlsx spreadsheet that you want to upload.
in To upload a ZIP folder, perform the following tasks:
Browse and select the updated ZIP folder that you want to upload.
In the xlsx Name field, enter the name of the .xlsx file that must be uploaded.
BMC Helix Innovation Suite processes only one .xlsx file from the ZIP folder. The ZIP folder can contain can contain other file
types such as .png file and more than one .xlsx file. However, BMC Helix Innovation Suite only recognizes the spreadsheet
named in the xlsx Name field and ignores all other spreadsheets.
Note: You can upload only one .xlsx file or a ZIP folder at a time.
Warning: Any uploads that run longer than an hour are not processed. Therefore, you must upload the Foundation data in smaller
batches and run the data jobs for each spreadsheet.
6. Click Save.
The updated Excel spreadsheet is uploaded to BMC Helix Innovation Suite. You can then run the load process to import
the Foundation data from the spreadsheet to Innovation Suite (see page 688).
Related topics
Downloading the template Excel spreadsheets (see page 685)

Update the template spreadsheets with Foundation data
Run the data load process (see page 688)
Running the Foundation data load process
After you upload the updated spreadsheets to BMC Helix Innovation Suite, you can run the data load job to process and
load the Foundation data from the spreadsheets to BMC Helix Innovation Suite.
To run the data load process

The details for the Data Management Console application are displayed.

4. Click Data Load.

A list of template spreadsheets and their data process status is displayed.
5. Select the file that you want to process and click the Run Process icon ( ) to trigger the data load process.
You can select multiple files for processing at one time; each file is considered a separate job and is processed
individually. However, the data load operation is memory intensive and any uploads that run longer than an hour
are not processed. Therefore, you must upload the Foundation data in smaller batches and run the data jobs for
each spreadsheet.
After the process is completed, the status of the process is displayed for each spreadsheet. You can then perform any of
the following tasks:

835665632 (see page 688) and resolve the issues, if any.
835665632 (see page 688) for long-term retention.
To view the status of the load process

You can view the processing status of every file in any of the following ways:
835665632 (see page 688)
835665632 (see page 688)
To view the status on the Data Load page

The details for Data Management Console application are displayed.

A visual representation of the application after it is deployed in BMC Helix Innovation Studio is displayed.
4. Click Data Load.

5. View the processing status beside the file that you processed.
The following table provides information about the processing status:
Icon Description
Data is ready to be processed.
Data is being processed.
Data is successfully processed.
File of an unsupported format is selected for processing.
To process the Foundation data, you must upload a .xlsx file or ZIP folder.
To view the status in processed spreadsheet


4. Click Data Load.

5.
5. From the Data Load Result column, click the Download File icon ( ) beside the processed spreadsheet that
you want to view.
The spreadsheet is downloaded to the default download location of your web browser. The Data Load Result column
contains the status spreadsheet that is automatically created for every load process.
The following image displays an example of a processed spreadsheet that is created automatically after the processing is
completed:
The following table provides information about the statuses available in the processed spreadsheet:
UI Description Examples
Element
Data Provides the status of the data load process for the The status can be either of the following:
Load respective row.
Status Processed
column Errored
Skipped
Status Provides additional information about processing The following details are displayed for a Processed operation:
column status.
Record Instance created with RecordId EMPID1
This column is appended automatically at the end of
the sheet for every tab. The following example shows the details for an Errored operation:
The data validations and formatting is not preserved [ERROR (307): Required field can not be blank.; com.bmc.
in the processed spreadsheet. Therefore, to resolve arsys.rx.foundation:Employee : Last Name, WARNING (52):
the errors, you must make the changes in the The field is a core system field and cannot be changed;
spreadsheet, upload it to BMC Helix Innovation 1]
Suite, and then run the processing job again.
The following example shows the details for a Skipped operation:
Bulk Data Load processing failed for row number 5.

Failure message [ERROR (307): Required field can not be
blank.; com.bmc.arsys.rx.foundation:Employee : Last
Name, WARNING (52): The field is a core system field
and cannot be changed; 1]
To archive the spreadsheets
2.


4. Click Data Load.

5. Click the Archive icon ( ) beside the file that you want to archive.
The file is archived and will no longer appear in the list of files on the Data Load page. To view all the archived files, select
the Show Archived check box.
Related topics
Downloading the template Excel spreadsheets (see page 685)
Update the template spreadsheets with Foundation data
Uploading the updated spreadsheets (see page 686)
Loading existing Foundation data from Remedy ITSM

As a Remedy IT Service Management Suite (Remedy ITSM) and BMC Helix Innovation Suite customer, you can leverage
Foundation data from Remedy ITSM in BMC Helix Innovation Suite.
Use this method for loading Foundation data to achieve the following results:
Import large amounts of Remedy ITSM Suite version 9.1 SP3 or later Foundation data to BMC Helix Innovation
Suite with minimal manual intervention.
Ensure faster onboarding and engagement of users in the organization - by making the Remedy ITSM Foundation
data available quickly to the consuming applications.
Continuously synchronize Foundation data changes in Remedy ITSM to BMC Helix Innovation Suite.
All changes made to Remedy ITSM Foundation data, such as modifications, deletions, and association changes are
synchronized to BMC Helix Innovation Suite.
The Remedy ITSM Foundation data is first copied to Microsoft Excel spreadsheets and then loaded to BMC Helix
Innovation Suite.
Before you begin

Before you load Foundation data from Remedy ITSM, ensure that you have considered the following points:
Version compatibility, supported and unsupported Foundation data, and restrictions in Foundation data
synchronization (see page 692).
Foundation field mappings in Remedy ITSM and BMC Helix Innovation Suite (see page 696).

Note
The Remedy ITSM Foundation data is locked for editing and cannot be modified after loading it in BMC Helix
Innovation Suite.
Process for loading Foundation data from Remedy ITSM

The following image provides an overview of the process of loading existing Foundation data from Remedy ITSM:
For more information about the process, see Leveraging Remedy ITSM Foundation data (see page 278)

Installing the BMC Helix Innovation Suite sync utility for Remedy ITSM (see page 700)
Foundation data load and synchronization considerations

Before you load existing Remedy IT Service Management Foundation data to BMC Helix Innovation Suite, ensure that you
are using a compatible version for the data load and understand the considerations for synchronizing Foundation data to
Foundation data load version compatibility information

The following list provides information about the compatible Remedy ITSM versions for loading Foundation data to BMC
Helix Innovation Suite:
18.08
18.05.003: Patch 3 for version 18.05
18.05.002: Patch 2 for version 18.05
18.05.001 : Patch 1 for version 18.05
18.05

9.1.04.002: Patch 2 for version 9.1.04
9.1.04: Service Pack 4
9.1.03: Service Pack 3
Foundation data types that can be loaded

You can load out-of-the-box Foundation data and custom Foundation data to BMC Helix Innovation Suite.
Out-of-the-box Foundation data

You can load the following out-of-the-box Foundation data from Remedy ITSM:
Foundation data: Person, Company, Site, Support Group, Product Category, and Operational Category
Foundation associations: Direct and indirect Foundation associations between Person, Company, and Site
Foundation data
Custom Foundation data

You can load the following custom Foundation data from Remedy ITSM:
Foundation data and Foundation associations: Custom fields added to out-of-the-box Foundation data in Remedy
ITSM through overlay Foundation data.
To prevent the Foundation data from being corrupted or lost during application or server upgrade, you cannot modify
the out-of-the box Foundation data. However, to meet your business requirements, you might want to add new fields to
the existing Foundation data. These new fields can be loaded and sycnhronized from Remedy ITSM to BMC Helix
Innovation Suite.
How synchronization works for created, updated, and deleted Foundation data
The following table describes how Foundation data is synchronized to BMC Helix Innovation Suite when it is created,
updated, or deleted from Remedy ITSM:
Remedy ITSM Foundation data BMC Helix Innovation Suite Foundation data
Foundation data is created. A similar Foundation data is created.
For example, AR user Foundation data is newly created in Remedy ITSM, a relevant Person foundation data
is automatically created in BMC Helix Innovation Studio.
Existing Foundation data is updated. Associated Foundation data is updated.
Foundation data is deleted. Foundation data that is deleted from Remedy ITSM is deleted from BMC Helix Innovation Suite.
An association is created between the A similar association is created between the respective Foundation data in BMC Helix Innovation Suite.
Foundation data.
Existing association between the Foundation Select Foundation data associations are updated or removed in BMC Helix Innovation Suite.
data is updated or removed.
Supported Remedy ITSM Foundation data for data load and synchronization
The Foundation data model differs between Remedy ITSM and BMC Helix Innovation Suite. As a result, data
corresponding to some Remedy ITSM Foundation data mappings are not loaded to BMC Helix Innovation Suite.

Best practice
Before performing a Foundation data load or synchronization, we recommended that you review this table in
detail for possible issues or workarounds.
The following table provides information about Foundation data that is loaded and synchronized from Remedy ITSM to
BMC Helix Innovation Suite:
Foundation Foundation data loaded or synchronized from Remedy ITSM Foundation data not loaded from
data type Remedy ITSM
Company
Companies of the COM:Company type only are loaded to BMC Helix Innovation Suite as Site is not associated with a
the following company types: region.
Organizations Changes made to categories in

Product Catalog or Service
Service Provider
Catalog are not synchronized to
Operating Company BMC Helix Innovation Suite.
Customer
Vendor
Departments
Support Organizations are loaded as Business units of the type Support.
Support Groups and Support Organizations are loaded as Support Groups.
Data is loaded according to the Primary organization types available in BMC Helix
Innovation Suite. After you load Organization data from Remedy ITSM, you cannot change
the company type.
The Company GUID and Group ID is loaded and does not change after data load.
All Remedy ITSM online and offline company data is synchronized. If a company is disabled
in Remedy ITSM, it is still synchronized.
Product category and operational category data, regardless of their state in Remedy ITSM,
is always loaded to BMC Helix Innovation Suite and assigned the Enabled state.
Site
Primary sites are loaded and synchronized regardless of the company. If you remove a home street
address for a person, the home
Home sites are associated with people data that have home street addresses.
site is not removed or
If people data is configured with home street address, BMC Helix Innovation Suite loads dissociated in BMC Helix
these home street addresses as home sites. Innovation Suite after data
synchronization.
During synchronization, sites that are deleted from Remedy ITSM are deleted from BMC
You must manually remove or
Helix Innovation Suite too.
dissociate the home site for the
person from BMC Helix
Innovation Studio.
Cities are not loaded to BMC

Helix Innovation Suite during data
load, and might cause blank
values. If there is any Foundation
data that uses Geography data
for cities, you must first load the
cities Foundation data in BMC

Foundation Foundation data loaded or synchronized from Remedy ITSM Foundation data not loaded from
data type Remedy ITSM
For more information, see Task 1

in Loading and verifying Remedy
ITSM Foundation data (see page
727).
Person
During synchronization, Person Foundation data that was deleted in Remedy ITSM is The Default Notify Mechanism
deleted from BMC Helix Innovation Suite too. that is configured for all users in
Remedy ITSM is not loaded to
If you change the company associated for a person in Remedy ITSM, the changes are
synchronized to BMC Helix Innovation Suite.
People with OOTB person client types only are loaded to BMC Helix Innovation Suite.
Support staff is loaded to BMC Helix Innovation Suite as agents person type and not as
employees person type.
The persons who are in the Enabled state are loaded as agents to BMC Helix Innovation
Suite. Additionally, a Login ID is created for every agent for accessing BMC Helix Innovation
Studio.
During data load, persons are associated to a company as primary organization.
Remedy ITSM users who have fixed licenses are assigned named licenses in BMC Helix
Innovation Suite.
Remedy ITSM users who have floating licenses are not assigned any license in BMC Helix
Innovation Suite, and therefore cannot access the application. In such a case, the
administrator must individually assign licenses to the users so that they can access the
application. For more information, see Assigning application licenses to users (see page
759).
Passwords are always migrated from Remedy ITSM to BMC Helix Innovation Suite. If the
password strength does not match the BMC Helix Innovation Suite guidelines, all
associations to Person Foundation data will break in BMC Helix Innovation Suite.
Additionally, the following error message is displayed: [ERROR (306): Value
does not fall within the limits specified for the
field; (Field ID - com.bmc.arsys.rx.foundation:Person
<123>, Maximum length - 30)]
You can choose to ignore the password policy enforcement in BMC Helix Innovation Suite
by configuring the following setting in the Centralized Tenant Configuration of BMC Helix
Innovation Studio:
Enforce-Password-Policy = F
For information about how to modify the centralized tenant configuration settings, see
Updating centralized tenant configuration settings (see page 756).
Associations
If you add or remove an existing association in Remedy ITSM, the changes for select
associations are synchronized to BMC Helix Innovation Suite.
During synchronization, Foundation data or association that is deleted from Remedy ITSM
is deleted from BMC Helix Innovation Suite too.
Restrictions in Remedy ITSM Foundation data synchronization

When you synchronize the Foundation data changes from Remedy ITSM to BMC Helix Innovation Suite, you encounter
the following restrictions:
You can perform a one-way synchronization only; any changes to Remedy ITSM Foundation data are
automatically updated to BMC Helix Innovation Suite.
Changes in BMC Helix Innovation Suite Foundation data are not updated to Remedy ITSM.

You cannot modify the synchronized Foundation data fields in BMC Helix Innovation Suite.
This behavior ensures that the Foundation data is not corrupted or lost during synchronize.
You can configure additional data that does not exist in Remedy ITSM. For example, Create functional roles (see
page 744) in Agent, Employee, Customer, and Vendor Foundation data.
Related topics
Foundation field mappings in Remedy ITSM and BMC Helix Innovation Suite (see page 696)
Foundation field mappings in Remedy ITSM and BMC Helix Innovation Suite
Before you load Foundation data from Remedy IT Service Management (Remedy ITSM) Suite to BMC Helix Innovation
Suite, you might want to understand how Foundation data from fields in Remedy ITSM is mapped to fields in BMC Helix
Innovation Suite. The Foundation data model differs between Remedy ITSM and BMC Helix Innovation Suite. Most fields
from Remedy ITSM Foundation and mapped to fields in the BMC Helix Innovation Suite Foundation library.
Customers can refer this topic to understand which fields are mapped to the BMC Helix Innovation Suite Foundation
library, and how they are mapped.
Field mappings in Company Foundation data

The following table provides information about Company, Person, and Site field mappings between Remedy ITSM and
BMC Helix Innovation Suite:
BMC Helix Innovation Suite fields Remedy ITSM Suite fields Description
and their IDs and their IDs
BMC Helix Innovation Suite record definition—com.bmc.arsys.rx.foundation:Primary Organization (Common Base)
Organization Name Company (1000000001) Commas replaced with space in translation.

(1000000010)
Status (7) Status (7) Remedy ITSM default status values that are provided out-of-the-box are mapped as is.
Organization Description Description (1000000000) Mapped as is.

(1000000000)
Notification Email List Not applicable Mapped as is.

(303500800)
Primary Organization Type Client Type

Remedy ITSM Client Type is mapped as is.
(304417291)
To support multi-select menu in BMC Helix Innovation Suite, semi colon is used as
a delimiter.
Budget Code (260100006) Budget Code Mapped as is.
Organization Abbreviation Company Abbreviation Mapped as is.

(1000000071)
Organization Email (260000018) Company Email Mapped as is.
Organization Hot Line Company Hiot Line Mapped as is.

(260000016) (260000016)
Company ID Company ID Mapped as is.

BMC Helix Innovation Suite fields Remedy ITSM Suite fields Description
and their IDs and their IDs
BMC Helix Innovation Suite record definition—com.bmc.arsys.rx.foundation:Primary Organization (Common Base)
Organization Web Page Company Web Page Mapped as is.

(260000019)
Cost Center (260100007) Cost Center Mapped as is.
Currency (240600036) Currency Mapped as is.
Hours of Operation (260100108) Hours of Operation Mapped as is.
Lead Time in Days (260000013) Lead Time (Days) Mapped as is.
Time Zone (240600035) Time Zone Out-of-the-box time zones from Remedy ITSM as mapped to matching IDs of time zones
in BMC Helix Innovation Suite.
Field mappings in Person Foundation data

The following table provides information about mapping of Person data in Remedy ITSM with BMC Helix Innovation
Suite:
BMC Helix Innovation Suite field Remedy ITSM field Description
BMC Helix Innovation Suite record definition —com.bmc.arsys.rx.foundation:Person (Base)
Unique Person ID LEN(38) (179) instanceId (179)

Mapped as is.
To ensure that future updates, deletions, and assoications are

processed, MUST remain unchanged.
Title (1000000021) Title (304299880)

Out-of-the-box values: Mr., Mrs., Ms., Dr., and Miss.
Non-matching values are mappe as NULL.
First Name (1000000019) First Name (1000000019) Mapped as is.
Preferred Name (1000000024) Nick Name (1000000024) Mapped as is.
Middle Name (1000000020) Middle Name (1000000020) Mapped as is.
Last Name (1000000018) Last Name (1000000018) Mapped as is.
Employee Type (304410181) Employee Type (304410181) Only out-of-the-box values are taken.
Employee ID (1000000054) Corporate ID (1000000054) Mapped as is.
Job Title (1000000023) Job Title (1000000023) Mapped as is.
NT Domain (420003300) Not applicable Not mapped from anywhere.
Primary Phone Type (304409631) Calculated Selection Field

Depends on the data Business.
If data Business does not exist, the values are:
Home—For home-based user
Mobile.
Primary Phone Number (1000000056) Phone Number Business OR Not applicable
Phone Number Home OR
Phone Number Mobile

Primary Email Type (304409601) Calculated Selection Field In Remedy ITSM, if the Internet E-mail field is not null, it is set to
Business.
Primary Email Address (1000000048) Internet E-mail Mapped as is.
Secondary Phone Type (304409621) Calculated Selection Field Depends on data Business if it exists. If the data Business does not
exist, it is home if home-based user or mobile.
Secondary Phone Number (1000000059) Phone Number Business OR Not applicable.
Phone Number Home OR
Phone Number Mobile
Secondary Email Type (304409611) Calculated Selection Field In Remedy ITSM, if the Corporate E-mail field is not null, it is set to
Other.
Secondary Email Address LEN(255) (530013700) Corporate E-mail Mapped as is.
VIP (1000000026) VIP (1000000026) Mapped as is.
Sensitivity (1000000027) Sensitivity (1000000027) Mapped as is.
Hire Date (304411651) Not applicable Not mapped
Assignment Availability (1000000346) Assignment Availability Mapped as is.

(1000000346)
Notification Language (1000003974) Notification Language Out-of-the-box values for this field are mapped as is.
(1000003974)
Login ID (4) Login ID (4) Mapped as is.
Password (123) Password (in User form) Mapped as is.
License Type (109) Not applicable Set to Named.
Default Notify Mechanism (430000003) Default Notify Mechanism Mapped as is.

(430000003)
Permissions (430000000) Not applicable Not mapped
Functional Roles (430000002) Unrestricted Access If a person has Unrestricted Access, this functional role is granted in
Application Licenses (430000001) Not applicable Not mapped
Person Image (304411861) Not applicable Not mapped
Status (7) Status (7) Mapped as is.
Accounting Number (240000042) Accounting Number Mapped as is.
Accounting Code (302006500) Accounting Number 2 Mapped as is.
Cost Center (1000000188) Cost Center Mapped as is.
Cost Center Code (300469300) Cost Center Code Mapped as is.
Cost Center Name (300469200) Cost Center Name Mapped as is.
Desk Location (1000000035) Desk Location Mapped as is.
GEOnet (1000000046) GEOnet (1000000046) Not applicable
Mail Station (1000000036) Mail Station Mapped as is.
Association - Business Unit Organization Not applicable

Association - Department Department Not applicable
Agent Support Staff Mapped as is.
Field mappings in Site Foundation data

The following table provides information about mapping of Site ITSM Foundation data with BMC Helix Innovation Suite:
BMC Helix Innovation Suite ITSM Suite field Description

field
BMC Helix Innovation Suite record definition— com.bmc.arsys.rx.foundation:Site (Base parent is com.bmc.arsys.rx.foundation:Location)
Site Name (260000001) Site (260000001) Mapped as is.
Site Description Description Mapped as is.

(1000000000) (1000000000)
Unique Site ID (179) InstanceId (179)

Mapped as is.
To ensure that future updates, deletions, and assoications are processed, MUST
remain unchanged.
Site Type (304410811) Not applicable

If data provided from the SIT:Site form—Hardcoded as Business.
If data provided from Person Home Address—Hardcoded as Residential.
Country (1000000002) Country (1000000002)

The GUID is mapped from Remedy ITSM to this field.
If GUID is not not found, kept blank in BMC Helix Innovation Suite.
State, Province or District State Province

(1000000003) (1000000003)
City (1000000004) City (1000000004)

Important: Cities are not loaded in BMC Helix Innovation Suite. You have to manually load the
cities data.
Street Address (1000000037) Street (1000000037) Mapped as is.
ZIP/Postal Code Not applicable

Mapped as is only if the following requirements are present in Remedy ITSM:
(1000000039)
ZIP requires a City.
City requires State/ Province.
State/ Province requires Country.
Additional Site Details Additional Site Details Mapped as is.

(1000001263) (1000001263)
Time Zone (1000000541) Not applicable Out-of-the-box time zones from Remedy ITSM as mapped to matching IDs of time zones in
Site Status (7) Status (7) Remedy ITSM standard values as mapped as is.

Related topics
Loading and verifying Remedy ITSM Foundation data (see page 727)
Creating a Pentaho job to load custom Foundation data (see page 710)
Installing the BMC Helix Innovation Suite sync utility for Remedy ITSM
To load the Foundation data from Remedy IT Service Management (Remedy ITSM) Suite to BMC Helix Innovation Suite
you must prepare your system for data transfer. You must download the following predefined files in BMC Remedy
Deployment Application (D2P package):
Atrium Integrator jobs and transformations, forms, and filters—Loads and synchronizes Foundation data from
Remedy ITSM.
Synchronization plug-in: Automatically synchronizes any changes in Remedy ITSM Foundation data to BMC Helix
Innovation Suite.
You must perform the tasks in this topic in the following scenarios:
If the D2P package for Foundation data load is not installed as part of your activation.
If BMC Remedy Action Request System (Remedy AR System) and Remedy ITSM are deployed in virtual machines.
Notes
You can load Foundation data from Remedy ITSM Suite version 9.1 SP3 or later.
For the complete list of compatible Remedy IT Service Management versions for loading Foundation
data, see Foundation data load compatibility information (see page 692).
If you are using Remedy ITSM version 9.1.04, after you import the predefined Pentaho jobs and
synchronization plug-in, you must also install the latest JAR file else the Pentaho jobs are not imported.
For information about how to install the latest JAR file, see Install latest JAR file for Remedy ITSM Suite
version 9.1 SP4 (see page 703).
Before you begin

Before you prepare your environment for Foundation data load, ensure that you have completed the following tasks:
To ensure that the predefined Pentaho jobs and transformations are imported, ensure that you have installed the
following patch:
18.05.01 or later: Service Pack 1 for 18.05 or later

Verify that the string /api/rx/application/command exists in the excluded-url-pattern parameter in the /conf
/rsso-agent.properties file, so that Remedy Single Sign-On (RSSO) is configured. For more information about
configuring Remedy SSO OAuth 2.0 authentication in your application, see Manually integrating Remedy SSO
with Remedy applications .
Task 1: To download the D2P package

Download the D2P package, so that you can obtain the predefined Pentaho jobs, transformations, and plug-in file.
1. From the BMC Remedy AR System server, with your support ID, log in to the BMC Electronic Product Distribution
page.
2. Select Product Downloads > Licensed Products.
3. In the Licensed Products View page, select the following options:
a. View: Licensed Product
b. Profile: Master
4. In the Find field, enter Remedy IT Service Management Suite and click Go.
5. From the search results, select Remedy IT Service Management Suite 18.11.00 > Remedy ITSM Foundation to
Innovation Suite Sync Utility Deployment Package Version 18.11.00.
6. Click Download.
The single download button replaces both Download via FTP and Download Manager buttons in the interface.
The ZIP file ITSM_Innovation_Suite_Foundation_SYNC_Utility.zip is downloaded to the default download location of your
web browser.
Task 2: To deploy the BMC Helix Innovation Suite Sync Utility

Import and deploy the ITSM_Innovation_Suite_Foundation_SYNC_Utility. This utility includes the predefined Pentaho
transformations and jobs that help you load the existing Foundation data from Remedy ITSM.
1. From the Mid Tier, to open the AR System Deployment Management Console, access the following URL:
http://<midtier>/arsys/forms/<arserver>/RDA%3ADeployment+Management+Console/Default+Administrator+View
For more information about how to access the Deployment Management Console, see Using the AR System
Deployment Management console .
2. From the left navigation pane, select Transfer Package> Import and then select the package
InnovationSuiteFoundationSYNCfor9.1.03_XX .zip.
3. Click OK.
4. After the package is imported, select the package Innovation Suite Foundation SYNC for 9.1.03.
5. From the left navigation pane, select Operations and click Deploy.
6.
6. (If you have not installed the r equired patch (see page 700)), assign Administrator permissions to records with
config-iss data tag, perform the following steps:
a. On the Mid Tier, navigate to the UDM:Import form.
b. Click New Search.
c. In the DataTags field of the UDM:Import form, specify config-iss and click Search.
The search results will display all records with config-iss data tag.
d. From the search results, click Select All > Modify All.
e. From the Permissions field, select Groups > Administrator.
f. Click Save.
The predefined Pentaho jobs and transformations are imported to the Pentaho repository.
Task 3: To extract the synchronization plug-in

Import the synchronization plug-in, so that any changes to existing Remedy ITSM Foundation data and newly-added
Foundation data are automatically synchronized to BMC Helix Innovation Suite.
1. On the AR System server, extract the ZIP file ITSM_Innovation_Suite_Foundation_SYNC_Utility.zip.
2. From the extracted folder, copy the JAR file com.bmc.arsys.foundationsync-1.0.0-SNAPSHOT.jar to the
<defaultInstall>/ARSystem/<pluginsvr_home> directory.
3. Open the BMC Remedy AR System Administration Console, and select System > General > Plugin Server
Configuration.
For information about how to open the AR System Administration Console, see Navigating the BMC Remedy AR
System Administration Console .
4. In the Plugin Configuration tab, click Create and provide the following values:
Field Action
Plugin Name Enter the plug-in name as ARSYS.FOUNDATIONSYNC.
Plugin Class Name Enter the class name as follows:com.bmc.arsys.foundationsync.plugin.FoundationSyncPlugin
Plugin File Name Provide the file name as follows:

<pluginsvr home>\com.bmc.arsys.foundationsync-1.0.0-SNAPSHOT.jar.
Path Elements Click the plus sign and enter the path element as follows:
ARSYS.FOUNDATIONSYNC.pathelement.type.location = <pluginsvr_home>\com.bmc.arsys.foundationsync-1.0.0-
SNAPSHOT.jar
User Defined Elements Click the plus sign and enter the user-defined element as follows:
ARSYS.FOUNDATIONSYNC.userDefined.NoOfThreads = 5
5. Click OK.
The following image shows an example of the values specified for the ARSYS.FOUNDATIONSYNC plug-in:

6. Restart the plug-in server to enable the plug-in.

For information about how to restart the plug-in server, see Restarting the plug-in server using the Set Server
Info command and Remedy - Server - How to restart the Java Plug-in Server (Unix/ Linux/ Windows) .
To modify the Foundation data synchronization schedule

The synchronization plug-in is scheduled to run at 12 AM daily so the Foundation data changes synchronize every 24
hours. If you want, you can change the synchronization interval time.
Best Practice
BMC recommends that you can schedule the plug-in to run up to a maximum of four times per day.
Synchronization operations are memory intensive. Frequent synchronizations can affect server performance
and increase synchronization errors.
1. Start the BMC Remedy Developer Studio from BMC Remedy AR System server.
For information about how to start the BMC Remedy Developer Studio, see Starting and logging on to BMC
Remedy Developer Studio .
2. Open the escalation INS:FoundationSYNC_Job.
3. Specify the interval for executing the escalation.

You can define the escalation to run at a specific time or at a specific interval.
For information about how to modify the escalation, see Creating escalations .
Task 4: (If you are using Remedy ITSM 9.1.04) To install the latest JAR file for Remedy ITSM
Note
If you are using Remedy ITSM version 9.1.04, after you import the predefined Pentaho jobs and
synchronization plug-in, you must also install the latest JAR file else the Pentaho jobs are not imported.

1. Open the pluginsvr_config.xml file.

The file is located in the pluginsvr subdirectory of your AR System server installation directory. This file should be
in the same directory as the plug-in server JAR files and startup script.
2. In the pluginsvr_config.xml file, add the following entry:

<pathelement type="location">C:/Program Files/BMC Software/ARSystem/diserver/data-integration/lib/commons-
collections4-4.1.jar</pathelement>.
3. Restart the plugin server.

For information about how to restart the ITSM service, see Restarting the plug-in server using the Set Server Info
command .

Action Reference
If you want to load custom Identifying fields added to view overlays in Remedy AR System documentation. After identifying the fields, you must
Foundation data, identify the return to BMC Helix Innovation Suite to perform the next step in the workflow of loading Foundation data from Remedy
custom overlay fields ITSM (see page 278).
If you do not want to load custom Connecting the Foundation data repositories (see page 725)
Foundation data
Extending BMC Helix Innovation Suite Foundation definitions

Developers can extend the Foundation data application definitions, such as record, view, and association so that you add
or remove objects in the definitions. When you load custom Foundation data from Remedy ITSM, you must extend the
Foundation definitions in BMC Helix Innovation Suite to include the custom Foundation data fields in Remedy ITSM. For
more information about identifying custom fields, see Identifying fields added to view overlays . If you do not need to
load custom Foundation data from Remedy ITSM, go to the next step in the workflow of loading Foundation data from
Remedy ITSM (see page 278).
You can extend the Person record definition in the Foundation library to add custom fields such as Passport number and
Passport expiry date. After you extend the definitions, you can create processes and rules to manage the data stored in
the newly-added objects. You can also move the extension definitions to other environments by creating install packages
(see page 766) and deploying the install packages to other environments (see page 773).
By default, the BMC Helix Innovation Suite Foundation definitions are enabled for extension. For all other applications,
you must create extendable definitions before you can extend them.
For example, you can extend the Person record definition in the Foundation library to add new fields such as Passport
number and Passport expiry date.
Note
You cannot extend the join and audit type of record definitions.

Before you begin
Ensure that you have permission to access the Foundation library and the custom application, so that the record
definitions and views can be created. For more information, see Roles and permissions (see page 743).
If you are extending definitions other than the Foundation definitions, ensure that you have enabled extension of
application definitions (see page 415).
If you are loading custom Foundation data from Remedy ITSM, ensure that you have imported predefined
Pentaho jobs (see page 700).
Process for extending application definitions

You can follow the same workflow to extend definitions in all other applications.
1 Create an extension record definition. To create an extension record definition

(see page 705)
A extension record definition contains the new fields that you want to add to the record definitions
that is being extended.
2 Create an extension association definition between the extension record definitions and the record To create an extension association (see page
definition in Foundation library. 705)
3 Create an extension view definition that you want to use to extend the record definition in the To create an extension view (see page 707)
Foundation library.
To create an extension record definition

In your custom application, you can create a regular record and specify all the additional fields that you require. For
example, you create a Passport information record and add Passport Number field, so that you can include passport
number for all employees in your organization. For the steps to create an extension record definition, see Creating or
modifying regular record definitions (see page 329).
Consider the following points when you create an extension record definition:
The extension record definition with additional fields can be associated with only one record definition. To avoid
errors, you must add a new extension definition for each association with the record definition in the Foundation
library.
The Description field is an out-of-the-box core field. This is a required field that is added to your record
definition. If it doesn't have a default value, the record definition cannot be saved, and an error Missing required
field is displayed. If you do not want to display this field in the application, select the Description field and in the
Settings tab, in the Default Value field, enter any value.
To create an extension association

You must create a direct association between the extension record definition and the record definition that is locked for
customization. For example, you can create a direct association between the Passport Information record definition and
the Employee record definition.

If you are creating new association (of type one-to-one or one-to-many), use the newly-created extension record
definition (for example, Person extension record definition) instead of the out-of-the-box Foundation record definition
(for example, Person record definition) form. Additionally, the newly-created extension record definition must always be
set as node B.
For more information about record associations, see Creating record associations (see page 342).
1. Log in to BMC Helix Innovation Studio, and navigate to the Workspace tab.
2. Select the application where you created the extension record definition.
3. Select Associations > New.
4. Specify the properties for the association.

The descriptions of some of the fields are explained in the following table:
First Record Select the out-of-the-box record definition as the node A of the association. Example: Person
Cardinality Select the cardinality as Has One to create a direct association.
Second Record Select the newly-created regular record definition as the node B of the association. Example: Passport Information
Role of First Provide a description in the context of the association. Example: The role of first record (node A) can be Person.
Record
Role of Provide a description in the context of the association.

Second Record Example: The role of second record (node B) can be PassportInfo.
Note: To ensure that the Foundation data load is completed successfully, BMC recommends that you specify the role for first
record and second record. The roles ensure that the foreign key field, that is automatically added to an extension form, is
identified during Foundation data load.
Add Select all the following constraints:

Constraints
If record is deleted, automatically delete all associated records
Require a record to be associated in order to create a new record
Scope The default value is Private. Do not change this value.

/Customization
Options
The following image is an example of creating a direct association between Person Foundation record definition
and Passport Information record definition:

5. Click Save.
To create an extension view definition

Create an extension view for the regular record definition.
2. From the Workspace tab, navigate to the application where you created the new record definition.
3. Select View > New > Container.
4. On the Properties tab, in Name, provide a name for the view.
5. Select the view from the Foundation library that you wan to extend by filling out the following fields:
Select the view in Foundation library that you want to extend
a. From the View to Extend list, select the Foundation view that you want to extend.
For example, PER Create Foundation view.
b. From the Extension Container list, select the extension container in which the view must appear.
The following image shows an example of Extension Containers available for PER Create Foundation view:

6. Configure the view.

Select the newly created record definition, association, and custom fields
a. From the Palette, drag the Record Editor component to the canvas and configure the properties.
b. For the Record Editor component, click the Settings icon and fill out the following fields:
UI element Description
Name Provide a unique name for the record editor.
Label Provide the label to be displayed in the application.

Note: If you do not provide a label, then the bundle name is displayed in the application.
Record Select the newly-created regular record definition. Example: Passport Information
Definition
Name
Association If there is only one association, the name of the association is auto-populated. If there are multiple associations, select the
to use association that you created earlier. Example: Employee to Passport Information
Mode The mode of the record editor is automatically set to match the mode of the record editor in the Foundation view.
Create: Enables users to create records.
Edit: Enables users to edit the existing records.

Important: If you select a mode that is different from the parent Foundation view's mode, the extension view is not
displayed in the application.
Form To include specific record fields to appear in the view, click Quick Add/Remove fields and select the custom fields that you
Contents require.
(Optional) In the Expression Editor, build an expression on the fields in the record editor if you want to hide or display these fields
Click to when specific conditions are met. You can also specify to disable the expression when the parent person status is offline.
build an For information about how to build expressions in view definitions, see Creating or modifying view definitions.
expression
a. Click Save.
7. The following image shows an example of an Employee Foundation view at run time, which includes the newly-
added Passport Number field:

Next task Reference
If you want to load custom Foundation data in Remedy ITSM and load the Foundation data in BMC Creating a Pentaho job to load custom
Helix Innovation Suite . Foundation data (see page 710)
If you are a business analyst or a developer, create processes and rules to manage the data stored in Defining the application business logic
the newly-added fields. through processes (see page 421)
Adding rules to validate data or trigger
events in a process (see page 490)
If you are an administrator or a developer, transfer the Foundation data customization to other Creating install packages to deploy entire
environments by creating install packages and deploying them to other environments. applications (see page 766)
Installing, reinstalling, or uninstalling
applications (see page 773)
If you are a business analyst or a developer, troubleshoot issues that you encountered while Troubleshooting Foundation data issues
customizing or extending Foundation data. (see page 989)

Creating a Pentaho job to load custom Foundation data

If you want to load custom Foundation data from Remedy IT Service Management (Remedy ITSM) Suite, you must create
a Pentaho job and transformations in Remedy ITSM to identify, read, and load the custom Foundation data into BMC
Helix Innovation Suite for processing. if you do not want to load custom Foundation data from Remedy ITSM, this task is
not required.
Note
You can load Foundation data from Remedy ITSM Suite version 9.1 SP3 or later. For a complete list of
compatible Remedy IT Service Management versions, see Foundation data load compatibility information (see
page 692).
Example
To meet your business requirements, you want to provide additional details like Passport Number and SSN for all
Employees in your organization. In such case, you must specify the custom Foundation data in Remedy ITSM so that the
custom data is identified and loaded to BMC Helix Innovation Suite. For example, to define the custom Foundation data,
you can create a Pentaho job Initial Sync - Person Additional Details and the following transformations:
Person Additional Details - Header to define the header of Excel spreadsheet.
Person Additional Details to define the sequence of data load.
When you run the Pentaho job Initial Sync - Person Additional Details, the Passport Number and SSN fields are loaded
from Remedy ITSM.
Before you begin
Ensure that you have Identified the fields added to view overlays that you want to load.
Ensure that you have extended the Foundation definitions (see page 704) in BMC Helix Innovation Suite to
include the custom Foundation fields.
Task 1: To modify CTM:People form to include custom fields

Identify the custom fields that you want to import in BMC Helix Innovation Suite from Remedy ITSM Foundation data.
For example, custom fields for Sites, People, Company, Support group, and category Foundation data. Add the custom
fields to CTM:People form, so that these fields are loaded from Remedy ITSM, and displayed as part of the out-of-the-box
Foundation record.
1. Log in to BMC Remedy IT Service Management console as an ITSM administrator.
2. Navigate to the CTM:People form.
3. Add the custom fields to suit your business needs.

For example, Passport Number and SSN fields.
The following image shows an example of custom fields that are added to CTM: People form:

Task 2: To create a Pentaho job in Remedy ITSM

Create a custom Pentaho job in Remedy ITSM, so that your custom Foundation data is loaded to BMC Helix Innovation
Suite.For example, create a Pentaho job Initial Sync - Person Additional Details for loading custom Foundation data for
employee, such as Passport Information and SSN.
You can create multiple transformations in a single job for different Foundation data types, for example, a single Pentaho
job that contains a transformation each for extended Person data, extended Organization data, and extended Site data.
1. Log in to BMC Remedy AR System server as an AR administrator.
2. In the Atrium Integrator Spoon client, select File > New > Job.
3. Right-click the new job, and in the Job tab, provide the following information:
UI field Description
Job Provide a unique name for the custom job. For example, Initial Sync - Person Additional Details.
name
Directory Specify the directory as Innovation Suite SYNC, so that the job can execute and load custom Foundation data to BMC Helix Innovation
Suite, and save the changes.
Important: If you do not select the Innovation Suite SYNC, the job is not executed and custom Foundation data is not loaded to BMC
The following image shows an example of newly-created Pentaho job Initial Sync - Person Additional Details:

4. In the Parameters tab, copy the parameters from a predefined Pentaho job for Innovation Suite - Sync directory
to the new job.
For example, copy the parameters from Initial Sync-Foundation data job to the newly-created Pentaho job Initial
Sync - Person Additional Details.
The following image is an example of parameters that you need to copy to the new Pentaho job:
5. In the Log tab, copy the log fields from a predefined Pentaho job for Innovation Suite - Sync directory to the new
job. You must copy the log fields for both Job log table properties and Jog entry log table properties.

5.
For example, copy the log fields from Initial Sync-Foundation data job to the newly-created Pentaho job Initial
Sync - Person Additional Details. This step ensures that the log settings used for new Pentaho job are same as
that of other predefined Pentaho jobs in Innovation Suite - Sync directory.
The following image is an example of Job log table fields that you need to copy to the new Pentaho job:
The following image is an example of Job log entry table fields that you need to copy to the new Pentaho job:
6. Click OK.

Task 3: To create a custom Pentaho transformation for defining the header of Excel spreadsheets
Create a custom Pentaho transformation in Remedy ITSM, so that you define the header of the Excel spreadsheet. For
example, for defining the header of Excel spreadsheet that loads Passport Information and SSN custom fields, create a
Person Additional Details - Header transformation.
1. In the Atrium Integrator Spoon client, select File > New > Transformation.
2. Right-click the new job, and in the Transformation tab, provide the following information:
Transformation Provide a unique name for the custom transformation. For example, Person Additional Details - Header.
name
Directory Specify the directory as Innovation Suite SYNC, so that the transformation can execute and load Excel spreadsheets to BMC Helix
Innovation Suite.
Important: If you do not select the Innovation Suite SYNC, the job is not executed and custom Foundation data is not loaded to
The following image shows an example of new Pentaho transformation Person Additional Details - Header:
3. In the Parameters tab, copy the Parameters and Logging channels from a predefined Pentaho transformation for
Innovation Suite - Sync directory to the new transformation.
For example, copy the Parameters and Logging channels from a transformation in Initial Sync-Foundation data
job to the newly-created Pentaho transformation Initial Sync - Person Additional Details - Header.
4. From the Design tab on the left side, drag the following steps to the canvas:
Step Description
Generate This step generates the rows that you want to display in an Microsoft Excel spreadsheet.
Rows
a. Select Input > Generate Rows.

b.
Step Description
b. Right-click the step > Edit > specify the following information:
i. Field name
ii. Field type

The following image shows an example of Generate Rows step EMPL Header 1.
You can add multiple Generate Rows steps in your transformation, according to the rows you want to include in the Excel spreadsheet.
The following image shows an example of Generate Rows step EMPL - AGNT Row 2 for adding employee name, passport number, and SSN
row headers in the in the Excel spreadsheet.
Excel This step appends the custom Foundation data to an Microsoft Excel spreadsheet.
Writer
a. Select Output > Microsoft Excel Writer.
b. Right-click the step > Edit > specify the following fields for the Excel Writer step:
Filename
Sheet name
You can add multiple Excel Writer steps in your transformation, according to the Foundation data you want to include in the Excel
spreadsheet.
The following image shows an example of Excel Writer step EMPL Row 1.

Step Description
Block this This step generates blocks the steps till all the earlier steps are completed successfully.
step until
steps finish a. Select Flow > Block this step until steps finish.
b. Right-click the step > Edit > specify the step name that you want to watch for.
You can add multiple Block this step until steps finish steps to your transformation.
The following image shows an example of Block this step until steps finish step Wait for Row 4:
Connection Add the hop connection between the steps, so that you specify the sequence in which the steps must be processed. The following image
shows an example of hop connections created for Pentaho transformation Initial Sync - Person Additional Details:

Step Description
Task 4: To create a custom Pentaho transformation for processing the custom Foundation data
Create a custom Pentaho transformation in Remedy ITSM, so that you define the process for generating the Excel
spreadsheets. For example, for loading Passport Information and SSN custom fields for Employee Foundation data, you
create a Person Additional Details transformation.
Note
If you are loading different types of Foundation data, you must create a transformation for every Foundation
data type in the same Pentaho job. For example, you must create a transformation each for extended Person
data, extended Organization data, and extended Site data.
1. In the Atrium Integrator Spoon client, select File > New > Transformation.
2. Right-click the new job, and in the Transformation tab, provide the following information:
Transformation Provide a unique name for the custom transformation. For example, Person Additional Details.
name
Directory Specify the directory as Innovation Suite SYNC, so that the transformation can execute and load Excel spreadsheets to
Innovation Suite.
Important: If you do not select the Innovation Suite SYNC, the job is not executed and custom Foundation data is not loaded to
Innovation Suite.
The following image shows an example of new Pentaho transformation Person Additional Details:

3. In the Parameters tab, copy the Parameters and Logging channels from a predefined Pentaho transformation for
Innovation Suite - Sync directory to the new transformation.
For example, copy the Parameters and Logging channels from a transformation in Initial Sync-Foundation data
job to the newly-created Pentaho transformation Initial Sync - Person Additional Details.
4. From the Design tab on the left side, drag the following steps to the canvas:
Step Description
AR Input This step reads the custom Foundation data from AR System form.
a. Select Input > AR Input.
b. Right-click the step > Edit > specify the following information:
i. Field name
ii. Field type
The following image shows an example of Generate Rows step Get Employees.

Step Description
Add This step adds one or more constants to the input rows.
constants
a. Select Transform > Add constants.
b. Right-click the step > Edit > specify the following constants:
i. varEmpty
ii. varOperation
The following image shows an example of Add constants step.
Excel Writer This step appends the custom Foundation data to an Microsoft Excel spreadsheet.
a. Select Output > Microsoft Excel Writer.
b. Right-click the step > Edit > specify the following fields for the Excel Writer step:
Filename
Sheet name
You can add multiple Excel Writer steps in your transformation, according to the Foundation data you want to include in the Excel
spreadsheet.

Step Description
The following image shows an example of Excel Writer step Write Employee:
Connection Add the hop connection between the steps, so that you specify the sequence in which the steps must be processed.
The following image shows an example of hop connections created for Pentaho transformation Person - Additional Details:
Qualification Double-click the newly-created transformation Person Additional Details, and perform the following tasks:
a. For pdireport-servername, select Qualification > Configure Qualification.
b. Specify the qualification string.

For example, to ensure that adiitional data (other than the qualified People data) is not processed, specify the following string:
(('DataTags' = $NULL$) OR (('DataTags' != $NULL$) AND NOT(('DataTags' LIKE "%config-fnd%") OR ('DataTags' LIKE "%
seeddata%") OR ('DataTags' LIKE "%SOLUTIONDATA%"))))
c. Save the changes.
d. Change the server to AR Server.

Step Description
The qualifications are passed to specify that Instance ID of Person is the required field. The Instance ID fields stores the foreign key in the
extension record definition.

Synchronizing custom Foundation data changes to BMC Helix Innovation Suite (see page 721)
Synchronizing Foundation data changes to BMC Helix Innovation Suite

To ensure that Foundation data from Remedy ITSM is synchronized to BMC Helix Innovation Suite, you must configure
Remedy ITSM for synchronization. You must add filters to track creation, update, and deletion of custom Foundation
data for the following situations:
Changes to existing custom Foundation data
Newly-added custom Foundation data
Changes to out-of-the-box Foundation data are automatically synchronized. You are not required to perform any
additional configurations.
Note
The sample Foundation data (seed data) is not synchronized from Remedy ITSM.
By default, the synchronization plug-in is scheduled to run at 12 AM daily so that Foundation data is synchronized every
24 hours. You can modify the synchronization schedule. For more information, see To modify the Foundation data
synchronization schedule (see page 700) .
Note
To synchronize Foundation data changes, you can configure Remedy ITSM Suite version 9.1 SP3 or later. For a
complete list of compatible Remedy IT Service Management Suite versions, see Foundation data load
compatibility information. (see page 692)
Before you begin

For custom Foundation data, ensure that you have completed the following tasks:
Extended the Foundation definitions (see page 704) in BMC Helix Innovation Studio to include the custom
Foundation data fields in Remedy ITSM.
Created a Pentaho job and transformations (see page 710) for loading custom Foundation data from Remedy
ITSM.

Task 1: To create filters for tracking changes to custom Foundation data

Create filters for the AR System form that you customized, so that any creation, modifications, and deletions to custom
Foundation data is tracked. The filters track the newly-added custom Foundation data as well as changes to existing
Foundation data in Remedy ITSM.
For example, if you customized CTM:People form to add Passport number and SSN for employees, you must create
filters for the CTM:People form.
1. Log in to BMC Remedy Developer Studio from BMC Remedy AR System server.
2. Select your local repository > All Objects.
3. Right-click Filters > New Filter.
4. In the associated form, select the Foundation data form that you customized for additional data. For example,
CTM: People form.
5. Add the filters for tracking creation, updates, and deletions of custom Foundation data.
The following image shows an example of filters created for CTM:People form:
6. Specify the following information:

Execution Specify when the filter must be executed. For example, to execute the filter when user saves the custom Foundation data, select
Option Submit.
Run If Specify the condition for executing the filter. A change log is created only when the conditions are met.
Qualification For example, to execute the create filter when user provides a value in Passport Number or SSN fields, specify the following string:
'Passport Number' != $NULL$ OR 'SSN'!= $NULL$
A change log is created only when the Passport Number or SSN value is entered.
To execute the update filter when user modifies the Passport Number or SSN fields, specify the following string: 'DB.Passport
Number' != 'Passport Number' OR 'DB.SSN' != 'SSN' A change log is created only when the Passport Number or SSN value is modified.
Push Fields Reads the data that is created in the record instances and populates the data in BMC Helix Innovation Studio Foundation-Sync form.
Additionally, this field identifies the custom Foundation data as a specific type of Foundation data. For example, when the Passport
Number and SSN fields are loaded to BMC Helix Innovation Studio, they are identified as Other Foundation data type and Person
Additional Information category.
The following image is an example of filter configuration for CTM:People form:

Task 3: To create Remedy ITSM Sync Extension Process

If there are any changes to the custom Foundation data, you must create a process in BMC Helix Innovation Studio
Process designer with actions to create, update, or delete a record. This ensures that after custom Foundation data is
synchronized, the data is added to relevant record definition in BMC Helix Innovation Suite and then becomes available
for use in the business logic. For example, if the Passport Number is added for an Employee In Remedy ITSM, create a
process to upload this newly-added data to the Person record definition in BMC Helix Innovation Studio. For the steps to
create a customer extension process, see Creating or modifying record instances using Record Service Tasks (see page
457).
Consider the following points points when you create an extension process:
When adding variables in the process, ensure that you copy the input variable IDs of the fields that you want to
synchronize. For more information, see To add process variables (see page 425).
Example of customer extension process
The following image is an example of a custome extension process that is used to create, update, or delete a record
definition:

When adding or removing fields for an element in the process, ensure that you select the GUID field so that it
matches with the GUID in Remedy ITSM. If you do not select the GUID field, a new GUID is generated
automatically and data is not synchronized correcttly.
Task 4: To specify the Remedy ITSM Sync extension process for appropriate custom data
If there are any changes to the custom Foundation data, specify the process that must be triggered to load the updates
to BMC Helix Innovation Studio. For example, if the Passport Number is added for an Employee In Remedy ITSM, create a
process to upload this newly-added data to BMC Helix Innovation Studio and specify Passport Number as Other type of
Foundation data.
1. Log in to BMC Helix Innovation Studio as an administrator.
2. Click Administration> Foundation Data > ITSM Foundation Data SYNC > Extension Processes.
3. On the Add Customer Extension Process, provide the following information:
Other Data Specify the same category for the custom Foundation data that you provided for the filters.
Type
For example, when the Passport Number and SSN fields are loaded to BMC Helix Innovation Studio, they are identified as Other Foundation data
type and Person Additional Information category.
Bundle ID Enter the fully qualified application bundle name in which the extension process is created.
Process to Enter the fully-qualified name of the Foundation process that must be triggered after the custom Foundation data is loaded to BMC Helix
Start Innovation Studio.
For example, on the audit entry, if the Foundation object category is Other, trigger the Additional Process Information process.
The following image is an example of specifying the extension process created for Person Additional Information type of
Foundation data:

After the changes to custom Foundation data are loaded from Remedy ITSM, you can view the synchronized Foundation
data.

Connecting the Foundation data repositories (see page 725)
Connecting the Foundation data repositories

To ensure that Foundation data from Remedy ITSM is loaded to BMC Helix Innovation Suite, you must connect the
repositories by specifying the source (Remedy ITSM) and target ( BMC Helix Innovation Suite) Foundation library details
in Remedy ITSM.
Note
page 692).
Before you begin
Ensure that you have downloaded the deployment package and imported the files. For more information, see
Installing the BMC Helix Innovation Suite sync utility for Remedy ITSM (see page 700)
If you want to load custom Foundation data, ensure that you have completed the following tasks:
Extended the Foundation data definitions (see page 704) to include custom fields from Remedy ITSM.
Created a Pentaho job to load custom Foundation data (see page 710).
Configured Remedy ITSM for Foundation data synchronization (see page 721).
Passwords are always migrated from Remedy ITSM to BMC Helix Innovation Suite. If the password strength does
not match the BMC Helix Innovation Suiteguidelines, all associations to Person Foundation data will break in BMC
Helix Innovation Suite. Additionally, the following error message is displayed:
[ERROR (306): Value does not fall within the limits specified for the field; (Field ID - com.
bmc.arsys.rx.foundation:Person <123>, Maximum length - 30)]
You can choose to ignore the password policy enforcement in BMC Helix Innovation Suite by configuring the
following setting in the Centralized Tenant Configuration of BMC Helix Innovation Studio:
Enforce-Password-Policy = F

For information about how to modify the centralized tenant configuration settings, see Updating centralized
tenant configuration settings (see page 756) .
To connect the Foundation data repositories

For information about how to access the IT Service Management console, see Accessing and navigating the
interface .
2. From Applications menu on the IT Home page, select Administrator Console > Application Administration
Console.
3. Select Custom Configuration > Foundation > Innovation Suite > Configure Foundation SYNC.
4. Expand STEP 1 - Configure/Enable Foundation SYNC, and enter the following information:
Field Description
Source (ITSM Foundation) section
AR Server Name Enter the Remedy AR System server name, that was provided in the AR Server configuration file ar.conf. This file is
available after BMC Remedy AR System is installed at the following location:
Program Files\BMC Software\ARSystem\Conf\
TCP Port Enter the Remedy AR System server TCP port number. If you do not want to use any port number, enter 0.
RCP Port Enter the Remedy AR System server RPC port number. If you do not want to use any port number, enter 0.
AR User Enter the Remedy AR System server administrator's user ID.
Atrium Log Level (for Select Minimal so that the logging processes do not affect the server performance.
Atrium Initial Loads) Warning: If you select Detailed Row Level, it can cause server performance issues and Pentaho memory issues.
Target (IS Foundation) section
Configure Manually (Remedy ITSM version 9.1 SP3 only)

If you have enabled and configured the Cognitive Connection settings, select the Configure manually check box to
manually provide the BMC Helix Innovation Suite details.
Use Cognitive Connection This option is not supported for loading and synchronizing Foundation data from Remdy ITSM to BMC Helix Innovation
Suite .
URL This field is autopopulated if you selected the Use Cognitive Connection check box.Enter the HTTP or HTTPS path of
BMC Helix Innovation Suite, such as http://serverA:8008.
Note: Do not enter an extra slash ( / ) at the end.
Tenant Admin User This field is autopopulated if you selected the Use Cognitive Connection check box.
Specify the administrator user name for logging in to BMC Helix Innovation Suite.
Tenant Admin Password This field is autopopulated if you selected the Use Cognitive Connection check box.
Specify the administrator password for logging in to BMC Helix Innovation Suite.
Status To permit the Foundation data load, click Enabled.
The following image shows the completed STEP 1 - Configure/Enable Foundation SYNC settings:

5. Click Save.
The Foundation data repositories are connected and you can start the initial load of Foundation data from Remedy ITSM.

Loading and verifying Remedy ITSM Foundation data (see page 727)
Loading and verifying Remedy ITSM Foundation data

After completing all the steps in Phase 1: Preparing to load Foundation data from Remedy ITSM (see page 278), you can
load and verify Remedy ITSM Foundation data in BMC Helix Innovation Suite. You must load the Foundation data in the
following sequence:
1. Load and verify Foundation data
2. Load and verify Foundation associations
3. Load and verify custom Foundation data
This topic describes the tasks to load and verify Foundation data.
Note
page 692).
Best practices
Although you can select multiple files for processing, BMC recommends that you load one Excel
spreadsheet at a time.
The data load operation is memory intensive. Any uploads that run longer than one hour are not
processed. However, you can run the data load jobs for similar type of Foundation data at the same
time. The processing will be slower, but the data load is not impacted because the Foundation data

belongs to the same data type.

For example, you can start a data load for Location data simultaneously to include Location, product
categories, service categories, and support group data.
All Foundation data is processed from Excel spreadsheets in chunks of 100 rows.
If there is any error in any one of the 100 rows, each remaining row from the chunk is processed
individually.
Task 1: To load the Cities Foundation data

You must load the City Foundation data in BMC Helix Innovation Suite before loading the Foundation data from Remedy
ITSM. The cities are not loaded to BMC Helix Innovation Suite during initial data load, and will display blank values.
If there is any Foundation data that uses Geography data for cities, you must first load the cities Foundation data in BMC
To load the Cities Foundation data, perform the following tasks:
1. Download the All Cities.xlsx or Sample Cities.xlsx template spreadsheet (see page 685).
2. Update the spreadsheet with Foundation data.
3. Upload the updated spreadsheets (see page 686).
4. Run the data load process (see page 688) from BMC Helix Innovation Studio.
Task 2: To start the initial data load from Remedy ITSM

The Foundation data is loaded in the following order: 1) Company, 2) Person, 3) Location.
2. From the Applications menu on the IT Home Page, select Administrator Console > Application Administration
Console.
3. From the Application Administration Console, select Custom Configuration > Foundation > Innovation Suite >
Configure Foundation SYNC.
4. In the STEP 2 - Initial Load (Core Foundation Data) area, click Start Initial Data Sync.
The ITSM Foundation data is transferred to Microsoft Excel spreadsheets, and these spreadsheets are uploaded
to BMC Helix Innovation Suite. The time it takes to generate the Excel spreadsheets is dependent on the volume
of Remedy ITSM Foundation data.
Note
Each Excel spreadsheet can contain up to 50,000 Foundation data records. If a spreadsheet contains
more than 50,000 Foundation records, a new Excel spreadsheet is automatically created with the
remaining Foundation data, such as CompaniesCustomer_0, CompaniesCustomer_1, and so on.
The following image shows an example of starting the initial load of Foundation data from Remedy ITSM:

Task 3: To verify that all Excel spreadsheets are uploaded to BMC Helix Innovation Studio
2. On the Workspace tab, click the Data Management Console application.
3. Click Visit Deployed Application > Data Load.
The Excel spreadsheets are displayed in the Data Load Input column. Click Refresh to view the latest Excel spreadsheets.
Task 4: To start the initial data load from BMC Helix Innovation Studio
4. Select the Excel spreadsheet that you want to process, and click Run Data Load to trigger the data load process.
You must trigger the data load in the following sequence: 1) Company data, 2) Person data, 3) Location data
All the Foundation data is processed from Excel spreadsheets in chunks of 100 rows. If there is any error in
any one of the 100 rows, each remaining row from the chunk is processed individually.
After the data load is completed, the processed spreadsheets are displayed in the Data Load Result column in the Data
Management Console, and the processing status is displayed in the Status column beside each spreadsheet.
The following table provides a few samples of processed spreadsheets:
Foundation data Processed spreadsheet
Location Processed-Location_0.xlsx
Organization Processed-Companies_0.xlsx

Foundation data Processed spreadsheet
Person Processed-Person Data.xlsx
Task 5: To confirm that out-of-the-box Foundation data is loaded successfully to BMC Helix Innovation Studio
1. In BMC Helix Innovation Studio, click Workspace > Data Management Console > Visit Deployed Application.
2. From the Data Load Result column, click the Download icon beside the spreadsheet that displays Processed
with Errors status.
In the spreadsheeet, the Data Load Result column contains the status spreadsheet that is automatically created
for every load process.
Note
If the Foundation data is not processed and displays an Errored status, resolve the issue by peforming
the workaround steps specified in Troubleshooting Foundation data issues (see page 989).
The following image displays an example of a processed spreadsheet:
3. In the IT Service Mangement Console, select the Data Loaded and Verified check box.
Task 6: To confirm that Foundation data is loaded successfully to BMC Helix Innovation Studio
You must confirm that Foundation data is successfully loaded by verifying that the trasaction audits are processed.
1. In BMC Helix Innovation Studio, click Administration > Foundation Data > ITSM Foundation Data SYNC >
Transaction Audits.
2. On the ITSM Synchronized Foundation Data page, filter the grid by Status: Unprocessed.
Wait till all the transaction audits are processed.
The following image shows an example of Foundation data that is synchronized to BMC Helix Innovation Studio:

You must proceed to load Remedy ITSM Foundation associations only after verifying that the out-of-the-box and custom
Foundation data is loaded successfully.

Loading and verifying Remedy ITSM Foundation associations (see page 731)
Loading and verifying Remedy ITSM Foundation associations

After completing all the steps in Phase 1: Preparing to load Foundation data from Remedy ITSM (see page 278) and
loading and verifying Remedy ITSM Foundation data (see page 727), you can load existing Remedy ITSM Foundation
associations for the first time and verify that the Foundation associations are loaded in BMC Helix Innovation Studio.
Note
page 692).
Best practice
When you load Foundation associations for the first time, BMC recommends that you run the data load jobs
one at a time. Because there can be multiple associations being loaded to the same Foundation data and
running data load jobs simultaneously can cause errors in associations.
For example, do not run the data load of Person to Home Site association and Person to Primary Site
association simultaneously, because they are direct associations to Person Foundation data.
Task 1: To start the initial associations load from Remedy ITSM
2.
2. From the Applications menu on the IT Home Page, select Administrator Console > Application Administration
Console.
3. From the Application Administration Console, select Custom Configuration > Foundation > BMC Helix Innovation
Suite > Configure Foundation SYNC.
4. In the STEP 3 - Initial Load (Core Foundation Associations) area, click Start Initial Association Sync.
The ITSM Foundation associations are populated into Microsoft Excel spreadsheets, and the spreadsheets are
uploaded to BMC Helix Innovation Suite. The time it takes to generate the Excel spreadsheets is dependent on
the volume of ITSM Foundation associations.
Note
Each Excel spreadsheet can contain up to 50,000 Foundation association records. If a spreadsheet
contains more than 50,000 Foundation association records, a new Excel spreadsheet is automatically
created with the remaining Foundation associations, such as ProductCatalogAssociations_0 ,
ProductCatalogAssociations _1 , and so on.
The following image shows an example of starting the initial load of Foundation associations from Remedy ITSM:
Task 2: To verify that Excel spreadsheets are uploaded to BMC Helix Innovation Suite

Task 3: To start the initial associations load from BMC Helix Innovation Studio
4. Select an Excel spreadsheet that contains Foundation associations and click Run Data Load to trigger the data
load process.
After the data load is completed, the processed spreadsheets are displayed in the Data Load Result column in the Data
Management Console, and the processing status is displayed in the Status column beside each spreadsheet.
The following file is a sample processed Person associations spreadsheet: Processed-Person Associations.xlsx (see page
731)
Task 4: To verify that associations are loaded to BMC Helix Innovation Studio
with Errors status.
In the spreadsheet, the Data Load Result column contains the status spreadsheet that is automatically created for
every load process.
Note
If the Foundation data is not processed and displays an Errored status, resolve the issue by performing
workaround steps specified in Troubleshooting Foundation data issues (see page 989).
The following image displays an example of a processed spreadsheet that is created automatically after the
processing is completed:

3. In IT Service Mangement Console, select the Associations Loaded and Verified check box.
Task 6: To confirm that Foundation data associations are loaded successfully to BMC Helix Innovation Studio
1. In BMC Helix Innovation Studio, click Administration > Foundation Data > ITSM Foundation Data SYNC >
Transaction Audits.
2. On the ITSM Synchronized Foundation Data page, filter the grid by Status: Unprocessed.
Wait till all the transaction audits are processed.
The following image shows an example of Foundation data that is synchronized to BMC Helix Innovation Studio :
If you want to load custom Foundation data, you must proceed only after verifying that the out-of-the-box and custom
Foundation data associations are loaded successfully.

Action Reference
If you want to load custom Foundation data Loading and verifying custom Remedy ITSM Foundation data (see page 735)

Action Reference
If you do not want to load custom Foundation data Viewing the synchronized Foundation data (see page 737)
Loading and verifying custom Remedy ITSM Foundation data

After you load and verify the Foundation associations (see page 731), you can load the custom Foundation data from
Remedy ITSM for the first time.
Note
You can load custom Foundation data from Remedy ITSM Suite version 9.1 SP3 or later. For a complete list of
page 692).
Before you begin

Before you start loading custom Remedy ITSM Foundation data to BMC Helix Innovation Suite, ensure you have
completed the following tasks:
Extended the existing Remedy ITSM Foundation definitions (see page 704) to include the custom Foundation
data fields.
Created a Pentaho job and transformations in Remedy ITSM (see page 710), so that the custom Foundation data
is identified, read, and loaded to BMC Helix Innovation Suite for processing.
Configured the synchronization of custom Foundation data changes (see page 721), so that these changes are
automatically synchronized with BMC Helix Innovation Suite.
Task 1: To start the initial data load from Remedy ITSM
2. From Applications menu on the IT Home Page, select Administrator Console > Application Administration
Console.
3. From the Application Administration Console, select Custom Configuration > Foundation > Innovation Suite >
Configure Foundation SYNC.
4. From STEP 4 (Optional) - Load Custom Data area, select the newly-created Pentaho job and click Start Initial
Data Sync.
The ITSM Foundation data is transferred to Microsoft Excel spreadsheets, and these spreadsheets are uploaded
to BMC Helix Innovation Suite. The time taken to generate the Excel spreadsheets depends on the volume of
Remedy ITSM Foundation data.
Note

Each Excel spreadsheet can contain 50,000 Foundation data records only. If a spreadsheet contains
more than 50,000 Foundation records, a new Excel spreadsheet is automatically created with the
remaining Foundation data.
The following image shows an example of starting the initial load of custom Foundation data from Remedy ITSM:
Task 2: To verify that Excel spreadsheets are uploaded to BMC Helix Innovation Studio
Task 3: To start the initial data load from BMC Helix Innovation Studio
4. Select an Excel spreadsheet that you want to process and click Run Data Load to trigger the data load process.
After the data load is completed, the processed spreadsheets are displayed in the Data Load Result column of Data
Management Console.

Task 4: To confirm that Foundation data is loaded successfully to BMC Helix Innovation Studio
with Errors status.
In the spreadsheet, the Data Load Result column contains the status spreadsheet that is automatically created for
every load process. All the Foundation data is processed from Excel spreadsheets in chunks of 100 rows. If there
is any error in any one of the 100 rows, each remaining row from the chunk is processed individually.
If the Foundation data is not processed and displays an Errored status, resolve the issue by performing
workaround steps specified in Troubleshooting Foundation data issues (see page 989).
3. In IT Service Management Console, click Confirm Load OK as shown in the following image:

Viewing the synchronized Foundation data (see page 737)
Viewing the synchronized Foundation data

After you load the Foundation data (see page 727) and associations (see page 731) from BMC Remedy IT Service
Management (Remedy ITSM), you can view the Foundation data that is synchronized to BMC Helix Innovation Suite. All
changes made to BMC Remedy ITSM Foundation data are synchronized with BMC Helix Innovation Suite, regardless of
whether the data is in online or offline state. The Foundation data, that is loaded from Remedy ITSM, is locked for editing
and cannot be modified in BMC Helix Innovation Suite.
Note

You can load and synchronize Foundation data from BMC Remedy ITSM version 9.1 SP3 or later. For a
complete list of compatible Remedy IT Service Management versions, see Foundation data load compatibility
information (see page 692).
To view the synchronized Foundation data

You can view the synchronized Foundation data from BMC Remedy IT Service Management Console.
In the IT Service Mangement Console, expand Monitor Data Updates.

The Summary column displays a list of Foundation data that must be synchronized, and the Transfer Status column
displays the synchronization status.
The following image shows an example of Foundation data changes that are synchronized to BMC Helix Innovation
Studio:
This is the final step in the process of loading Foundation data from Remedy ITSM (see page 278) to BMC Helix
Innovation Suite.
Common tasks after synchronizing Foundation data

After verifying the synchronized Foundation data from Remedy ITSM Suite to BMC Helix Innovation Suite, the
Foundation data is locked for editing and cannot be modified. However, you can leverage the data to create new data,
extend existing data, or modify associations between the data.
The following table explains the common tasks that administrators might want to perform after loading data from
Remedy ITSM:
Task Reference
You can create a new child support group by following the instructions in To create
secondary organization (see page 663).

Task Reference
To create a new support group for a Primary organization of

type Operating Organization that is brought over from Remedy
ITSM.
To create a new support group for a Primary organization of

type Service Provider that is brought over from Remedy ITSM.
You can assign an agent to the newly created support group by creating a direct or
To assign an existing agent from Remedy ITSM to a newly
indirect affiliation between the agent and the support group (see page 677).
created support group in BMC Helix Innovation Suite.
You can create new customers by following the instructions in To create person
To add new customers for an existing Primary organization of
data (see page 664).
type customer that is brought forth from Remedy ITSM.
Related topics
Synchronizing custom Foundation data changes to BMC Helix Innovation Suite (see page 721)
Addressing data privacy requests

The BMC Helix Innovation Suite product provides capabilities that help administrators address the personal data
protection and privacy requirements associated with the General Data Protection Regulation (GDPR). The GDPR is a set
of rules and principles governing the handling of personal data of individuals located in the European Union (EU).
Note
This BMC document provides general information about the General Data Protection Regulation (GDPR) and
GDPR key requirements. It is not intended to provide any legal advice. The GDPR can be found at https://ec.
europa.eu/info/law/law-topic/data-protection_en. Under this new Regulation, any organization handling
personal data of European Union residents, regardless of its location, needs to understand which GDPR
requirements apply to its organization and accordingly devise a plan for adjusting its systems and processes
and for educating its people. Although BMC is not in the business of data privacy compliance software, some
of the features of the BMC Helix Innovation SuiteBMC Helix Innovation Suite product can help customers
meet some requirements of the GDPR. For more information about how BMC solutions can help achieve the
requirements of GDPR, see https://www.bmc.com/it-solutions/gdpr-compliance.html .
Personal data in BMC Helix Innovation Suite

BMC Helix Innovation Suite applications may include users' personal data such as names, phone numbers, email
addresses, government ID numbers, locations, credit card numbers, IP addresses, and so on that can identify individuals
personally.
Personal data in BMC Helix Innovation Suite log files

BMC Helix Innovation Suite retains the data in log files for a limited period of time and then the log files data is deleted
from the BMC cloud.

Personal data used by the BMC Helix Innovation Suite Cognitive Service
BMC Helix Innovation Suite deletes all the conversation logs from the BMC cloud once a week.
For information about the log limits in IBM Watson Assistant (formerly known as IBM Watson Assistant), see Log limits
in the Watson documentation.
For information about IBM Watson GDPR readiness, see GDPR in the Watson documentation.
Capabilities for handling personal data

BMC Helix Innovation Suite provides an administrator the following capabilities to protect user's personal data:
Perform a lookup to find whether any personal data of a user is stored in applications.
Provide a user with their personal data in a safe way.
Replace users' personal data permanently in the applications.
On behalf of a user, an administrator can perform the following operations on user's personal data:
Operation Description
Search Searches for the user's personal data available in applications and provides a report of the search data. An administrator can download and
send this data to the user in a portable and standard format such as .csv file format. The search operation is performed on structured and
unstructured data.
To enable search operation for structured data, for example, JSON and HTML, the SaaS administrator must configure the content-
definition setting by providing the following value:
{"formName":"<name>","fieldName":"<field>","fieldFormat":"<JSON>/<HTML>/<TEXT>"}
If the content-definition setting is not configured, then the search is performed on the fields with datatype as Text and CLOB (character
large object).
Replace Replaces the user's personal data. The data is not deleted; however, it is replaced with a non-readable information permanently. The replace
operation is performed only on the fields with datatype Text and CLOB.
Ignore Ignores a record during a replace operation.
You can exclude any personal data from getting replaced. The ignored records are not replaced.
You must consider the following points while performing operations on personal data:
You need to perform these operations in each environment separately such as development, QA, and production
environments.
You cannot modify or search for the personal data stored in the following components:
Attachments stored along with records instances
Process definitions
Localized strings
You must not replace the login ID of a user.
To search for personal data

2. Select General > Data Requests.
3. On the Data Requests page, click New to search for user's personal data.
4. In the New Search and Replace Request section, enter the values for the following fields:
Field Description
Label Enter the label of the personal data that needs to be searched such as name, email ID, and so on.
Search String Enter the personal data that the requester wants to search, such as John Smith, john.smith@gmail.com, and so on.
Replace With Enter the value with which you want to replace the search string data.
Note: If you leave the field blank, the value in the Search String is replaced with GUID.
Add Search Data Use this option to add more personal data to search.
Comments Enter comments.
After you submit a request, the request is displayed on the Data Requests page and the status of request is
updated to Created. After the request is completed, the status is changed to Search Completed.
5. Click Save.
You can view the search results by clicking the Request ID. The Request Details page displays the details for Submitter,
Status, Search String, and Notes along with the search results.
The following image shows an example of the search results:
To download personal data

After you perform a search operation on the personal data, you can download the data so that you can send the data to
the user.
3. On the Data Requests page, select the Request ID of the search request that you performed earlier, and click
Download Search Results.

The personal data is download in the CSV file format.
To replace personal data
3. On the Data Requests page, select the Request ID of the search request that you performed earlier, and click
Replace.
The status of the request is changed to Replace In Progress. After the request is completed, the status changes to
Replace Completed.
GDPR request status

A GDPR request may have any of the following statuses depending on the request conditions:
Request status Description
Created Search request or replace request is created
In Progress Search request is in progress.
Search Completed Search request is completed.
Replace In Progress Replace request is in progress.
Replace Completed Replace request is completed.
Search Failure Search request failed.
Replace Failure Replace request failed.
Replace Completed With Error Replace request is completed but some errors were encountered during the process.
Managing user access and permissions

An administrator performs the following tasks to setup user accounts and grant access to manage and maintain the
system.
Action Reference
Understand the roles and permissions level for each role. Roles and permissions (see page 743)
After you define application roles, grant a person record permission to perform tasks in multiple Creating Functional roles (see page 744)
applications by grouping a collections of application roles into a functional role.

Action Reference
Define application roles and map them to explicit groups Creating and modifying application roles (see page
749)
Define the administrators or application business analysts Creating administrators and application business
analysts (see page 747)
Roles and permissions

BMC Helix Innovation Suite supports several different roles, each with its own goals and responsibilities.
The following table describes capabilities for each role.
Role Responsibilities
Administrator
Creates and manage users and user access permissions.
Creates and deploy codeless applications or libraries in tailoring, test, or production environments.
Addresses the personal data protection and privacy requirements associated with the General Data Protection
Regulation (GDPR).
Sets the foundation data and load bulk foundation data.
Provides licenses to users.
Integrates applications with Approval library.
Configures applications and services; for example, Cognitive Service, connectors, chatbot.
Submits user reported issues to BMC Customer Support.
Application Business Analyst

Tailors applications and libraries, for which they have access to, so that they are custom suited to specific needs.
However, cannot modify the Foundation data or deploy applications to other environments.
Defines any process automation required to improve the quality of services delivered to the stakeholders.
Configures and customize applications by using visual designers without writing any code.
Developer
Creates bundle projects, defines core definitions for the bundles, creates additional custom application code.
Builds code-based applications and libraries.
Runs automated tests of the application code by using the development tools.
Leverages BMC Helix Innovation Studio to build definitions that can be used by the applications and libraries.
Uses Java, JavaScript, Angular JS, HTML, or CSS to extend the BMC Helix Innovation Suite framework.

Action Reference
To understand the goals for these roles and the capabilities provided by BMC Helix Innovation Suite to each role. User goals and features (see
page 275)
To understand the concepts related to Digital Service applications, how to start with application development, and the Key concepts (see page 36)
recommended process to develop applications.

Creating Functional roles

To provide a person with access to one or more applications, administrators create and assign a functional role (see
page 45) to a person record.
Functional role use case
Scenario
Consider a scenario where Chris, the Change Assignee uses the Change Management application to issue and
resolve a change ticket. Along with Change Management application Chris uses the following applications to
issue and resolve the ticket:
Knowledge Management, to refer to an existing knowledge article to resolve the issue, or create a new
Knowledge article for future use.
Service Level Management, to provide correct level of service to meet the need of the issue.
Chris, therefore, requires permissions to these applications to resolve a ticket. The administrator creates a
functional role for Chris which enables Chris to perform his tasks.
The following table explains the tasks involved in creating a functional role for Chris:
Task Description Reference Example
1 Before you create the functional role, Creating and Define the following appliction roles with these associated permission levels:
define the permissions if each deployed modifying
Change Management
application by creating application roles. application roles
(see page 749) Change Read
Change Write
Change Admin Write
Knowledge Management
Knowledge Read
Knowledge Write
Service Level Management
SLM Read
SLM Write
2 Create a functional role to grant Create a To resolve a ticket using Change Management, Chris requires access to applications
permission to the person to access and functional role like Knowledge Management and Service Level Management and should have all the
use the applications. (see page 745) necessary permissions to perform the tasks on these applications.
Create Change Manager functional role which is a collection of all the following
roles:
Change Write
Change Admin Write
Knowledge Write
SLM Write

Task Description Reference Example
3 Assign the functional role to the person. Assign a functional Assign the Change Manager functional role to Chris. This enables Chris to easily
role to a person access and use the applications with all of the required permission levels.
(see page 745)
When you create a functional role and assign it to a person, the server performs certain tasks. For more information, see
Server behavior (see page 745).
To create a functional role
1. Log in to BMC Helix Innovation Studio, navigate to the Administration tab, and select Configure My Server >
Application Permissions > Manage Functional Roles to open the Functional Roles UI.
2. Click New to add a new role and perform the following actions:
Field Action
Application Enter the name of the deployable application for which you are defining a functional role.
Name
Role Name Enter a unique name for the functional role.
Description Enter a description for the functional role.
Select Role Select the application roles that you want to combine into one functional role. The Selected Role section displays the list of
application roles from multiple applications.
3. Click Save.
You can also update (modify) or delete the functional roles using the Functional Roles UI.
To assign a functional role to a person
1. In BMC Helix Innovation Studio, navigate to the Administration tab, select Foundation Data > Manage People.
2. Select the appropriate person type: Employees, Agents, Customers, or Vendors.
3. Select the person record for which you want to add the functional role and click Edit.
4. From the Functional Roles field select the appropriate functional role.
5. Click Save.
Server behavior
When you create, update, or delete functional or application roles, or when you export or deploy your applications, the
server automatically performs certain tasks. After every action the server rebuilds the group list and updates the user
record.
The following table provides the details:
Action Role Tasks performed by the server
Create Functional
Creates a new group for the corresponding application role, if the application role is not mapped to any group.
role

By default, the groups are named after the application role name. For example, Change Read.
However, if the group name already exists, the group is named using a combination of application name and
application role name. For example, ChangeManagementChangeRead.
Maps application roles to corresponding groups.
If one application role is added to multiple functional roles, the mapping between application role and group is
created only for the first instance.
Identifies the person record associated with functional role and updates the group list for the corresponding user record.
Application
role
Update Functional
(modify) role
Identifies the person record associated with functional role and updates the group list for the corresponding user
record.
Updates the groups mapped to the application roles.
Application
Updates the group list for user records associated to the functional role.
role
Delete Functional
role
Application
role
If a new group was created automatically by the server, the group is not deleted even after the application role is deleted.
This group is reused, if you create an application role with same name later. You can manually delete the unwanted groups.
For more information, see Creating and managing groups.
Export Application
Exports functional role associated with that application in its bundle as schema data.
During Application
Creates or updates application roles.
deploy
If an application role is added to a functional role, server performs the following tasks:
Identifies the person record associated with functional role and updates the group list for the corresponding user
record.
After Application
Creates or updates functional role on the target system.
deploy

Identifies the person record associated with functional role and updates the group list for the corresponding user record.
Creating administrators and application business analysts

A user is any person to whom you give permission to access BMC Helix Innovation Studio. To cater to specific user goals
and help users achieve them, BMC Helix Innovation Studio provides a few roles such as the following:
Administrator: Creates and manage users and user access permissions.
Application business analyst: Modifies application definitions within applications and libraries for which they have
access.
You can assign the user role while creating users or while updating existing users. For more information about the user
roles, see Roles and permissions (see page 743) and User goals and features (see page 275).
To assign administrator role to a user
2. Select Foundation Data > Manage People.
3. To add a user of type agent, click Agents. To add a user of type employee, click Employees.
When assigning administrator role to a new user

a. Click New.
b. On the Access Details tab, click Tenant Admin to specify the user as an administrator.
c. Click Save.
When assigning administrator role to an existing user

a. Select the user and click Edit.
b. On the Access Details tab, click Tenant Admin to specify the user as an administrator.
c. Click Save.

4. Click Save.
To assign application business analyst role to a user
2. Select Foundation Data > Manage People.
3. To add a user of type agent, click Agents. To add a user of type employee, click Employees.
When assigning application business analyst role to a new user

a. Click New.
b. On the Access Details tab, click Application Business Analyst .
When assigning application business analyst role to an existing user

a. Click New.
b. On the Access Details tab, click Application Business Analyst .
Note
You will be able to select Application Business Analyst, only if you do not select Tenant Admin
role for a user.
4. From Bundle Access, select the bundles that the application business analyst can access and tailor.
5. From Access Details tab, select BMC Helix Innovation Suite User Named license from Application Licenses.

5.
6. Click Save.
The user with application business analyst role can log in to BMC Helix Innovation Studio and can access and tailor the
bundle for which the user has permissions.
Creating and modifying application roles

Application Roles (roles) are permissions similar to groups, except that they belong to a particular application, instead of
a particular server. Application roles are used exclusively in deployable applications.
Application roles are defined for each deployable application and then mapped to explicit groups on the server. You can
map a deployable application's roles to different groups on different servers, depending on how the groups are defined
on each server. This allows you to develop and test the application on one server and deploy it to a number of other
servers without having to redefine permissions on each server. You can also map application roles to different groups for
each development state, such as Test or Production.
Because application roles are mapped to groups, the groups you define on the server and the users that belong to them
are the foundation of access control.
Use the Manage My Roles UI to create application roles to which you grant or deny access to objects in deployable
applications. In deployable applications, you assign permissions using implicit groups (including dynamic groups) and
roles. You then map roles to explicit groups on the server. This section provides the steps to create application roles and
map them to explicit groups.

To create an application role
2. Click Configure My Server > Application Permissions > Manage Role Permissions to open the Manage My Roles UI.
3. Click New to add a new application role and enter information in the appropriate fields as described in the Role
form fields (see page 750) table.
4. Save your changes.
To manage application roles
To modify an application role:
1. From the Mange My Roles UI, select the name of the role that you want to edit from the Role Name field.
2. Enter information in the required fields and save your changes.
To delete an application role:
1. Open the Mange My Role UI.
2. Select the role and click Delete.
Fields in the Role Information form

Field Description
Application Enter the name of the deployable application for which you are defining an application role. You can define the same role for multiple
Name applications.
Role Name Enter a unique name for the application role. Within each application, every role name should be unique. You can reuse the same role name-role
ID pairs across a suite of applications.
Role ID Integer ID that is the recognized identity of the role. The ID must be a negative number, such as -10001. Role IDs must be unique for each
application name. You can reuse the same role name-role ID pairs across a suite of applications.
Test Enter or select one group name for the regular or computed group to which you want to map this role for the Test application state. To enable
this mapping, set the application's State property to Test.
Production Enter or select one group name for the regular or computed group to which you want to map this role for the Production application state. To
enable this mapping, set the application's State property to Production.
Configuring incoming and outgoing email

You can configure the incoming and outgoing mailboxes, and templates. You can use several attributes from the
incoming mailbox when creating rules or processes that run when an email is received. You can use the default outgoing
mailbox configuration to send email notifications when certain events take place. For more information, see Automating
tasks through emails (see page 289). You can also configure multiple outgoing profiles to send email notification to
multiple lines of business. You can use the attributes of a template when you want to send a notification to the users by
using the Send Message by Template element (see page 470) in the Process designer.
This topic provides the steps to configure incoming and outgoing mailboxes, configure outgoing profiles, and to create
templates.

To configure incoming mailboxes

You can use the incoming mailbox configuration to trigger a rule when an email is received in the configured mailbox.
The rule can be used to run a process, such as the process to create a case.
2. Select Configure My Server > Email > Incoming Mailbox.
3. Click New.
4. Fill out the field in the Basic Configuration tab.

Fields in the Basic Configuration tab and their descriptions
Field name Description
Mailbox Name Type the incoming mailbox name that describes the function of the mailbox.
Example: Calbro helpdesk - incoming
Status Select one of the following values:
Enabled—If you want to activate the mailbox.
Disabled—If you do not want to activate the mailbox.
Email Server Type Select one of the following server types:
POP3
IMAP4
Note: MAPI and MBOX server types are not supported.
Polling Interval (Minutes/ Enter the number of minutes after which the email engine will check for incoming emails for this mailbox. The
Seconds) minimum value is 1.
Email Server required SSL Select the options if you want to enable or disable the Secure Socket Layer.
Email Server Port Type the port number that is used to connect to the mail server according to the email server type that you
selected earlier.
Email Server Name/ IP Type the name or IP address of your email server.
Email Server Password Type the password of the administrator or user for this email server.
Email Server User Type the email address of the user for this email server.
Associated Mailbox Name Select the name of the outgoing mailbox that is used to reply to incoming emails.
5. Save the settings.
To configure outgoing mailboxes

You can use the outgoing mailbox configuration to send an email notification or to send a reply to recipients by email.
The outgoing mailbox configuration is used to run a process that contains the Send Message element. For example, you
can use the outgoing mailbox to send an email notification when a ticket is created.
Note
Only SMTP server type is supported for outgoing mailboxes.
1.
2. Select Configure My Server > Email > Outgoing Mailbox.
3. Click New and fill out the following fields:
4. Fill out the Basic Configuration fields:

Fields in the Basic Configuration tab and their descriptions
Mailbox Name Type the outgoing mailbox name that describes the function of the mailbox. The mailbox name is displayed as the From
email address to the recepients.
Status Select one of the following values:
Enabled—If you want to activate the mailbox.
Disabled—If you do not want to activate the mailbox.
Email Server User If the email server requires authentication information before sending an email, type the email account user name.
Polling Interval (Minutes/ Enter the number of minutes after which the email engine will check for outgoing mails.
Seconds) The minimum value is 1.
Email Server Port Type the port number that is used to connect to the mail server.
Email Server Name/ IP Type the name or IP address of your email server.
Email Server required SSL Select the values to enable or disable the Secure Socket Layer. This field can be enabled only for the POP3 and IMAP4
email server type.
Email Server Password Type the password of the administrator or user for this email.
Associated Mailbox Name Select the incoming mailbox that is used to receive replies to the outgoing emails.
Fields in the Advanced Configuration tab and their descriptions

Display Name Type a descriptive name for the outgoing mailbox. The display name appears in the <From:> field of the outgoing
emails.
Default outgoing Select the value to make the current outgoing mailbox as the the default mailbox to send all outgoing emails if any other
mailbox outgoing mailbox is not specified.
Note: You can set only one default outgoing mailbox.
Reply To Address If you want the outgoing email recipients to reply to the emails, specify the email address to which the replies must be
sent.
Email Address Type the email address of the server user. The email address appears in the <From:> fields of the outgoing emails along
with the display name.
Example: If the value in the Display Name field is BMC Helix Innovation Suite and the email address is
system@innovationsuite.com, the <From:> line is From: BMC Helix Innovation Suite.
Delete Outgoing Select the options if you want to delete or retain the outgoing emails from BMC Helix Innovation Suite after they are sent
Notification Messages from this mailbox.
Organization If your email client displays the organization name, type the name.
Fields in the Default Addressing tab and their descriptions

Field Description
name
Default If the recipient email addresses are not mentioned, type the default email addresses to which the outgoing email must be sent from this
To mailbox.
Default If the recipients for blind carbon copy of the outgoing email are not mentioned, type the default email addresses to which the blind
BCC carbon copies must be sent.
Default If the recipients for carbon copy of the outgoing email are not mentioned, type the default email addresses to which the carbon copy
CC must be sent.
5. Click Save.
To configure outgoing profiles

To use the outgoing profile, you must map the outgoing profile to your outgoing mailbox and use this outgoing profile in
your processes and rules to send email notifications to multiple lines of business, such as facilities, travel, legal, IT, and so
on. You can use outgoing profile to update the outgoing mailbox without the need to modify the existing processes and
rules.
Scenario
Consider a scenario where you use HR@calbro.com outgoing mailbox in multiple processes and rules to send
email notifications to the employees of Calbro Services. Now you want to update the outgoing mailbox based
on the geographic location, such as HR_India@calbro.com and HR_USA@calbro.com. Because of this change
you will now have to update the multiple processes and rules that used the HR@calbro.com outgoing mailbox.
To avoid this issue, an administrator can now map the outgoing mailbox to an outgoing email profile and use
this profile in the processes and rules. So that even after you update the outgoing mailbox, the processes and
rules remain unaffected and continue to send email notifications by using correct outgoing mailbox.
2. Select Configure My Server > Email > Outgoing Profile.
3. Click New.
4. In Profile Name, enter the name of the outgoing profile.
5. In Outgoing Mailbox, select the existing outgoing mailbox to which you want to map the outgoing profile.
6. In Application, select the application for which you want to use the outgoing profile.
7. Click Save.
After you create the outgoing profile, you can use the outgoing profile while designing a process or a rule (see page 470)
by using the Send Message and Send Message by Template actions in the Process and Rule designer.
Note

You need to create the outgoing profile only once. You do not need to recreate the outgoing profiles in each
environment. When you deploy your application across tailoring, QA, or production environments, you can
just map the existing outgoing profiles with the corresponding outgoing mailbox to send email notifications.
To configure templates
You can create text and HTML templates that can be used to send a message in the notification bell and email.
2. Select Configure My Server > Email > Templates.
3. In Template Name, enter the name of the template.
4. In Short Description, enter the purpose of the template.
5. In Template Attachment , select a .txt or .HTML fil e that you want to use as a template.
6. Click Save .
The template name is used when configuring (see page 470) the Send Message by Template element in the Process
designer.
Related topics
Defining a trigger for a rule (see page 495)
Sending a user message from a process (see page 470)
Configuring full-text search to refine the search results

After the application business analyst has enabled full-text search on fields (see page 336), as an administrator, you can
configure additional FTS settings to refine the search results.
This topic provides the list of FTS settings that you can configure, and provides the configuration steps.
FTS configuration settings and their descriptions

The following table describes the FTS configuration settings in BMC Helix Innovation Studio and provides example values
for each setting:
Configuration setting name Description Values
Full-Text-Case-Option Indicates whether full-text searching is case 0—Case sensitive (default)

sensitive. This setting affects all the FTS-
1—not case sensitive
enabled fields. Changes to this setting trigger
an automatic re-indexing.
Full-Text-Collection- Provides the location of the directory where Default location: <install directory>/arsystem/tenant
Directory the FTS index files are stored. /<tenant name> /ftsconfiguration/collection

Full-Text-Configuration- Provides the location of the directory where Default location: <install directory>/arsystem/tenant
Directory the FTS configuration files are stored. /<tenant name> /ftsconfiguration/conf
Example, configuration files for the words-to-

ignore and synonyms list.
Full-Text-Disable-Indexing Indicates whether the FTS server processes F— Do not disable indexing (Default).
pending indexing tasks.
T—Disable indexing. Pending indexing tasks are processed after indexing is
enabled.
Full-Text-Disable-Searching Indicates whether the BMC Helix Innovation F— Use the full-text search engine (Default value).
Suite server uses the full-text search engine.
T—Disable the full-text search engine.
Note: The database search capability continues to work even after the full-
text search engine is disabled.
Full-Text-Exclude-List Contains the extensions of files that must be Example: .pdf, .xml, .png, and so on.
excluded from full-text search.
Full-Text-Ignore-Word-List Contains words to be ignored during FTS. Articles (a, an, the), prepositions (in, on, from, front, beside), and so on.
Search results will not contain the words that
are added in this list. Press Enter to add a new word in this list.
Full-Text-Indexer-Log-File Gives the location of the directory where the Default location: <install directory>/arsystem/tenant
FTS index log files are stored. /<tenant name>/db
Full-Text-Match-Option Indicates how the FTS server modifies search 0—Force leading and trailing wildcards.
queries.
1—Ignore leading and force trailing wildcards.
2—Ignore leading wildcards.
3—Remove leading and trailing wildcards.
4—Leave query unchanged (Default value).
Full-Text-Synonyms Contains synonyms so that when the end user PC workstation laptop desktop computer
searches for any of these words, resources
related to its synonyms also appear in the slow sluggish
search results. bright shiny
Type a word followed by its synonyms separated by a space. Press Enter to

add a new list of synonyms.
MFS-Environment-Field- Defines the relevancy weight for the Default value: 1

Weight Environment field. This setting relates to the
fields for which the application business analyst
has defined the relevancy when Enabling full-
text search in an application (see page 335).
MFS-Keywords-Field- Defines the relevancy weight for the Keyword Default value: 2
Weight field. This setting relates to the fields for which
the application business analyst has defined the
relevancy when Enabling full-text search in an
MFS-Title-Field-Weight Defines the relevancy weight for the Title field. Default value: 4
This setting relates to the fields for which the
application business analyst has defined the
relevancy when Enabling full-text search in an
Full-Text-Reindex Initiates the re-indexing of all FTS-enabled 0 — Re-indexing is not performed. (Default)
fields.

1 — Starts re-indexing.
To configure FTS settings
2. Select Configure My Server > Centralized Configuration Settings > Centralized Tenant Configuration.
To configure a new setting, click Add Setting.
To edit a setting, select the checkbox that corresponds to the setting you want to edit and click Edit.
3. From the Setting Name list, select the FTS setting (see page 754) to be configured.
4. In Setting Value, provide the appropriate value (see page 754) for the selected setting.
5. Click Save.
Note
In a server group, if you configure the settings on one server, the configuration settings get updated in all
other servers in the server group.
Related topic
Enabling full-text search in an application (see page 335)
Updating centralized tenant configuration settings

Centralized tenant configuration refers to storing the tenant's configuration data at a common location that can be
accessed across multiple servers. T he Centralized Tenant Configuration ensures consistency by communicating changes
to the global properties across all the servers in a cluster. When a tenant-specific property is modified on one server, the
Centralized Tenant Configuration automatically sends the notification to other servers that have the same tenant added,
so that these configuration changes are also synchronized by each server in the same cluster.
The Centralized Tenant Configuration contains the configuration settings for the following components:
Approval

Assignment
Shared
To configure centralized tenant configuration settings
2. Select Configure My Server > Centralized Configuration Settings > Centralized Tenant Configuration.
3. From Component Type, select the component for which you want to configure the setting.
To configure a new setting, click Add Setting.
To edit a setting, select the checkbox that corresponds to the setting you want to edit, and click Edit.
4. From the Setting Name list, select the setting to be configured.
5. In the Setting Value, provide the appropriate value (see page 757) for the selected setting.
6. Click Save.
Centralized Tenant Configuration settings

The following table describes the centralized tenant configuration settings in BMC Helix Innovation Studio and provides
example values for each setting:
Tip
If you cannot view all the columns, click Full screen in the upper-right corner of the page or press
F to open the page in full screen mode. Alternatively, use the scroll bar at the bottom of the table.
Press Esc to exit full screen mode.
To easily search for a specific parameter in the table, select the parameter from the Setting Name list.
Alternatively, type the name of the parameter in the Setting Name text box.
For example, to search for the Full-Text-Case-Option parameter, select it from the Setting Name list, or
type the parameter name in the Setting Name text box.
Setting Name Description Values
Email-Max- Defines the maximum combined size limit for all attachments in an outgoing Example: 5000000 bytes
Attachment- email.
Size

Email-Max- Defines the maximum number of attachments that can be added to an Example: 5
Number-Of- outgoing email.
Attachments
Full-Text-Case- Indicates whether full-text searching is case sensitive. This setting affects all 0—Case sensitive (Default)
Option the FTS-enabled fields. Changes to this setting trigger an automatic re-
1—not case sensitive
indexing.
Full-Text- Provides the location of the directory where the FTS index files are stored. Default location: <install directory>
Collection- /arsystem/tenant/<tenant name>
Directory /ftsconfiguration/collection
Full-Text- Provides the location of the directory where the FTS configuration files are Default location: <install directory>
Configuration- stored. /arsystem/tenant/<tenant name>
Directory /ftsconfiguration/conf
Example, configuration files for the words-to-ignore and synonyms list.
Full-Text- Indicates whether the FTS server processes pending indexing tasks. F— Do not disable indexing (Default).
Disable-
T—Disable indexing. Pending indexing tasks are processed
Indexing
after indexing is enabled.
Full-Text- Indicates whether the BMC Helix Innovation Suite server uses the full-text F— Use the full-text search engine (Default).
Disable- search engine.
T—Disable the full-text search engine.
Searching
Note: The database search capability continues to work

even after the full-text search engine is disabled.
Full-Text- Contains the extensions of files that must be excluded from full-text search. Example: .pdf, .xml, .png, and so on.
Exclude-List
Full-Text- Contains words to be ignored during FTS. Search results will not contain the Articles (a, an, the), prepositions (in, on, from, front,
Ignore-Word- words that are added in this list. beside), and so on.
List
Press Enter to add a new word in this list.
Full-Text- Gives the location of the directory where the FTS index log files are stored. Default location: <install directory>
Indexer-Log- /arsystem/tenant/<tenant name>/db
File
Full-Text- Initiates the re-indexing of all FTS-enabled fields. 0 — Re-indexing is not performed (Default).
Reindex
1 — Starts re-indexing.
Full-Text- Indicates how the FTS server modifies search queries. 0—Force leading and trailing wildcards.
Match-Option
1—Ignore leading and force trailing wildcards.
2—Ignore leading wildcards.
3—Remove leading and trailing wildcards.
4—Leave query unchanged (Default).
Full-Text- Contains synonyms so that when the end user searches for any of these PC workstation laptop desktop computer
Synonyms words, resources related to its synonyms also appear in the search results.
slow sluggish
bright shiny
Type a word followed by its synonyms separated by a

space. Press Enter to add a new list of synonyms.
MFS- Defines the relevancy weight for the Environment Field. This setting relates to Default value: 1
Environment- the fields for which the application business analyst has defined the relevancy
Field-Weight when Enabling full-text search in an application (see page 335).

MFS- Defines the relevancy weight for the Keyword Field. This setting relates to the Default value: 2
Keywords- fields for which the application business analyst has defined the relevancy
Field-Weight when Enabling full-text search in an application (see page 335).
MFS-Title- Defines the relevancy weight for the Title Field. This setting relates to the Default value: 4
Field-Weight fields for which the application business analyst has defined the relevancy
when Enabling full-text search in an application (see page 335).
Enforce- Specifies whether the password policy must be enforced. T: Enforces the password policy, and you must create
Password- users and define the password according to the guidelines
Policy BMC Helix Innovation Suite ensures that passwords are always encrypted. To defined in the password policy. By default, the value is set
ensure that the passwords are validated and encrypted, a password policy is
to T.
enforced and forces the users to set a password that cannot be blank. For
information about the password policy, see Enforcing a password policy. F: Does not enforce the password policy, and you can
create users without a password.
Assigning application licenses to users

BMC Helix Innovation Suite enables an administrator to assign application licenses to users, so that the users can legally
use the application.
An administrator can manage licensing by performing the following tasks:
Assign BMC Helix Innovation Suite or application license to users.
View application license usage by generating a report.
Remove licenses assigned to users.
Before you begin

To be able to assign BMC Helix Innovation Suite licenses to users, ensure that the SaaS administrator has assigned
the BMC Helix Innovation Suite license to your tenancy.
To be able to assign application licenses to users, ensure that the SaaS administrator had assigned the application
license to your tenancy.
To assign BMC Helix Innovation Suite licenses to users

You can assign an BMC Helix Innovation Suite license to tenants so that they can legally use a custom application.
Assigning this license is a one-time activity.
2. Select Configure My Server > Licenses Management > Innovation Suite Licenses.
3. On the BMC Helix Innovation Suite License Users page, click Assign/Unassign Licenses.

4. Select one or more users to whom you want to assign BMC Helix Innovation Suite licenses.
5. Click Save.
To assign application licenses to users

To apply licenses to a tenant, the administrator can add the licenses by using BMC Helix Innovation Suite. Licenses are
active as soon as they are added to the server.
Note
This step is not required for a BMC application or partner-developed application that allows access to
unlimited users in a tenancy.
2.
2. Select Configure My Server > Licenses Management > Application Licenses.
3. Select the application for which you want to assign a named license.
4. Click Assign Licenses.
5. In the Assign/Unassign Licenses dialog box, select the users to whom you want to assign the application license.
6. Click Save.
7. (Optional) To view the list of users having licensed applications, click the application name link.

To generate application license usage reports
3. From the list of tenants, click the tenant name to access the list of applications and related licenses.
4. Select the application and click Generate Report.
5. In the Generate Report dialog box, specify the date range to include in the report.
6. Click Generate.
The report is created and downloaded as a CSV file to the default download location of your web browser. The following
image displays an example report for the application license consumption time (In seconds) for the user User 1:
Note
For BMC applications or partner-developer applications that are set for unlimited end-user licenses, the
license usage report returns "Unlimited end user licenses are applied to this Application" and the license usage
information is not available.
To remove BMC Helix Innovation Suite licenses from users
2.
3. In the BMC Helix Innovation Suite License Users page, click Assign/Unassign Licenses.
4. Clear the check boxes beside the user names whose license you want to revoke.
5. Click Save.
The licenses are revoked from the selected users.
Related topic
BMC Helix Innovation Suite licensing model (see page 40)
Deploying codeless applications

With BMC Helix Innovation Suite you can manage releasing your own custom built codeless applications and libraries
including new version updates at your own pace or according to the release cadence.
To build codeless applications and libraries, start by creating an install or update package either in the Developer
Sandbox or in the tailoring environment. You can then self deploy installation packages and update packages in the BMC
Helix Innovation Suite for each environment such as Developer Sandbox, Tailoring environment, QA environment, and
Production environment.
Using the deployment capability in BMC Helix Innovation Studio allows you to:
Deploy and upgrade codeless bundles in a few clicks without depending on developers, requiring an IDE, or using
an antiquated command line tool to deploy.
Move definitions and data for bundles from one environment to the next.
Deploy and upgrade codeless bundles in any environment you choose.
Release at a regular cadence of your choice or release immediately at any time when your new bundle or new
version is ready.
Administrators and developers can create install packages, update packages, and export packages from the BMC Helix
Innovation Studio. Once you provide the package to the Administrator, he or she can then self deploy the new bundle or
new version to the next environment of choice.
Workflow of deploying codeless applications

The following illustration shows the standard workflow for promoting codeless bundles and upgrades from one
environment to the next:

For more information about creating codeless applications, see Developing codeless applications (see page 794).

Next task Reference
Understand the different types of packages that you can create to deploy codeless applications Types of deployment packages (see page 765)
across environments
As an administrator, create and deploy entire application to test or production environments

1. Creating install packages (see page 766)
2. Installing codeless applications (see page 773)
As an administrator, create and deploy incremental changes of applications to test or

production environments 1. Creating update packages (see page 769)
2. Updating applications by using update packages

(see page 771)
As an administrator, create and deploy tailoring changes of applications to development or test

environments 1. Creating export packages (see page 775)
2. Importing export packages (see page 777)
As an administrator or a developer, redeploy entire application to test or production Reinstalling codeless applications (see page 773)
environments
Remove unnecessary applications from Innovation Studio Uninstalling applications by using Innovation Studio (see
page 773)

Types of deployment packages

After you create and customize the codeless applications in a development environment by using a dedicated system or
in a tailoring environment by using dedicated or shared systems, you can create deployment packages for deploying the
application to test or production environments. You can create an install package, update package, or export package as
per your requirements. You can then share the deployment packages with administrators, who can deploy these
deployment packages to other development, test, or production environments.
The following illustration provides information about the different types of deployment packages that you can create:
The following table helps you determine which package you can create based on your requirements:
Condition Install package Update package Export package
Usage
Created by administrators or Created by application business analysts or developers Created by administrators
developers and shared with and shared with administrators.
Created to deploy the
administrators.
Created to deploy incremental changes only of an application's tailoring
Created to deploy an entire application to collaborative development, test, or changes only.
application to a test or production environments; for example, bug fixes or
production environment. new features.
Package All the application data, such as the Only the changed items. Importing configuration data is Only the customized definitions
contents JAR files, definitions, and optional. and configuration data.
configurations.
Cannot include specific data only,

such as JAR files, definitions, or
configuration data in an install
package.
Environment
Can create the install package Can create the update package by using dedicated or Can create an export
by using dedicated or shared shared systems. package on a dedicated or
systems. shared tailoring system.
Can deploy the update package to a production
Can deploy the install pack environment. Can deploy the export
age to a production package to a development
environment. environment only.
Version Every package has a version number Every package has a version number that you can modify
that you can modify according to according to your requirement.
your requirement.

Condition Install package Update package Export package
Every package has a version

number. You cannot modify the
version number of the export
package.
File naming <developer ID>.<application name>- <developer ID>.<application name>-<update from version>-to- <developer ID>.<application name>-
convention <application version>-install.zip <update to version>-update.zip> format. <application version>-import.zip>
format. format.
For example, com.example.workorder-1.0.0-to-2.0.0-update.zip
For example, com.example. . For example, com.example.
workorder-2.0.0-install.zip. workorder-1.0.0-import.zip.

Next task Reference
As an administrator, create and deploy entire application to test or production environments

1. Creating install packages (see page 766)
2. Installing codeless applications (see page

773)
As an application business analyst or a developer, create and deploy incremental changes of

applications to test or production environments 1. Creating update packages (see page 769)
2. Updating applications by using update

packages (see page 771)
As an administrator, create and deploy tailoring changes of applications to development or test

environments 1. Creating the export packages (see page 775)
2. Importing the export packages (see page

777)
As an administrator or a developer, redeploy entire application to test or production environments Reinstalling codeless applications (see page 773)
Remove unnecessary applications from BMC Helix Innovation Studio Uninstalling applications by using Innovation Studio
(see page 773)
Creating install packages to deploy entire applications

On dedicated or shared systems, administrators and developers can create install packages. You use the install package
to deploy entire codeless applications in test or production environments. An install package contains all the codeless
application's data, which is, the JAR files, definitions, and configuration data of an application. You cannot choose to
include specific data, such as only JAR files, definitions, or configuration data in an install package.
You can share the install package with administrators, who can use it to deploy an entire application to a test or
production environment.
Workflow of creating install packages

The following illustration shows the workflow for promoting an install package from development or tailoring
environments to production environment:

Before you begin

Ensure that you complete the following actions:
You have created a codeless application (see page 794).
You are logged in to a development or tailoring environment where the Developer ID is configured.
For more information about downloading and installing BMC Helix Innovation Suite SDK, see Setting up your IDE
and installing BMC Helix Innovation Suite SDK (see page 800).
To create install packages

The deployable install package is downloaded as a ZIP file and consists of the following items:
JAR files, which include only the manifest file that contains the bundle descriptor
Definition data, such as records, views, processes, rules, named lists, documents, and associations
Localized data
Configuration data
The install file is named in <developer ID>.<application name>-<application version>-install.zip format. For example, com.
example.workorder-2.0.0-install.zip.
The following video (4:20) provides the process overview to create install packages:
https://youtu.be/3h1cXnvRkh8
Important
Use the 7 Zip utility to extract the contents of the ZIP file. You cannot extract the contents of the install ZIP file
using the Windows Zip utility or Mac archive utility.
To create an install package, perform the following steps:
2. Select the application that you want to package.

3. Click Actions > Create Install Package.

The Create Install Package window appears.

4. Provide the following information

Select View the definitions that are included in the install package and click Next.
Definitions By default, all definitions are added in the install package. You cannot select to include only specific definitions in the install package.
tab
Order Data Reorder data items by moving them up or down and click Next. The data items are installed in the same order on the target
tab computer.
Specify From the Options area, specify the following information and click Next:
Options tab
Application name: Enter a display name to identify the application. For example: Work Order.
Version: Enter the version number in the <major>.<minor>.<maintenance><anystring> format. For example, enter version
numbers such as 17.11.0, 17.11.0-SNAPSHOT, 1.0-SNAPSHOT, or 1.0.0.RELEASE.
Description: Enter a short description for the install package.
Depends On: Select the application or library on which your application should depend on. You can select multiple
applications or libraries.
Developer ID, Application ID: Review these autopopulated fields. You cannot change the value of these fields. The Developer
ID matches the ID configured in your sandbox instance.
Package tab Click Create Package to create the install package. After the package is created, click Next.
If the package creation fails, see Troubleshooting application deployment issues (see page 980) .
Download Click Download. The install package is downloaded to the default download location of your web browser.
tab
The deployable install package is downloaded as a ZIP file. You can upload the install package to a version control system
and share the package with administrators for installing the codeless application to test or production environments.

Install the codeless application to test or production environments (see page 773)

Creating update packages to deploy incremental changes of applications

On dedicated development system, BMC Helix Innovation Suite enables application business analysts and developers to
create update packages of codeless applications. You use the update package to deploy incremental changes of codeless
applications to collaborative development, test, or production environments. For example, you can deploy updates such
as application fixes, newly added features, or changed configuration data.
The update package can contain the application's modified data, which is, the JAR file, definitions, and configuration data
of an application. You can choose to include specific data, such as only JAR files, definitions, or configuration data in an
update package.
You can share the update package with administrators, who can deploy incremental changes of a codeless application to
a test or production environment.
Workflow of creating update packages

The following illustration shows the workflow for promoting an update package from development or tailoring
environments to production environment:
Before you begin

You have created a codeless application in Innovation Studio (see page 794).
You customized the application as per your requirement by adding record definitions, view definitions, rules,
processes, named lists, or associations.
You are logged in to a development or tailoring environment where the Developer ID is configured.
For more information about downloading and installing BMC Helix Innovation Suite SDK, see Setting up your IDE
and installing Innovation SDK (see page 800).
To create update packages

The deployable update package is downloaded as a ZIP file, and consists of the following items:

JAR files, which includes only the manifest file that contains the bundle descriptor
Definition data, such as records, views, processes, rules, named lists, documents, and associations.
Localized data
Configuration data
The update file is named in <developer ID>.<application name>-<update from version>-to-<update to version>-update.
zip> format. For example, com.example.workorder-1.0.0-to-2.0.0-update.zip.
The following video (4:20) provides the process overview to create update packages::
https://youtu.be/oBcglgR59I0
Important
Use the 7 Zip utility to extract the contents of the ZIP file. You cannot extract the contents of the update ZIP
file using the Windows Zip utility or Mac archive utility.
To create an export package, perform the following steps:

3. Click Actions > Create Update Package.

The Create Update Package window appears.

Select Select the definitions that you want to include in the update package and click Next. You can filter the definitions based on name,
Definitions tab modification date, or modified by and select the definitions from the search results.
Add Data tab Select the data to include in the update package. To include configuration data in the update package, select the Include
configuration data in the package check box.
Order Data tab Reorder data items by moving them up or down and click Next. The data items are installed in the same order on the target
computer.
Select (Optional) Definitions that have been deleted are displayed here. If you want to remove the definitions from the target computer
Definitions to after deployment, select the deleted definitions to be removed.
Delete tab If you do not select any definitions, the definitions are available for use on the target computer after the application is deployed.
Specify Options From the Options area, specify the following information and click Next:
tab
Application name: Enter a display name to identify the application. For example: Work Order.
Update from Version: Enter the version number of the source application that you want to update.
The update package cannot be created if you select an invalid version of the source application.
Update to Version: Enter the version number of the target application you want to update to.
BMC Helix Innovation Suite updates the application and its version only if the source application's version is different
from the target application's version.
Note: To share the application's incremental changes with other developers in a collaborative environment, the Update to
Version number and Update to Version number must match so that you avoid updating the application.
Description: Enter a short description for the update package.
Depends On: Select the application or library on which your application should depend on. You can select multiple
applications or libraries.
Developer ID, Application ID: Review these autopopulated fields. You cannot change the value of these fields. The
Developer ID matches the ID configured in your sandbox instance.
Package tab Click Create Package to create the update package. After the package is created, click Next.
If the package creation fails, see Troubleshooting application deployment issues (see page 980) .
Download tab Click Download. The update package is downloaded to the default download location of your web browser.
The deployable update package is downloaded as a ZIP file. You can upload the update package to a version control
system and share the package with administrator. The administrator can then update the application by using the update
package.

Update the application by using the update package (see page 771)
Updating applications by using update packages

Application business analysts and developers can create update packages of codeless applications on dedicated shared
systems. Administrators can use the update packages to deploy incremental changes of codeless applications to test or
production environments. For example, updates such as application fixes, newly-added features, or changed
configuration data.
Before you begin

1.
1. Create a codeless application in Innovation Studio (see page 794) and customized the application as per your
requirement.
2. Create an update package (see page 769) by using a development or tailoring environment.
To update applications by using the update package

After you create an application package, you can import the update package to apply the incremental changes to the
application.

3. Click Actions > Update Application.

The Update Application window appears.

Upload tab Select and upload the package for import by performing the following steps:
a. Click Upload.
b. Browse and select the ZIP file of the update package that you want to upload.
For example, select the ZIP file com.example.workorder-1.0.0-to-2.0.0-update.zip.
c. Click Next.
Update tab Click Update to import the update package and install the incremental changes for an application.
The application's incremental changes get uploaded, and the updated definitions are available for use in BMC Helix
Innovation Studio.
Related topics
Developing codeless applications (see page 794)

Deploying codeless applications (see page 763)
Installing, reinstalling, or uninstalling codeless applications

After you create the deployment packages for a codeless application, you can install the install package from BMC Helix
Innovation Studio. You can also reinstall an application that was modified by using Maven archetype or an earlier version
of the application. You can also uninstall the unnecessary applications from BMC Helix Innovation Studio.
Before you begin

Create a codeless application in Innovation Studio (see page 794).
Create an install package (see page 766) or an update package (see page 769) from BMC Helix Innovation Studio.
Important
If you want to view the deployment package contents, use the 7 Zip utility to extract the contents of
the ZIP file. You cannot extract the contents of the install ZIP file using the Windows Zip utility or Mac
archive utility.
Download the install package or update package from the version control system used by your project.
To install applications in BMC Helix Innovation Studio

As an administrator, you can install a full installation package by using BMC Helix Innovation Studio. Installing a full
installation package enables you to deploy the application for the first time to development, test, or production
environments. If an application is already installed, installing a full install package of the same application overwrites the
application data.
2. Click Install.
3. Browse and select the ZIP file of the install package that you downloaded to your local computer.
Browse and select the ZIP file of the deployment package that you copied to the environment.
The status of the installation process is displayed in the Install dialog box. After the process is completed, click
Close.
The application is installed in BMC Helix Innovation Studio and is displayed in the Workspace. You can then customize
the application by adding record definitions (see page 324), view definitions (see page 376), processes (see page 421), or
rules (see page 490).
If the installation fails, see Troubleshooting application deployment issues (see page 980) for information about the error
and workaround.

To reinstall codeless applications in BMC Helix Innovation Studio

You can reinstall an application that was updated in Maven archetype or reinstall an earlier version of the application.
During reinstallation, BMC Helix Innovation Suite overwrites the definitions in the existing application. The record
definitions are retained; however, data of newly added record fields is lost. The application version is overwritten with
the reinstalled application's version, which is specified during packaging and exporting the application or in Maven
archetype.
2. Select the codeless application that you want to reinstall.

3. Select Actions > Reinstall.
4. In the Warning! dialog box, click OK to proceed.
5. Browse and select the ZIP file of the install package or update package that you want to reinstall.
The status of the installation process is displayed in the Reinstall dialog box.
6. After the process is completed, click Close.

If the reinstallation fails, see Troubleshooting application deployment issues (see page 980).
The codeless application is reinstalled in BMC Helix Innovation Studio. You can then modify the codeless application by
adding record definitions (see page 324), view definitions (see page 376), processes (see page 421), or rules (see page
490).
To uninstall codeless applications or libraries from BMC Helix Innovation Studio

You can undeploy or uninstall the tenant-specific applications only.
2. Select the codeless application or library that you want to uninstall.

3. Select Actions > Uninstall.
4. In the Warning! dialog box, click OK to proceed.

BMC Helix Innovation Suite starts uninstalling the application. The status of the installation process is displayed in
the Uninstall dialog box.
5. After the process is completed, click Close.

If the uninstallation fails, see Troubleshooting application deployment issues (see page 980).
The codeless application is uninstalled from BMC Helix Innovation Studio.
Related topics

Creating export packages to deploy tailoring changes of applications

On a dedicated or shared tailoring system, BMC Helix Innovation Suite enables administrators to create export packages.
You use the export package to deploy the changes in tailoring codeless applications. An export package contains an
application's customized definitions and configuration data only; the export package does not include application code.
After you customize the application, you can create an export package and share with other administrators and
developers. Administrators and developers can then import the export package (see page 777) by using BMC Helix
Innovation Studio to deploy the tailoring changes.
Workflow of creating export packages

The following illustration shows the workflow of promoting an export package from tailoring to production environment:
Before you begin

The application is created and deployed to your environment.
The application is customized to suit your business requirement.
To create export packages

On a dedicated or shared tailoring system, you can create a deployable export package that gets downloaded as a ZIP file.
The ZIP file is named in <developer ID>.<application name>-<application version>-import.zip> format. For example, com.
example.workorder-1.0.0-import.zip. If an application's export package was created earlier, BMC Helix Innovation Suite
overwrites the earlier export package with the latest package.
The following video (3:37) provides the process overview to create export packages:
https://youtu.be/gAwdNleOZqU
Important

Use the 7 Zip utility to extract the contents of the ZIP file. You cannot extract the contents of the import ZIP
file using the Windows Zip utility or Mac archive utility.
To create an export package, perform the following steps:
2. Select the installed application that you want to export.

3. Click Actions > Create Export Package.

The Create Export Package window appears.

Select Definitions Select the customized definitions that you want to include in the export package and click Next.
tab You can filter the definitions based on name, modification date, or modified by and select the definitions from the search
results.
Add Data tab Select the following data to include in the update package and specify the following information and click Next:
To prevent rules from being executed after the export package is deployed to target computer, click Ignore Rules
beside the data source.
To choose how duplicate data records should be handled, select one of the following options:
Create new data records: New data records are created, regardless of whether any data records are duplicates.
Ignore the duplicates: Discards the duplicate data records, and creates data records only for the unique
records.
Merge the duplicates: Combines the duplicate data records into a single data record.
Overwrite the existing data records: If a duplicate data record is found, replaces previous data with new data
record.
To include configuration data in the update package, select the Include configuration data in the package check box.

Order Data tab Reorder data items by moving them up or down and click Next. The data items are installed in the specified order on the
target computer.
Select Definitions (Optional) Definitions that have been deleted are displayed here. If you want to remove the definitions from the target
to Delete tab computer after deployment, elect the deleted definitions to be removed.
If you do not select any definitions, the definitions are available for use on the target computer after the application is
deployed.
Specify Options Review the following information, which is autopopulated by default and cannot be modified:
tab
Application name
Application version
Description
Developer ID
Application ID
Package tab Click Create Package to create the update package. After the package is created, click Next.
If the package creation fails, see Troubleshooting codeless application issues (see page 980) .
Download tab Click Download. The export package is downloaded to the default download location of your web browser.
The deployable export package is downloaded as a ZIP file. You can upload the export package to a version control
system and share the package with other developers and administrators, so that they can deploy the tailoring changes by
importing the export package.

Import the export package to deploy the tailoring changes of codeless applications (see page 777)
Importing the export packages to deploy tailoring changes of applications

On a dedicated or shared development system, BMC Helix Innovation Suite enables administrators to apply the changes
done while tailoring an application to development environments by importing the export package. During import, BMC
Helix Innovation Suite overwrites the existing application data with the data from the export package.
Before you begin

Ensure the following:
1. The application is created and deployed to your environment.
2. The application is customized to suit your business requirement.
3. An export package is created (see page 775) that includes the tailoring changes of the application.
To import the export packages
2. Select the installed application that you want to import.

3. Click Actions > Import Definitions and Data.

The Import Definitions and Data window appears.

3.

UI Description
element
Upload Select and upload the package for import by performing the following steps:
tab
a. Click Upload.
b. Browse and select the ZIP file to upload.

For example, select the ZIP file com.example.workorder-1.0.0-import.zip.
c. Click Next.
Note: The export package's name and version number must match the
installed application's name and version number or the installation fails. For more information, see Creating export packages (see page
775).
Import Click Import to import the package and install the application.
tab
The application gets imported and installed, and the updated definitions are available for use in BMC Helix Innovation
Studio.
Related topics

Consuming a new version of an application

An application is in consumption when end users in a tenancy are using the application. With every release of a new
application version, new set of features and enhancements are provided. Some new features and enhancements might
not require implementation changes, such as zero downtime upgrades. Depending on the impact of these features and
enhancements, you can decide to test the new version in the test environment before making it available for
consumption.
Points to consider
When you upgrade to the new version, consider the following points:
After you upgrade to a new version in a test environment, ensure that you do not create any
customizations on the earlier version.
Any active process instances created on the earlier version will continue to work on the later version
after upgrade.
Before you begin

Ensure that the SaaS administrator activates the new version.
Process to upgrade to a new version of an application in a test environment

The administrator opts for the new version in the test environment. After testing and validating the new version, the
administrator must create an export package. For more information about creating an export package, see Creating
export packages to deploy tailoring changes of applications (see page 775)
The following diagram explains the process of upgrading to a new application version in a test environment:

Process to upgrade to a new version of an application in a production environment

After testing the new version in the test environment, you must import the new version along with its changes in the
production environment. The SaaS administrator must activate the new version in the production environment only
after the administrator has imported the export package tailoring changes (see page 777). After activating, the new
version of the application is available for all the tenants for consumption.
The following diagram explains the process of upgrading to a new application version in a production environment:

To upgrade to a new version in a test environment
2. Select Manage Application > Configure Versions.
3. Select the application for which you want to consume the upgraded version, and click Opt-In.
4. From the popup window, select the version and click Opt-in.
Note

In a test environment, an administrator can choose to switch back to the previous version by clicking Opt out.
The Opt out option is not available in the production environment. A version of an application is available for
consumption immediately after the SaaS administrator activates the version.
Submitting user reported issues to BMC Customer Support

When a user encounters an error on BMC Helix Innovation Studio, the user can report the error as an issue along with
information about the issue that the user wishes to provide. As an administrator, you can view and resolve the issues
reported by users or submit a case to BMC Customer Support to help resolve these issues. You can also consolidate
similar issues and submit one to BMC Customer Support.
Before submitting an issue to BMC Customer Support, BMC recommends that you click to
search for any existing knowledge articles related to the issue by entering the error ID or error description, and then
provide a solution to the user.
The following illustration provides information about submitting a user reported issue to BMC Customer Support:

Before you begin

Before you submit user reported issues, ensure that as an administrator you have linked the BMC Service Cloud Account
to BMC Helix Innovation Suite and configured your email ID with the BMC Service Cloud Account. For more information,
see Configuring administrator credentials for reporting errors to Customer Support (see page ).
To configure your BMC Service Cloud account
2. Select Issue Reporting > Issue Reporting Configuration.
3. Select BMC Service Cloud Account Configuration and enter the following details:
Fields Description
Support ID The Support Contract ID registered for your company.
Support Email

3.
Fields Description
The administrator's email ID registered with Customer Support.

Note: Each administrator has to provide his or her own Support Email and perform the configuration individually.
4. Select Link BMC Service Cloud Account to BMC Helix Innovation Suite and click Link Account.
The Link Account button opens a BMC Service Cloud login page that allows the administrator to enter the
credentials for authorization. BMC Service Cloud authenticates the credentials. The administrator authorizes the
use of the credentials and then BMC Service Cloud returns an OAuth token for the administrator that is saved in
After the authorization is complete, the status is updated to Account is linked.
5. Click Save.
To submit user reported issues to BMC Customer Support
2. Select Issue Reporting > Application Issues.
3. In the Application Issues section, select the issue submitted by the user that you want to submit to BMC
Customer Support.
You can select the check box to select multiple issues and submit a single case to BMC Customer Support.
4. Click Submit to BMC Support.
5. In the Submit to BMC Support dialog box, provide the description and select the severity for the issue.
Note
BMC recommends that you click Knowledge Articles to view the knowledge articles related to the issue
before submitting the case to BMC Customer Support.
6. Click Submit Case.
After the issues are submitted, a case is created. The administrator can click Refresh Case Status to view the case ID and
case status of the submitted issues. After BMC Customer Support resolves the case, the Case Status is updated as Closed
.
The administrator can also click Delete to remove the closed issues from the list.

To mark an issue as duplicate

If the administrator receives two or more similar issues, the administrator can submit just one issue to BMC Customer
Support and select the other similar issues and mark them as duplicates.
After BMC Customer Support resolves the case, the Case Status is updated as Closed, the administrator can click Refresh
Case Status to view the case ID and case status and then update the user on the status of all these issues.
Note
You can mark the issue as duplicate only if the Issue Status is New and the issue is not submitted to BMC
Customer Support.
1. From Administration > Issue Reporting > Application Issues, select the issue submitted by the user that you want
to mark as duplicate and click Close as Duplicates.
On the Close Duplicates Issues page, the issue to be marked as duplicate is displayed in the Selected Issues
section.
2. From the Are Duplicates Of section, select the issue against which you want to close the selected issue as
duplicate.
3. Click Close Selected Issues.
Related topics
Reporting application errors as issues (see page 992)
Support information (see page 993)
Measuring the cognitive service consumption

The BMC Helix Innovation Suite Cognitive Service consumption is measured by using three parameters—number of chat
conversations, API calls, and documents. The SaaS administrators and administrators can monitor the consumption of
cognitive service for these parameters, download the consumption reports, and configure email notifications that are
sent when the consumption exceeds the specified threshold.
By monitoring the cognitive service consumption, you can get answers to the following questions and make informed
decisions:
How much of a service am I using?
How much of a service is overused?
Is there a need to purchase more capacity?
Cognitive service operations and their measure

Operation Parameter measured
Chat

Operation Parameter measured
Number of cognitive service chat conversations
The following actions are considered as a chat conversation:
When a chat session times out
When a developer clears the chat session to mark the session complete
When a conversation has 50 responses
Classify Number of API calls made for auto-classification
Search Number of cognitive service advanced training documents
Methods for monitoring cognitive service consumption

You can monitor the cognitive service consumption in the following ways:
View the Telemetry dashboard.

The Telemetry dashboard displays cognitive service consumption statistics that enable an administrator to obtain
a usage report for their company.
For more information about downloading the consumption statistics, see 836466051 (see page 785).
Configure the threshold and email notifications when the cognitive service usage exceeds a specified threshold.
You can configure the email addresses and three thresholds each for API calls, document storage capacity, and
conversation capacity. For more information about configuring the threshold and email addresses for
notifications, see 836466051 (see page 785).
View the notification history

The notification history displays the list of notifications that are triggered when the cognitive service usage
exceeds the specified threshold. The notification history displays entries only after notifications are triggered. For
more information, see 836466051 (see page 785).
To download the cognitive service usage report from the Telemetry dashboard
2. Select Configure My Server > Telemetry.
3. The Telemetry dashboard displays statistics for each operation—Cognitive Service Chatbot Conversation,
Cognitive Service Automation API Calls, and Cognitive Service Advanced Training Documents.
4. Download the cognitive service usage report.
a. Click Download.
b. In the Download CSV File dialog box, select a predefined time or enter a specific period.
c. Click Download.
The CSV report is downloaded. The following image shows a sample report:

Report details
Operation - Chat, classification, and search
Application – Name of the application that performed the operation
Period – Selected time period
Count – Total count of operations
To configure thresholds and email notifications for cognitive service usage

The administrator can configure up to three thresholds and 10 email addresses.
2. Select Configure My Server > Telemetry .
3. Click the Notifications icon that corresponds to the operation for which you want to configure
the thresholds.
4. Configure the capacity and threshold.
a. In the Capacity section, enter the total capacity.

Example: In the Capacity section for Number of Conversations (N), enter 10,000.
b. In the Threshold 1 (%) field, enter the threshold for when you want to trigger the first notification.
Example: 50. If the total capacity is 10,000 conversations, the first notification is triggered when the
number of conversations exceed 5,000.
c. In the Threshold 2 (%) field, enter the threshold for when you want to trigger the second notification.
Example: 75. If your total capacity is 10,000 conversations, then the second notification is triggered when
the number of conversations exceed 7,500.
d. In the Threshold 3 (%) field, enter the threshold for when you want to trigger the third notification.
Example: 90. If your total capacity is 10,000 conversations, then the third notification is triggered when
the number of conversations exceed 9,000.
5. Configure the email addresses.
a.
5.
a. From the Available Email Notifications recipients list, which displays the email addresses of all the users
created in the Foundation data for a tenant, select the email addresses to which you want to send the
cognitive service consumption notifications. You can select up to 10 email addresses. To add people to
the Foundation data, see Creating or modifying Person data (see page 664) .
b. To add the email addresses to the Selected Email Notifications Recipients list, click .
c. Click Save.
To view the notification history
1. Log in to BMC Helix Innovation Studio and navigate to Administration tab.
2. Select Configure My Server > Telemetry .
3. Click the Notifications icon that corresponds to the operation for which you want to view the
notifications history.
4. Click Notification History.
Localizing field values

You can localize fields of a record definition so that the end users of an application can view the application data in their
locale during run time. An administrator must first add the locale information in the system and then define the fields of
a record definition that are localizable.
To add a system locale
2. Select Configure My Server > Manage System Locales.
3. On the Manage System Locales page, click New.
4. In the Create New Locale dialog box, enter the locale name and the locale code.

Note
When entering locale values, ensure that you adhere to the browser's language naming convention,
which is Language-Country Name. For example, en-US, en-UK, fr-FR and so on.
5. Click Save.
A new locale is added to the list of supported system locales.
To edit a system locale
1. On the Manage System Locales page, select the locale and click Edit.
2. Edit the locale information as per your requirements.
3. Click Save.
Best practices for defining localizable fields

Consider the following recommendations when designing record definitions to include localizable fields:
When you create localizable fields in a record definition, the server does extra computation work, which slows
down transactions during run time. Therefore, choose only those fields for localized values that are a must-have.
Localize fields that have prepopulated configuration data that does not change often; for example, organization
name, department name, country name, and so on.
Do not localize fields that hold transactional data during run time; for example, Issue Description.
Do not localize a field that is used to store the localized configuration data; for example, a field such as Issue
Type, whose values can get populated through a named list that holds different, localized issue type values.

Operations supported by a localizable field

A localizable field is of Localized Text data type and is similar to a Character field. The following table lists the operations
supported by a localizable field.
Operation Supported by a localizable field?
Create a named list with a localized text field as the data source
Attach a named list to a localized text field cross (x)
Customize the localized text field
Create a join record definition
Inherit record definition with shared data
Inherit record definition without shared data
Create unique index
Create composite index cross (x)
To define localizable fields
1. Log in to BMC Helix Innovation Studio, navigate to the Workspace tab, and select the application.
2. Select a record definition or create a new record definition.
3. Click New Field to create a new field and select the data type as Localized Text.
4. Enter the field name and provide additional details for the field as described in the following table:
Field Description
Name Enter the name of the record field.
Description Provide the description for the record field.
Required Select to mark the field as required for the record definition.
Allow Select to allow any user to submit new requests.

anyone to
submit
Change Select to create an audit record if there is any change in the field value.
triggers
audit
Include Select to copy the field value to an audit record.

value in
audit
(Optional)
Field ID

Field Description
Enter a numeric value. If the field ID is not entered, a field ID is automatically is assigned from the custom Field ID range.
The Field ID range specifies the limit for values that you can assign (or are assigned automatically if you do not assign any value) to the
Field ID. You can assign the value to Field ID within the Field ID range. The Field ID range for a field in a record definition is specified by
the SaaS administrator. You cannot assign the lower limit value of the Field ID range to a field. For example, if the Field ID range is
1000:2000, the minimum value that you can assign to a Field ID is 1001.
Length Enter the field length in characters; enter 0 for an unlimited field length.
By default, field length is of 254 characters.
Default Click the Localize link to select a locale as the default locale. The locale values are populated from the list of supported system locales.
value For information about adding a system locale, see Adding a field value locale (see page 788).
5. Click Save.
To add record instances in the localizable record definition
1. Select the record definition in which you want to enter values.
2. Click Edit Data.
3. In the Data Editor, click New to enter a new record.
4. Enter values for all the record fields.

To enter values in the localized text field:
a. Click Localize.
b. In the Localize value dialog box, enter the values against each locale that you need.
Note
The list of locales is populated from the list of supported system locales.
5. Click Save.
When a user logs in, they can see the content for that field in their locale setting. If no locale is set, the value from
the default locale is shown. If the default locale is not set, a NULL value is displayed for the locale.
Example:
In this scenario, you need to add localized values to a localizable field called Department. Two system locales,
German and German (Germany), are already in the system and the default locale is set to English-United States. Add
localized values to the Department field as shown in the following images.
1. Add values to the new record and click the Localize link beside the localizable field.

2. Enter the localized values and click Save.
After entering the localized values, the data editor shows the Department field values based on user's
current locale.
If your browser locale is set to de-DE German (Germany), the localized field shows values in de-DE
German (Germany).
If your browser locale is set to de-AT German (Austria) and you have not defined the de-AT German
(Austria) locale for the Department field values, the data editor shows the data in the generic
system locale, that is de German.

If you have not entered the localized values for the system locale, the data editor shows the data in
the default locale, that is English-United States.
Considerations when assigning a Localized Text field in a process or a rule

During assignment of a Localized Text field to another Localized Text field in a process or a rule, the assignment
is successful and the entire locale map is assigned to the new field.
During assignment of a Localized Text field to a Character field, the current locale value is assigned to the
Character field. If no locale is defined, the default system locale is assigned to the Character field.
During assignment of a Character field to a Localized Text field, only the current locale value is assigned to the
Localized Text field. Other locale values in the map will be NULL.
Fallback mechanism for displaying localized field values

BMC Helix Innovation Suite displays localized field values to the user according to the following order of preference:
1. User's current locale
2. Generic system locale

For example, if the user's locale is de-AT German (Austria), then the fallback locale is de German.
Note
You cannot edit the value of the fallback locale.
3. Default locale as set in the system locale
The fallback mechanism applies when displaying values in the Record Editor, Record Grid, and View component.
Example
You have defined three locales: French, French (France), and Japanese. English US is the default locale and the
user's current locale is set to French.
If the field values are provided in French, the user can see values in French.
If the field values are provided in French (France), the user can see values in French (France).
If the field values are provided in French (Belgium), the user can see values in French because French is
the generic system locale.
If you have not entered an value in the Localize Value field for French locale and the user's current
locale is set to French, the data editor shows the data in the default locale.

Related topics
Localizing a Digital Service application (see page 968)
Creating a view for localized field values (see page 415)
Developing applications
This section provides you information about developing Digital Service applications. BMC Helix Innovation Suite provides
two ways to develop an application: developing codeless application and developing a code-based application.
Administrators can develop codeless applications by using BMC Helix Innovation Studio. Development of
codeless applications requires minimal programming knowledge or dependency on developers. Administrators
can create codeless applications that require less customization and are not complex. These applications consist
of definitions and data only, and do not include libraries.
Developers can develop code-based applications by using the BMC Helix Innovation Suite SDK, BMC Helix
Innovation Studio, and Maven archetypes. With code-based applications, developers can extend the BMC Helix
Innovation Suite platform to create custom components, custom REST APIs, connectors, and so on.

Action Reference
Create a codeless application by using BMC Helix Innovation Studio. Developing codeless applications (see page 794)
Create a code-based application by using BMC Helix Innovation Suite SDK, BMC Helix Innovation Developing and deploying code-based applications
Studio, and Maven archetypes. (see page 798)
Developing codeless applications

BMC Helix Innovation Suite enables you to create codeless applications and libraries in both a development (Developer
Sandbox) and a pre-production (Tailoring) environment. As an administrator, you can create a new codeless application
or library bundle within BMC Helix Innovation Studio. Codeless bundles consist of definitions and data only, and do not
include any Java or JavaScript code.
Benefits of codeless bundles:
Develop applications and libraries without having to know or learn a programming language.
Eliminate the dependency on a procode developer to build an application or library.
Minimize the complexity of initially setting up an environment to build applications and libraries since a codeless
bundle does not require setting up a full IDE, build tool, and source control system. Please note that you will need
some technology to manage versions of your changes of a codeless bundle. For instance you can export and save
copies of your bundle to a file system that is backed up on a regular basis or if you prefer, you can leverage a
source control system to check in versions of your bundle.
Construct applications quickly by using drag and drop visual designers to define the structure of your application.

Easily maintain and modify your applications and libraries since the structure of your application is visually
represented in the visual designers.
Notes
Codeless bundles created in a Tailoring environment are considered your intellectual property and are not
tailorable. In other words, changes you make on your bundles are not considered customizations and
instead are changes to the original objects. Codeless bundles you create in Tailoring can't be seen or used
by other tenants. Your codeless bundles can't be installed in tenant spaces other than your own.
To add custom code to your codeless application or library, you must convert your bundle to a coded
bundle and move it to a Developer Sandbox environment. For more information, see Extending codeless
applications with custom coded components (see page 797).
Custom codeless applications contain a universal entry point that is shared by all applications and includes an index.html
file. Developers are not required to include framework functionality that maintains a custom entry point in their coded
applications .
The universal entry URL is formatted like this:
http://<host>:<port>/innovationsuite/index.html#/<applicationId>
For more information about the URLs for BMC Helix Innovation Suite applications, see Upgrade considerations (see page
).
The following video (8:01) demonstrates how a small codeless application can be rapidly developed by using BMC Helix
Innovation Suite:
https://youtu.be/T2C7h3NdejA
Workflow of creating codeless applications

The following illustration shows the workflow for creating and promoting a codeless bundle from one environment to
the next:

Before you begin

Ensure that your Developer ID (see page 52) is set correctly in the Developer Sandbox or a tailoring environment .
Steps to create a codeless application bundle
2. Click New > Application.

The New Application dialog box is displayed.

Application Name Enter the display name of your application. For example, Work Order.
Application Short Name Enter the name of your application that will be used for unique namespacing of objects. Additionally, the short
name is prefixed with a Developer ID to create the Application ID. For example, workorder.
Note: Do not use any special characters or spaces in the application short name.
Developer ID, Application ID The Developer ID is already configured in your environment and is displayed for your reference. The Application ID
is constructed based on your Developer ID and your Application Short Name and displayed for your reference.
4. Click Create.
A new application called Work Order with a default version of 1.0.0 is created in BMC Helix Innovation Studio appears in
the Workspace.
If your application fails to be created, see Troubleshooting application deployment issues (see page 980) for information
about the errors and workarounds.
Steps to create a codeless library bundle
2. Click New > Library.

The New Library dialog box is displayed.

Library Name Enter the display name of your library. For example, Work Order Library.

3.
Library Short Enter the name of your application that will be used for unique namespacing of objects. Additionally, the short name is prefixed with
Name a Developer ID to create the Application ID. For example, workorder-lib.
Note: Do not use any special characters or spaces in the application short name.
Developer The Developer ID is already configured in your environment and is displayed for your reference. The Library ID is constructed based
ID, Library ID on your Developer ID and your Library Short Name and displayed for your reference.
4. Click Create.
A new library called Work Order Library with a default version of 1.0.0 is created in BMC Helix Innovation Studio appears
in the Workspace.
If your Library fails to be created, see Troubleshooting application deployment issues (see page 980) for information
about the errors and workarounds.
Extending codeless applications with custom coded components

When the out of the box components aren't enough to build your codeless application in the way you want, you can
extend your application with custom coded components. There are two approaches to extend your application.
First Approach: Build the custom coded components in a separate, coded library
1. Create a new coded library in which to build the custom coded components. See Developing and deploying code-
based applications (see page 798).
2. Add the custom coded component from your new coded library to your codeless application. For example if the
custom coded component is a Process Action, it will appear in the Process Designer palette that you can drag
and drop into your process in your codeless application.
Second Approach: Convert your codeless bundle to a coded bundle.
1. If you created your codeless bundle in your Tailoring environment, you need to move your bundle to your
Developer Sandbox. Create an install package (see page 766) for your codeless bundle in your Tailoring
environment. Then install the newly created package (see page 773) in your Developer Sandbox.
2. Create a new project using Maven (see page 806) in your IDE. When using Maven to create the project, set the
property values (groupID, artifactID, version, name) in Maven to match the property values of the codeless
bundle. This step presumes you have already setup your IDE. If you haven't, then follow these instructions to set
up your IDE (see page 800).
Note
Do not run the Maven command: mvn clean install -Pdeploy as this could clobber over your codeless
definitions in the Developer Sandbox.
Don't forget to configure your pom.xml file in your project folder to point to your Developer
Sandbox server with your developer credentials.
3.
3. In your project directory, run this Maven commend to export the definitions of your bundle from your Developer
Sandbox and store them in the project repository in your IDE.
mvn install -Pexport
4. Add the custom coded components to your application.
5. When you are done developing the code and are ready to promote the new custom coded bundle to QA and
Prod environments, create a deployment package and deploy the custom code-based application (see page 915)
to your Tailoring or QA environments in BMC Helix Innovation Studio.

Next task Reference
Develop the codeless application by adding record definitions, view definitions,

Defining record definitions to store and manage data (see
processes, or rules.
page 324)
Defining the user interface through view definitions (see

page 376)
Defining the application business logic through processes

(see page 421)
Adding rules to validate data or trigger events in a process

(see page 490)
Create install packages to deploy entire codeless applications in development, test, or Creating install packages to deploy entire applications (see page
production environments 766)
Developing and deploying code-based applications

This section provides you information on developing Digital Service applications by using BMC Helix Innovation Suite.
BMC Helix Innovation Suite consists of BMC Helix Innovation Suite SDK and BMC Helix Innovation Studio that assists you
to create applications and libraries. BMC Helix Innovation Studio requires minimal code and has an intuitive user
interface that allows developers to drag and drop items while creating applications.
To understand the skills required to develop an application, see Orientation (see page 30).
The following image provides the broad level steps to develop an application:

This section provides information about how you can setup the development environment, create application project,
create application definition, develop connectors, create a deployment package, and test an application.
Action Reference
Set up the environment to develop an application, create a project, add dependencies on other Preparing to develop a Digital Service application (see
smart bundles, and apply license to your application. page 799)
Create data and logical definitions for an application by using BMC Helix Innovation Studio. Creating the definitions for a tailorable Digital Service
Integrate an application with a third-party systems. Integrating with another application by using a
connector (see page 615)
Package and test an application. Getting your Digital Service application ready for use
(see page 915)
Preparing to develop a Digital Service application

After you understand the concepts required to build a Digital Service application, you should set up the development
environment. The application development process consists of creating a project using Maven archetype and BMC Helix
Innovation Suite SDK, implementing data and logical definitions using BMC Helix Innovation Studio, extending the
services using Java and JavaScript (if required), and packing the application.
This section provides you the information on how to set up the environment to develop an application, create a project,
add dependencies on other smart bundles, and apply license to your application.
Action Reference
Set up the environment to develop an application Setting up your IDE and installing BMC Helix Innovation Suite SDK (see page 800
)

Action Reference
Create a new application project or library project Creating a Project using Maven and the Archetype (see page 806)
Create a deployment package for an application and deploy the package to Deploying your Digital Service application for the first time to start working in
the BMC Helix Innovation Suite server BMC Helix Innovation Studio (see page 813)
Specify the dependency of your application on the other bundles Using components from another developer's Digital Service application or
library (see page 815)
Specify the third party code dependency for your application Using code from open source (see page 816)
Set up a collaborative development environment so multiple developers Developing collaborative Digital Service applications (see page 820)
want to simultaneously work on an application
Setting up your IDE and installing BMC Helix Innovation Suite SDK
Before you start with developing applications, you must install the BMC Helix Innovation Suite SDK and the components
required to develop applications. For an overview of the steps to develop an application, see Preparing to develop a
Digital Service application (see page 799).
The following video (4:20) d emonstrates the list of components required to develop the application and how to setup
the Integrated Development Environment (IDE).
https://youtu.be/5mzWv7y3_3s
The following table lists the different components and installers you need to set up the development environment:
Components and installers Description
Innovation Suite SDK (see page BMC Helix Innovation Suite Software Development Kit
805)
Java JDK 1.8 (see page 801) Java Development Kit
BMC Helix Innovation Suite BMC Helix Innovation Suite server and database are installed in the Amazon Web Services (AWS) instance.
server
Mid Tier Mid Tier is required to create a developer user account. You can use a mid tier on other environments and point it to the
development environment.
Maven 3.2.1 (see page 801) Build system
Eclipse 4.6 (see page 801) Integrated Development Environment (IDE)
GitHub (see page 802) Required for BMC Helix Innovation Suite SDK
Node.js (see page 804) JavaScript runtime engine required for Grunt
Yarn (see page 804) Package manager for JavaScript
Grunt (see page 805) JavaScript task runner for running and debugging custom web applications
Recommendations
Use Google Chrome or Mozilla Firefox browser to access BMC Helix Innovation Studio.
If you are using Google Chrome, ensure that you use Batarang - the AngularJS Extension. To download the tool,
click Chrome webstore apps .
When working with REST APIs, ensure that you use the Postman application.

To view text files, you can use Notepad++ .
To install Java 1.8.x JDK
1. Download and install JDK 8.

See JDK 8 and JRE 8 installation .
Note
While installing the JDK, select the option to include the public Java Runtime Environment (JRE).
2. Create a JAVA_HOME environment variable pointing to the location of the JDK installation.
To create the variable on Microsoft Windows:
a. Navigate to Start > Control Panel > System > Advanced System settings.
b. In the System Properties, navigate to Advanced > Environment Variables.
c. In System Variables, add the location of the bin folder of the JDK installation to the JAVA_HOME variable.
For example, a typical value for the PATH variable can be:
C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Java\jdk1.8.0\
3. Add %JAVA_HOME%\bin to the PATH environment variable.
To install Maven 3.2.1
1. Download and install Maven 3.2.1.

See archive.apache.org and download one of the following files:
(Windows) Download apache-maven-3.2.1-bin.zip.
(UNIX) Download apache-maven-3.2.1-bin.tar.gz.
See Installing Apache Maven in the Maven documentation.
2. Create a MAVEN_OPTS environment variable and set it to -Xms512m -Xmx1024m.

See Configuring Apache Maven in the Maven documentation.
Note
Do not change the default location of the Maven repository. By default, the Maven repository is located at C:
\Users\Administrator\.m2.
To install Eclipse 4.6
1. Download and install Eclipse IDE for Java developers , 64-bit version 4.6 (Neon).
2. Modify the eclipse.ini file to increase the memory used by Eclipse.
a.
2.
a. Edit the line with -Xms to -Xms256m
b. Edit the line with -Xmx to -Xmx1536m
3. Download and install the AspectJ plug-in for Eclipse.
a. Download AspectJ plug-in .
b. In Eclipse, navigate to Help > Install New Software > Add.
c. Enter the URL of your Eclipse version such as

http://download.eclipse.org/tools/ajdt/46/dev/update .
d. Select Required Tools > Next > Finish.
To install GitHub
The following procedures list the different ways to install GitHub:
Using GitHub desktop
1. Install the desktop version of GitHub.

See GitHub .
2. After you install GitHub, add the command line git.exe in the Windows Path environment variable.
a. Get the git.exe path. GitHub desktop is installed in the following folder:
C:\Users\<YourUserName>\AppData\Local\GitHubDesktop\app-<VersionNumber>\resources\app\git\cmd
<YourUserName> is your Windows login name and <VersionNumber> is the GitHub version installed.
For example:
b. Navigate to Windows Explorer > This PC > Properties > Advanced System settings and in the System
Properties, navigate to Advanced > Environment Variables.
c. In System Variables, edit the variable Path to add the path to the git.exe utility and save the changes.
3. Verify that git.exe is available by opening a Window command prompt and entering the following command:
git --version
The git.exe tool version is displayed.

Using the Git command line program
1. Access the GitHub Downloads URL and select Windows.
2. Cancel the download for the default git installer and from the UI select the 64-bit Git for Windows Portable
option.
3. After you run the executable file, the Git command line program is installed at the C:\git\PortableGit folder.
4. Add the git.exe path in the Windows Pathenvironment variable by using the following steps:
a. Get the git.exe path fromtheC:\git\PortableGit\bin\ folder.
b. Navigate to Windows Explorer > This PC > Properties > Advanced System settings and in System
Properties, navigate to Advanced > Environment Variables.
c. In System Variables, edit the variable Path to add the path to the utility git.exe and save the changes.
5. Verify that git.exe is available by opening a Window command prompt and entering the following command:
git --version
The git.exe tool version is displayed.

To install Node.js
1. If you have installed a Node.js version earlier than 10.7.0, uninstall Node.js.
For example, if you have installed Node.js 6.11.2 , use the following command to uninstall it:
nvm uninstall 6.11.2
If you have Windows and do not have the nvm, you can uninstall nvm using the Add/Remove Programs
feature of the operating system.
2. (Optional) Install Node Version Manager version 1.1.0 or later.

See nvm-windows .
Note
BMC recommends that you use Node Version Manager. Node Version Manager simplifies the
management of node versions when you have to frequently install, uninstall, or switch between
different node versions. If you do not install Node Version Manager, make sure that you get the
installer from the Previous Releases page on the nodejs.org website.
3. Install Node.js 10.7.0 by using the following command:
nvm install 10.7.0
4. Make the Node.js version 10.7.0 as the default version in your system by using the following command:
nvm use 10.7.0
5. Verify that the correct version of Node.js is running on your system by using the following command:
node --version
To install Yarn
1. Install Yarn 1.9.4 .

Operation System Use the installation file with extension
Windows .msi
Linux .tar
MAC .deb
Other See the Yarn installation information.

To get the actual version of Yarn, you can refer: Yarn v1.9.4 .
2. Verify that the version of Yarn running on your system by using the following command:
yarn --version
If you have Windows operating system, you can install/uninstall Yarn using the Add/Remove Programs.
To install Grunt
You can install Grunt tool for easy debugging of custom web applications. Grunt is installed and managed via the Node.js
package manager. No additional installer is required for installing Grunt.
To install Grunt 1.2.0 Grunt 1.2.0 command line interface by using the following command:
npm install -g grunt-cli@1.2.0
Note
If the grunt command is not recognized as a command, the installer may have failed to add it to the path.
Ensure that the npm folder is in the path, usually located at \Users\YOURNAME\AppData\Roaming\npm.
To download and install BMC Helix Innovation Suite SDK

If you have created applications by using an BMC Helix Innovation Suite SDK version earlier than 18.11.01, you must
upgrade your applications to version 18.11.01. To upgrade your application to 18.11.01, see Upgrading BMC Helix
Innovation Suite SDK to 18.11.01: Patch 01 (see page 27).
1. Download BMC Helix Innovation Suite SDK.
2. Extract the sdk folder to a desired location (for example, C:\sdk) and add an environment variable RX_SDK_HOME
pointing to the sdk folder location.
3. Run the following command:
mvn clean install
For example, if the sdk folder is located at C:\sdk, run the following commands:
cd C:\sdk\lib
mvn clean install

To verify the development environment

You can have a quick check of installed software in the development environment by using commands. The following
table describes the commands with output examples. The output may vary on your system depending on the installed
components.
Command Output Verification
java -version java version "1.8.0_131" Java(TM) SE Runtime Verify that the JAVA_HOME and PATH parameters are
Environment (build 1.8.0_131-b11) Java HotSpot set to correct locations. If not set correctly, set the
(TM) 64-Bit Server VM (build 25.131-b11, mixed locations manually:
mode) C:\Users\Administrator>jar
Set the JAVA_HOME parameters to "C:
\BMCPreReq\Java"
In the PATH parameters, add "C:

\BMCPreReq\Java\bin"
mvn -version Apache Maven 3.2.1 Verify that the MAVEN_HOME, MAVEN_OPTS and
(ea8b2b07643dbb1b84b6d16e1f08391b666bc1e9; PATH parameters are set to correct location. If not set
2014-02-14T09:37:52-08:00) Maven home: C: correctly, set the locations manually:
\BMCPreReq\apache-maven-3.2.1\bin\.. Java
Set the MAVEN_HOME parameter to
version: 1.8.0_131, vendor: Oracle Corporation
"C:\BMCPreReq\apache-maven-3.2.1"
Java home: C:\BMCPreReq\Java Default locale:
en_US, platform encoding: Cp1252 OS name: Set the MAVEN_OPTS parameter to "-Xms512m
-Xmx1024m"
"windows server 2008 r2",
version: "6.1", arch: "amd64", family: "dos" In the PATH parameter, add
"C:\BMCPreReq\apache-maven-3.2.1\bin"
node -v v10.7.0 Verify that the PATH parameter is set to correct

location. If not set correctly, in the PATH parameter
add "C:\BMCPreReq\nodeJS\" manually.
set RX_SDK_HOME=<sdk loc>\com.bmc.arsys.rx.sdk- Verify that the RX_SDK_HOME parameter is set to

RX_SDK_HOME 18.11.1 correct location. If not set correctly, set the location
manually to
<sdk location>\com.bmc.arsys.rx.sdk-18.11.1
yarn --version 1.9.4 Verify that the PATH parameter contains the location
C:\Users\Administrator\AppData\Local\Yarn\bin
grunt -version v1.2.0 Verify that the PATH parameter is set to correct
location. If not set correctly, set the location manually
to
"C:\Users\Administrator\AppData\Roaming\npm"

Creating a Project using Maven and the Archetype (see page 806)
Creating a Project using Maven and the Archetype

The smart bundle development involves development of a Digital Service application or a smart library. All the code for
an application or a library is packaged and deployed as a bundle deployment package. A bundle has a project structure in
the development environment.

Important
Application development or smart library development must be done by using the developer account.
A developer account is set with an administrator role. The developer account does not require the
domain identifier to log in. You can login to BMC Helix Innovation Studio with just the user name
without the developer.com domain.
Ensure that the Developer ID is set for the BMC Helix Innovation Suite server. The Developer ID is used
to uniquely identify your organization. When the SaaS administrator creates the Bundle project, the
archetype assigns the Developer ID.
The following video (5:41) provides details on how to create a maven project using BMC Helix Innovation Suite SDK and
IDE and how to deploy the project to your system.
https://youtu.be/_aXeUOGRlNY
To create a new project

To create a new application project or smart library project, use the Maven archetypes (simple archetype or lib
archetype) with the BMC Helix Innovation Suite SDK. For your projects, decide where you want your project code to
reside. It is recommended that not to place the project code at the BMC Helix Innovation Suite SDK location. For
example, you can create a new directory projects in the root directory.
1. On the command prompt, navigate to the directory to create project.

For example: C:\projects
2. Create a project for application development or library development.
If you want to create a project for application development, run the following command:
mvn archetype:generate -DarchetypeGroupId=com.bmc.arsys -DarchetypeArtifactId=rx-sdk-archetype-

simple -DarchetypeCatalog=local
where,
Archetype Argument Description
-DarchetypeGroupId=com.bmc. Maven uses BMC archetypes

arsys
-DarchetypeArtifactId=rx-sdk- Selects the simple application archetype. This sets the POM file to create an application package
archetype-simple and generates a working UI.
-DarchetypeCatalog=local Uses only the local catalog
If you want to create a project for library development, run the following command:
mvn archetype:generate -DarchetypeGroupId=com.bmc.arsys -DarchetypeArtifactId=rx-sdk-archetype-

lib -DarchetypeCatalog=local
where,

-DarchetypeGroupId=com.bmc. Maven uses BMC archetypes

arsys
-DarchetypeArtifactId=rx-sdk- Selects the library archetype. This sets the POM file to create a library package and does not
archetype-lib generates a working UI.
For more information on Maven archetype, see Maven archetype plugin in Maven documentation.
3. The command (for library archetype or simple application archetype) starts the archetype plugin in interactive
mode and prompts for the property values.
Enter the values for the following properties:
Property Description Sample values for Sample values for
application library
development development
groupId Project group ID. The ID usually follows the naming conventions of Java package names. com.example com.example
Note: You must provide the Developer ID as the groupID value.
artifactId Project ID that is used as a part of filename. It usually has a short name as the project is suggestion-box work-order-lib
already name spaced by the groupId.
Notes:
The artifactId cannot be a combination of:
'-' (hyphen) and numeric character. For example, work-order-lib-12 is not a valid
artifactId.
Upper case and lower case letters. For example, Work-Order-Lib is not a valid artifactId.
For more information, see Naming conventions in the Apache Maven
documentation.
version Project version. You must provide the value in the following format: 1.0-SNAPSHOT 1.0-SNAPSHOT
See Version number rules in Maven documentation and Guidelines for versioning
and undeploying an application (see page 320).
package Default Java package for the project. The default value is groupId value. com.example com.example
name Friendly name of the bundle. This is used by the archetype to display the name of the Suggestion Box Work Order
application on the login page and in the BMC Helix Innovation Studio.
4. Confirm the configuration of all the properties.
5. If any dependencies on other smart bundles, add the dependencies. See Using components from another
developer's Digital Service application or library (see page 815).
6. If any third party dependencies, add the third party dependencies. See Using code from open source (see page
816).
After you create the application (or smart library) project, you must modify the user credentials in the project pom.xml
file. See 754913794 (see page 806).
To set up the development server environment properties in the project pom.xml file
1. Open the parent pom.xml file located in project folder. For example, projects\work-order-lib\pom.xml.
2.
2. Modify the properties section that specifies the environment information provided with your Development
Server instance.

<developerUserName>developer</developerUserName>
<developerPassword>mydeveloperpw</developerPassword>


<webUrl>https://developer.innovate.bmc.com</webUrl>

where, developerUserName is developer user that you create while requesting a sandbox. You do not need to use
the domain name developer.com.
Note
You must provide the webUrl of your sandbox.
3. If you plan to use the Grunt utility for active debugging of Javascript, you must add the correct api-host in the
parent project bundle\bundle.conf.json file. By default, it is generated as localhost, you must update it to match
your development server host. The host typically remains as localhost that is where the JavaScript source code
resides. For example:
"options": {
"livereload-port": 39005,
"skip-tests": "true",
"skip-validation": "true",
"api-host": "developer101.innovate.bmc.com",
"api-port": 443,
"api-https": true,
"host": "localhost",
"port": 9005
},
After you create a new project, add the dependencies and define the user (user credentials in the pom.xml file), you
should create a deployment package and deploy the package to the BMC Helix Innovation Suite server. See Deploying
your Digital Service application for the first time to start working in BMC Helix Innovation Studio (see page 813).
To set up dependencies that are needed for your bundle

The dependencies on the other bundles are declared in the bundle\pom.xml file. If your application or smart library
intends to make use of workflows for approvals, assignments, or the Foundation library, add the dependencies in the
bundle\pom.xml, so that these capabilities can be tailored after the application is deployed. You can use the following
content for the rx-sdk.bundledependencies tag. The syntax is bundleid;version using commas to separate each bundle.
<properties>


<rx-sdk.bundleDependencies>standardlib;${rx-sdk.version},com.bmc.arsys.rx.approval;${rx-sdk.version},
com.bmc.arsys.rx.assignment;${rx-sdk.version},com.bmc.arsys.rx.foundation;${rx-sdk.version}</rx-sdk.
bundleDependencies>
</properties>
Projects created by the archetype

The Maven archetype creates the following projects:
Project Location
Parent project <artifactId>/
Bundle project <artifactId>/bundle/
Package project <artifactId>/package/
The application bundle project and the deployment package project have their own build system pre-generated in the
form of a Maven POM file. You can import these projects in Eclipse to customize and debug the application or library.
Smart bundle attributes

Smart bundle (application or smart library) attributes and properties are defined in the project pom.xml file and bundle
pom.xml file respectively.
The following table describes the project pom.xml file and bundle pom.xml file:
pom. Description Sample code

xml file
Project The project pom.xml file consists of the smart bundle attributes. The attribute values are The following code snippet illustrates a sample maven-
pom. defined in the maven-bundle-plugin configuration. You can edit this file to modify the bundle-plugin configuration in the project pom.xml file:
xml file attribute values.
<plugin>
<groupId>org.apache.felix<
/groupId>
<artifactId>maven-bundle-
plugin</artifactId>
<version>${maven-bundle-plugin.
version}</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-Name>${rx-sdk.
bundleName}</Bundle-Name>
<Bundle-
SymbolicName>${rx-sdk.bundleId}<
/Bundle-SymbolicName>
<Bundle-Activator>com.
mygroupid.bundle.MyApplication<
/Bundle-Activator>
<Import-Package>*;
resolution:=optional</Import-
Package>
<Embed-Dependency>*;
scope=compile|runtime</Embed-
Dependency>
<Bundle-
Description>${rx-sdk.
bundleDescription}</Bundle-
Description>

pom. Description Sample code

xml file
<Bundle-Vendor>${rx-
sdk.bundleDeveloperId}</Bundle-
Vendor>
<RxBundle-
DeveloperName>${rx-sdk.
bundleDeveloperName}</RxBundle-
DeveloperName>
<RxBundle-
FriendlyName>${rx-sdk.
bundleFriendlyName}</RxBundle-
FriendlyName>
<RxBundle-
IsApplication>${rx-sdk.
bundleIsApplication}</RxBundle-
IsApplication>
</instructions>
</configuration>
</plugin>
Bundle By default the bundle pom.xml file consists of the properties that are used to define The following code snippet illustrates a sample
pom. bundle specific values.You can edit this file to customize your smart bundle. properties configuration in the bundle pom.xml file:
xml file
<properties>
<rx-sdk.bundleId>${project.
groupId}.${project.artifactId}</rx-
sdk.bundleId>
<rx-sdk.bundleName>${project.
artifactId}</rx-sdk.bundleName>
<rx-sdk.
bundleFriendlyName>${project.name}<
/rx-sdk.bundleFriendlyName>
<rx-sdk.
bundleDescription>${project.
description}</rx-sdk.
bundleDescription>
<rx-sdk.
bundleDeveloperId>${project.
groupId}</rx-sdk.bundleDeveloperId>
<rx-sdk.
bundleDeveloperName>${project.
groupId}</rx-sdk.
bundleDeveloperName>
<rx-sdk.bundleIsApplication>tru
e</rx-sdk.bundleIsApplication>
<properties>
The following table describes the smart bundle properties:
Smart bundle Sample value Bundle descriptor pom.xml node in How to define value Default value Required Description
property method the maven-
bundle-plugin
section
ID com.bmc. getIid() <Bundle- Set property in the ${project. Yes

lunchorder SymbolicName> project\pom.xml file: groupId}.${project.
artifactId}
${rx-sdk.bundleId}

Smart bundle Sample value Bundle descriptor pom.xml node in How to define value Default value Required Description
property method the maven-
bundle-plugin
section
Globally
unique
identifier
for the
bundle (i.e.,
Bundle Id)
Short Name lunchorder getName() <Bundle-Name> Set property in the ${project. Yes Bundle
project\pom.xml file: artifactId} short
name. Not
${rx-sdk.bundleName} a friendly
name.
Friendly Lunch Order getFriendlyName() <RxBundle- Set property in the ${project.name} Yes Friendly
Name FriendlyName> project\pom.xml file:${rxbundle
sdk. name.
bundleFriendlyName}
Description An application getDescription() <Bundle- Set property in the ${project. Yes Friendly
which allows Description> project\pom.xml file: description} long
users to place description
${rx-sdk.
lunch orders. of bundle.
bundleDescription} Derived
during
project
creation.
Version 1.0.0.0 getVersion() <Bundle- Set property in the ${version} Yes Version of
Version> project\pom.xml file: the bundle
${version}
Developer ID com.bmc developerId() <Bundle- Set property in the ${project. Yes Id of

Vendor> project\pom.xml file: groupId} bundle
author. Not
${rx-sdk.
a friendly
bundleDeveloperId} name.
Developer BMC Software getDeveloperName() <RxBundle- Directly add <RxBundle- ${project. No Friendly
Name DeveloperName> DeveloperName> node groupId} name of
to the maven-bundle- developer.
plugin configuration Not in
archetype
or manifest
by default.
Is true getIsApplication() <RxBundle- Set property in the <based on

Application? IsApplication> project\pom.xml file: archetype used>
${rx-sdk.
bundleIsApplication}
Smart Bundle com.bmc.arsys.rx. getBependentBundles() <RxBundle- Directly add <RxBundle- standardlib;9.5.00-

Dependencies standardlib;1.0, Dependencies> Dependencies> node to SNAPSHOT
com.bmc.arsys.rx. the maven-bundle-
approval;2.0 plugin configuration


Deploying your Digital Service application for the first time to start working in BMC Helix Innovation Studio (see page 813
)
Deploying your Digital Service application for the first time to start working in BMC Helix Innovation Studio
Before you begin make sure that you create a project for Digital Service application (or smart library) development . To
manage the data for the application (or smart library), you should deploy the deployment package to the BMC Helix
Innovation Suite server.
To deploy a package
Navigate to the <artifactId> directory (parent folder) of your application project (or smart library project) and run the
following command:
mvn clean install -Pdeploy
The following video (5:07) provides details on how to deploy the Maven project to BMC Helix Innovation Suite server.
https://youtu.be/A7B6xXoElw0
For example:
\projects> cd suggestion-box
\projects\suggestion-box> mvn clean install -Pdeploy
Important
As a developer, after you complete the initial deployment, if you deploy the package multiple times using the
command mvn clean install -Pdeploy duplicate log configurations are created for the application and the
following error occurs:
DeploymentPackage [packageDeployStatus=Error, packageName=com.example.test-smart-app,

packageVersion=1.0.00-SNAPSHOT, currentServersInSync=true, newlyAddedServers=[],
jarToServerDeployStatusMap={onbmc-s=ReadyDeploy}, ErrorMessages=PARSE_DEF_IMPORT_STATUS:
IMPORTING_SERVER:onbmc-s:10.133.77.92
IMPORT_APPLICATION_ERROR: ERROR (382): The value(s) for this entry violate a unique index that has
been defined for this form; Error importing record 1: FormName: AppLocalConfig_ComponentBase
WARNING (55): The following item was not imported
As a workaround, export the application after you complete the initial deployment, by using the command
mvn install -Pexport.
When you deploy the package to BMC Helix Innovation Suite server,

The deployment package is a zip file (for example, com.example.suggestion-box1.0SNAPSHOT.zip ) is created. It is

located in the target directory in the application package directory (for example, \projects\suggestion-
box\package\target\com.example.suggestion-box1.0SNAPSHOT.zip).
The zip file consists of the following folders and files:
db
record
<record-definition-name1>.def
<record-definition-name3>.options
<record-definition-name3>.data
<record-definition-name3>.delete
process
<process-definition-name1>.def
rule
<rule-definition-name>.def
association
view
<view-definition-name>.def
named-list
<named-list-definition-name1>.def
localized-string
<localized-strings.def>
configuration.data
role.data
code <jar file>
manifest file
The .jar file is used to store the code for your application and the .def files are used to store definitions for your
application.
You can access the application in BMC Helix Innovation Studio.

Note
You must login to BMC Helix Innovation Studio using the credentials of the developer account. A
developer account is set with an administrator role. The developer account does not require the
domain identifier to log in. You can login to BMC Helix Innovation Studio with just the user name
without the developer.com domain.
In the BMC Helix Innovation Studio, from the application page, you can launch the application using the Launch
Deployed Application link .
You can import the bundle project in Eclipse. Using Eclipse you can modify the Java code and test the code.
To import the application to Eclipse, you should import the POM file to Eclipse using the Import command (File >
Import> General > Maven Projects) and set the root folder to the bundle directory of the project.
Note
You cannot rename the bundle after importing it to Eclipse.

Using components from another developer's Digital Service application or library (see page 815)
Using components from another developer's Digital Service application or library

Before you begin make sure that you create a project and a deployment package for Digital Service application (or smart
library) development.
If your smart bundle has dependency on the other available smart bundles, you should specify the dependency in the
pom.xml file located in the bundle project. For example, your bundle may have a dependency on the Approval library.
Notes

You cannot configure smart bundles with circular dependencies on each other. A circular dependency
is a relation between two or more bundles which either directly or indirectly depend on each other to
function properly.
You must deploy a bundle’s dependencies before you deploy a bundle to BMC Helix Innovation Suite.
To add the dependency in the pom.xml file
1. Open the pom.xml file located in bundle project. For example, projects\work-order-lib\bundle\pom.xml .
2. Add the dependency in the maven-bundle-plugin configuration, using the following syntax:
,<groupId>.<artifactId>;<version>,
Note: The dependencies are delimited by commas and the version information is separated using a semicolon.
For example, if you want to add the dependency on the Standard library and Approval library, use the following
syntax:
<RxBundle-Dependencies>standardlib;9.5.00-SNAPSHOT,com.bmc.arsys.rx.approval;9.5.00-SNAPSHOT</RxBundle-
Dependencies>
The following is the sample of maven-bundle-plugin configuration in the bundle pom.xml file :
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>${maven-bundle-plugin.version}</version>
<configuration>
<instructions>
<Bundle-Name>${rx-sdk.bundleName}</Bundle-Name>
<Bundle-SymbolicName>${rx-sdk.bundleId}</Bundle-SymbolicName>
<Bundle-Activator>com.example.app1.bundle.App1Application</Bundle-Activator>
<Import-Package>*;resolution:=optional</Import-Package>
<Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
<Bundle-Description>${rx-sdk.bundleDescription}</Bundle-Description>
<Bundle-Vendor>${rx-sdk.bundleDeveloperId}</Bundle-Vendor>
<RxBundle-DeveloperName>${rx-sdk.bundleDeveloperName}</RxBundle-DeveloperName>
<RxBundle-FriendlyName>${rx-sdk.bundleFriendlyName}</RxBundle-FriendlyName>
<RxBundle-IsApplication>${rx-sdk.bundleIsApplication}</RxBundle-IsApplication>
<RxBundle-Dependencies>standardlib;9.5.00-SNAPSHOT,com.example.somelibrary;1.0.00-SNAPSHOT<
/RxBundle-Dependencies>
</instructions>
</configuration>
</plugin>

Using code from open source (see page 816)
Using code from open source

Before you begin make sure that you create a project and a deployment package for Digital Service application (or smart
library) development .

You can use the Java code from a third party code (such as code that is available as open source in Github) in your smart
bundle. To use the third party code in your smart bundle, y ou need to specify the dependency in the pom.xml file
located in the bundle project.
Notes
You cannot configure smart bundles with circular dependencies on each other. A circular dependency
is a relation between two or more bundles which either directly or indirectly depend on each other to
function properly.
You must deploy a bundle’s dependencies before you deploy a bundle to BMC Helix Innovation Suite.
To add the third party dependencies to your smart bundle
1. Add the dependency of the third party code in the pom.xml file located in the bundle project. For more
information see, Dependencies.
For example, in the work-order-lib\bundle\pom.xml file, add a dependency of a library from Apache Commons to
perform CSV parsing .
<dependencies>


<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-csv</artifactId>
<version>1.1</version>

<scope>compile</scope>
</dependency>
2. Set up the dependencies in the maven bundle plugin .

For example:
. . .
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>${maven-bundle-plugin.version}</version>
<configuration>
<instructions>
<Bundle-Name>${rx-sdk.bundleName}</Bundle-Name>
<Bundle-SymbolicName>${rx-sdk.bundleId}</Bundle-SymbolicName>
<Bundle-Activator>com.example.bundle.MyApplication</Bundle-Activator>
<Import-Package>*;resolution:=optional</Import-Package>
<Bundle-Description>${rx-sdk.bundleDescription}</Bundle-Description>
<Bundle-Vendor>${rx-sdk.bundleDeveloperId}</Bundle-Vendor>
<RxBundle-FriendlyName>${rx-sdk.bundleFriendlyName}</RxBundle-FriendlyName>
<RxBundle-IsApplication>${rx-sdk.bundleIsApplication}</RxBundle-IsApplication>



</instructions>
</configuration>
</plugin>
3. Run the following command to navigate to the bundle directory and build the bundle :
mvn clean install
For example:
projects> cd work-order-lib\bundle
bundle> mvn clean install
4. Verify the bundle.

For example, open the bundle work-order-lib\bundle\target\com.example.work-order-lib.1.0-SNAPSHOT.jar and
check the dependent library is distributed at the root location of the bundle.
5. Load the pom.xml file in Eclipse. Ensure that the project (for work-order-lib) is updated with the new pom.xml file
settings.
This enables the use of CSV library.
6. Modify the required class in the Java code to use the library.
7. Build and deploy the new code using the following command:
mvn clean install -Pexport -Pdeploy

Applying a license to your application (see page 818)
Applying a license to your application

When you create an application, you can set your application as requiring a license. Setting the application as requiring a
license protects your IP so that only licensed tenants can use the application. After an application is deployed, it is
available to all tenants. When the application requires a license, only those tenants with an appropriate license can see
and use the application. The tenants without a license cannot log in to the application or see it in BMC Helix Innovation
Studio, and therefore cannot customize it.
Important
After you apply a license to the application, you cannot revoke the license for that application.

Setting a BMC or partner application for unlimited users

Licensed BMC applications or partner-developed applications, can allow unlimited users within a tenant to log in to an
application. When the SaaS administrator assigns the application license to the tenant, the administrator is no longer
required to assign individual licenses to the users.
When licensing an application, you can set the -DenforceEndUserLicenses parameter in the Maven command to one
of the following values:
True—Individual end user licenses is enforced.
False—Individual end user licenses is not enforced.
The default value of the -DenforceEndUserLicenses parameter is True.
Before you begin

Ensure that you have created and customized the application. For more information, see Preparing to develop a Digital
Service application (see page 799).
To license an application
1. N avigate to the <artifactId> directory that is the parent folder.
mvn com.bmc.arsys:rx-sdk-maven-plugin:license -N -DappAuthorType=Number -DenforceEndUserLicenses=true/f

alse
and specify either of the following values for application AuthorType ( -DappAuthorType) and End user Licenses (-
DenforceEndUserLicenses) parameters:
Application type Value for -DappAuthorType Value for -DenforceEndUserLicenses
BMC application 1
True—If you want the administrator to assign individual
Partner application 2 licenses to the users. This setting means that end-user
licenses are enforced for the application.
False—If you do not want the administrator to assign

individual licenses to the users. This setting means that
end-user licenses are not enforced for the application.
Custom application 3 Not applicable The combination of the -DappAuthorType and -

DenforceEndUserLicenses is invalid for custom applications.
When to apply license to your development server?

If you apply a license to your application and you want to develop the application on the development server, you must
apply the application license to the development server. See Assigning application licenses to users (see page 759).

Deploying the custom code-based applications to development environments (see page 915)

Developing collaborative Digital Service applications

In a development team, all developers have their own sandbox development environments, which include the BMC Helix
Innovation Suite SDK and a cloud-based instance of the BMC Helix Innovation Suite. In a development environment, an
option to install a master or single BMC Helix Innovation Suite platform is not available. Therefore, if multiple developers
want to simultaneously work on a Digital Service application and access the updates, the developers must set up a
collaborative development environment.
A collaborative development environment enables multiple developers to perform the following tasks:
Easily work on a single environment from different locations
Participate in updating an application simultaneously
Maintain all project files in a source control system
Obtain the latest source code files easily
Process for setting up a collaborative development environment

In a collaborative development environment, you can do one of the following tasks:
Collaborate with multiple developers for working on a single application bundle (see page 820)
Collaborate with multiple developers for working on their individual application bundles (see page 823)
For multiple developers to access and update the application bundles, you must set up a collaborative development
environment as described in the following process:
Task User Action
1 A single Creates a new bundle project by using the archetype.

developer
For more information, see Creating a Project using Maven and the Archetype (see page 806).
2 A single Optionally builds, deploys, and tests the bundle project. The developer is not required to export or deploy the project in BMC Helix
developer Innovation Studio.
For information about building and deploying a project, see Creating a Project using Maven and the Archetype (see page 806) and
Deploying the custom code-based applications to development environments (see page 915).
3 A single Checks in the bundle project source code and definition file to the source control system.
developer
The following files are checked in:
Project folder, including the bundle and package folders
The following folders are not checked in:
bundle\node_modules
bundle\target and package\target
Process for multiple developers working on a single application bundle

The following table describes the tasks that multiple developers must perform to work on a single application bundle.
Task User Action
1 All developers Coordinate to ensure that only a single dedicated developer works and updates individual definition files at any point of
time.

Task User Action
2 Single dedicated developer Performs the following tasks to build the project and make it available to all developers in a team:
who works on
and updates the definitions 1. Gets the latest code and definitions from the source control system.
2. Builds and deploys the project in the environment.
3. Uses BMC Helix Innovation Studio to create, modify, or delete the definitions.
4. Tests the project.
5. Exports the definitions.
6. Commits the updated definition file and the modified project files into the source control system.
7. Notifies other developers that a new definition file has been checked in and is now available for use.
For more information, see the following topics:
3 All developers Perform the following tasks to access the latest application and update the definitions:
1. Undeploy existing version of BMC Helix Innovation Suite from their individual sandbox instances of BMC Helix
Innovation Suite.
2. Get the latest source code and definitions from source control system.
3. Build and deploy the project to individual sandbox instances of BMC Helix Innovation Suite.
4. Use BMC Helix Innovation Studio to create, modify, or delete the definitions.
5. Test the project.
Creating a Project using Maven and the Archetype (see page 806)Deploying the custom code-based
applications to development environments (see page 915)
The following illustration describes different stages when multiple developers are working on a single application bundle:

Best Practice
To enable better collaboration, use libraries of small granularity to adhere to good modular design and to
minimize conflict. After you reach the limit of 1000 objects in a module, avoid adding further objects. Critically
examine objects before you add them to the module.
Limitation
In a collaborative environment, the following limitation is applicable when updating definitions of a single application:
Changes made by only one developer for a particular definition file can be committed to the source control
system at a given point of time.
If multiple developers update a single application bundle, then their changes are not checked in to the source
control system. Only the single dedicated developer can save and check in the changes.
A developer who is not the dedicated developer can save the project changes by performing the following tasks:
1. Coordinate with other developers and become the single dedicated developer to work on the bundle
project.
2.
2. Undeploy the existing project from the sandbox environment.
3. Update the definitions and check in the updated files to the source control system (see page 820).
Process for multiple developers working on individual application bundles

After the developer who built the bundle project has checked in the updated project files, all developers in the
development team can obtain the bundle project and deploy it to their sandbox instances of BMC Helix Innovation Suite.
The developers must perform the following steps to deploy and update the application bundle in their sandbox
environments:
Task User Action
1 All developers Undeploy existing version of BMC Helix Innovation Suite from their individual sandbox instances.
For more information, see Deploying the custom code-based applications to development environments (see page 915).
2 All developers Perform the following steps for deploying the application to the sandbox instances:
1. Get the latest source code and definitions from source control system.
2. Build and deploy the project in the environment.
3. Use BMC Helix Innovation Studio to create, modify, or delete the definitions.
4. Test the project.

To start working in BMC Helix Innovation Studio, deploy your Digital Service application for the first time (see page 813).
Creating a custom service in Java

A service provides business logic to a smart bundle. The REST API delegates to the service to fulfill the API request. Each
method that you define in the service can be exposed to BMC Helix Innovation Studio as an Action Type. An Action Type
can be used to create a Service Task in business processes or Custom Rule Action in business rules. The advantage of
this model is that you can extend the platform by creating your own service, and integrate it seamlessly in BMC Helix
Innovation Studio. Services can be used by the application business analyst as designer components of the BMC Helix
Innovation Studio to build processes and rules.
Creating a service class

To create a service class, you must first implement it as a service interface. This interface is a marker interface that
makes your service and its actions discoverable by the platform. Your service class can depend on other services.
Framework services are available through ServiceLocator, for example ServiceLocator.getRecordService() returns
Record Service. To access services defined in other bundles, you can use Bundle Service, ServiceLocator.
getBundleService.getService(serviceName).
To create a service class, perform the following steps:
1.
1. Create a Java class which implements com.bmc.arsys.rx.services.common.Service.

For example:
package com.example.taskmanager.service;
. . .
/**
* The Class TaskService that manages tasks.
*/
public class TaskService implements Service {
. . .
2. Add methods required for business logic to the service class.
3. Register the service in the bundle class.

For example:
package com.example.taskmanager.bundle;
. . .
import com.example.taskmanager.service.TaskService;
. . .
/**
* Task Manager application bundle.
*/
public class TaskManagerApplication extends RxBundle {
. . .
@Override
. . .
registerService(new TaskService());
. . .
}
. . .
}
4. F or service methods that need to be available in BMC Helix Innovation Studio as Action Type, please annotate
them with @Action . When you deploy the smart bundle, Action Types show up in the designer palette . For more
information, see Annotating methods as actions (see page 825).
For example:
. . .
/**
* The Class TaskService that manages tasks.
*/
public class TaskService
implements Service {
. . .
@Action
public void updateTaskStatus(@ActionParameter(name = "taskID") @NotBlank String taskId,, @ActionPar
ameter(name = "status") @NotBlank String status) {
. . .
}
. . .

5. Compile the code using Maven.
6. Deploy the service interface using the following command:
7. Navigate to Process designer, Rule designer and test the service that you have created and deployed.
Note
In a bundle, do not declare actions with same names for different services.
For example:
If a bundle has two different services, service1 and service2, you should not declare an action with the same
name for service1 and for service2.
If you have duplicate action names, you can use the @Action annotation name property.
Annotating methods as actions

You can develop reusable methods with declared parameters that can be used by process definitions and rule
definitions. You can annotate the required parameters with the following standard bean validations:
@NotNull--CharSequence, Collection, Map or Array object is not null, but can be empty
@NotEmpty–CharSequence, Collection, Map or Array object is not empty
@NotBlank–The string is not null and the trimmed length is greater than zero
For example:
import javax.validation.Valid;
import javax.validation.constraints.NotNull;
import org.hibernate.validator.constraints.NotBlank;

. . .
@Action
public TaskResult createTask(@ActionParameter(name = "submitter") @NotBlank String submitter,
@ActionParameter(name = "summary") @NotBlank String summary,
@ActionParameter(name = "taskName") String taskName,
@ActionParameter(name = "priority") @NotBlank String priority) {
...
}
}

Working with action parameter bean validation

For validating action parameters, add the following code to the pom.xml file in custom bundle:


<dependency>
<groupId>javax.validation</groupId>
<artifactId>validation-api</artifactId>
<version>${javax.validation.api.version}</version>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
<version>${hibernate-validator.version}</version>
</dependency>

<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<compilerArgs>
<arg>-parameters</arg>
</compilerArgs>
</configuration>
</plugin>
Related topics
Enabling logging for a Digital Service application (see page 981)
Enabling browser logging in a Digital Service application (see page 987)
Creating a custom user interface with AngularJS

BMC Helix Innovation Suite provides you the facility to create custom visual components that can be integrated in Digital
Service applications by using BMC Helix Innovation Studio. You can create a view component using AngularJS directives.
The view components you create are available in the View designer and can be used in different view definitions.
Related topic
Guidelines to create custom view components that are accessible (see page 320)
Creating custom view components

The View designer consists of built-in view components (like record grid, record editor). You can create your own
custom view components. A view component is a regular AngularJS directive. To create a custom view component you
can create an AngularJS directive and register it to make it available in the View designer.
For more information on directives, see Creating Custom Directives.
Note

You must ensure that you follow naming conventions (namespacing) for all AngularJS object names and all
HTML filenames in shared code. See Naming conventions for AngularJS objects (see page 869).
View component files

Anatomy of a view component consists of the following files:
File Description
<view-component-name>.module.js AngularJS module for the view component
<view-component-name>.config.js Configuration of the AngularJS module that includes view component registration
<view-component-name>.directive.js Runtime directive that is bootstrap in runtime
<view-component-name>.design.directive.js Design-time directive that is used in the BMC Helix Innovation Studio
Additional code or resources Supporting code and utilities for the view component
<view-component-name>.directive.html HTML template for runtime directive
<view-component-name>.design.directive.html HTML template for design-time directive
<view-component-name>.design.service.js Defines the design manager of the view component
<view-component-name>.model.service.js Defines the model of the view component
Additional code or resources Resources like icons, images and styles
For example:
Star-rating view component consists of the following files:
To create a custom view component
1. Define a Angular module for your view component that must have isolated scope and rxConfiguration
configuration property.
Sample code:
angular.module('com.example.samplelibrary.view-components.customer-location')
.directive('customerLocation', function () {
return {
restrict: 'E',

templateUrl: '/scripts/view-components/customer-location/com-example-samplelibrary-
customer-location.html'
// should have isolated scope

scope: {
}
};
});
2. Register the view component.

To make a view component available for use in the View designer, you must register the view component by
using the registerComponent method of rxViewComponentProvider. The following code illustrates view
component basic registration:
var componentDescriptor = {
name: 'Customer Location',
type: 'com-example-samplelibrary-customer-location',
bundleId: 'com.example.samplelibrary'
};
rxViewComponentProvider.registerComponent(componentDescriptor);
Component descriptor properties

The following table describes the component descriptor properties:
name Name of the view component that is displayed in the View designer.
type Name of the runtime directive.
bundleId Bundle ID of the bundle in which the view component is defined.
icon Name of an image from the icon library available in BMC Helix Innovation Suite SDK.
group Group name in the View designer stencil under which the view component is displayed.
propertiesByName Array of property descriptors. Values for these properties are defined during design time and can be either constants or expressions.
See propertiesByName configuration (see page 828).
Properties for design time
designType Name of the design-time directive See Design time configuration (see page 829).
designManagerService Name of the angular service for managing component in design time.
propertiesByName configuration
This configuration describes all properties which are needed for the view component during runtime.
Property Description Default value
name Name of the property
isConfig Set this configuration property if you want to make it available in the View designer inspector. false
isProperty Defines if this property can be used in expressions and exposed in the data dictionary. false
isRequired Defines if this property is required. false
enableExpressionEvaluation Defines if the property value should be evaluated as an expression in runtime. false

Property Description Default value
See Expressions (see page 834).
localizable Defines the value of this property is localizable. false
defaultValue Defines the default value for this property.
The following code illustrates registration of a view component with propertiesByName configuration:
rxViewComponentProvider.registerComponent({
name: 'Customer Location',
type: 'com-example-samplelibrary-customer-location',
bundleId: 'com.example.samplelibrary',
propertiesByName: [
{
name: 'customerName',
isConfig: true,
isProperty: true,
isRequired: true
},
{
name: 'selectedCustomer',
isPropery: true
}
]
});
Design time configuration

By default, a view component does not require any custom configuration logic. The View designer automatically creates
all the required configurations based on the component descriptor. You may add custom configuration logic for
configurations such as:
complex inspector configuration
saving and restoring complex component definition
controlling the appearance of the view component in the View designer canvas
complex user input validation
To implement the custom configuration, perform the following steps:
1. Create a model that extends the default rxViewComponentModel.
angular
.module('com.bmc.samplelibrary.view-components.customer-location')
.factory('CustomerLocationModel', function (rxViewComponentModel) {
var CustomerLocationModel = rxViewComponentModel.extend({
initialize: function(){
// launch parent initialize method
rxViewComponentModel.prototype.initialize.apply(this, arguments);
// provide your custom initialization

},
// ... customize other model methods

});
return CustomerLocationModel;

});
2. Create a design manager.

Design manager is a regular angular service. To register a service as a view component design manager, it must be
specified in the view component descriptor.
// create angular service

angular.module('com.example.samplelibrary.view-components.customer-location')
.factory('comExampleSamplelibraryCustomerLocationDesignManager', function(CustomerLocationModel){
return {
getModel: function(componentDefinition){
return new CustomerLocationModel();
},
someCustomeMethod: function(){
//...
}
};
});
// register service as design manager

designManagerService: 'comExampleSamplelibraryCustomerLocationDesignManager',
// ...
});
When you provide a custom design manager, the View designer always uses the custom design manager and not
the default design manager service.
3. Create a design time directive.

Design time directive is a regular Angular directive. See Design time directive (see page ).
angular.module('com.example.samplelibrary.view-components.customer-location)
.directive('comExampleSamplelibraryCustomerLocationDesign', function () {
return {
restrict: 'E',
templateUrl: '/scripts/view-components/customer-location/com-example-samplelibrary-
customer-location-design.html'
scope: {
}
};
});
4. Register the design-time directive by using the designType property of the component descriptor.
// register design directive

designTime: 'com-example-samplelibrary-customer-location-design',
// ...
});

Design-time directive
Design-time directive represents how a view component is displayed on the canvas in the View designer. It provides the
functionality for configuring and storing the view component properties in the component definition object. The View
designer uses the design manager for creating the model which can store the definition.
Component definition
Component definition is a representation of a view component in a view definition.
Sample component definition:
{
"resourceType": "com.bmc.arsys.rx.services.view.domain.ViewComponentDefinition",
"guid": "dac5ae7b-7bac-4997-97e0-4ef59364e011",
"type": "com-example-samplelibrary-customer-location",
"propertiesByName": {
"customerName": "Customer A"
}
}
Where,
Definition key Type Value
resourseType string com.bmc.arsys.rx.services.view.domain.ViewComponentDefinition
guid string Unique GUID
type string The type used during the component registration
propertiesByName object
{
"customerName": "Customer A"
}
The configuration is passed to the runtime directive.

The value must be a string.
rxViewComponentModel
rxViewComponentModel is the default model that is used by a view component. You can extend this model to create a
design manager. The rxViewComponentModel provides the following feature:
stores component configuration
configures the property pane
implements validation
saves component definition
The following table lists the rxViewComponentModel properties :
Property Type Description Example
guid string Unique GUID dac5ae7b-7bac-4997-97e0-4ef59364e011
type string The type used during the component registration

Property Type Description Example
com-example-samplelibrary-customer-
location
rxData object Contains data that is persisted to propertiesByName property of the component
definition.
{
customerName: "Customer
A"
}
rxInspector object Contains configuration for the view component property pane.
{
inputs: {
rxData: {
title: {
label: 'Tit
le',
type: 'text
',
group: 'gen
eral',
index: 1
}
}
},
groups: {
general: {
label: 'General
',
index: 1
}
}
}
The following table lists the rxViewComponentModel methods:
Method Type Argument Description
initialize sync modelProperties (object) Executed once the model instance is created.
(Initial data that is passed to the model Used for initial model configuration, adding listeners, and so on.
during creation)
persist sync viewDefinition (object)

Executed each time the model data is changed.
(View definition object)
Used for creating or updating component definition.
describeViewComponent sync
Called by default implementation of the persist method.
Returns view component definition object.
updateInspectorConfig async
Executed each time the view component is selected on the View
designer canvas.
Used to update rxInspector model property
validate async viewDefinition (object)

Executed each time the model data is changed.
(View definition object)

Method Type Argument Description
Returns validation issues (array)
Validation issues returned by this method are displayed in the

Validation Issues tab.
See Validation issue (see page 833).
Validation issue
Validation issue is an object that describes the details of a single view component configuration validation issue.
Validation issues are displayed on the Validation Issues tab in the view designer.
The format for validation issue object is as follows:
Property Value Example value
elementId View component GUID 'dac5ae7b-7bac-4997-97e0-4ef59364e011'
elementName User friendly view component name 'Customer Location'
propertyName Name of view component property (as defined in propertiesByName) 'customerName'
message Validation message to display 'Customer name cannot be blank.'
type 'error'
error
warning
info
The following image illustrates how the properties defined in the validation issue object appear in the View designer:
Design manager
Design manager is to create view component model and configure the data dictionary for the expression builder. If you
do not provide a design manager when you register a view component, the default manager, r xViewComponentManager
is used.

Design manager methods
Method Description Type Arguments Return
getModel rxViewComponentManager.getModel sync model

componentDefinition
(componentDefinition, componentDescriptor); instance
componentDescriptor
Returns an instance of the model.
Sample code:
getModel: function (componentDefinition) {

return new rxViewComponentModel({
guid: 'dac5ae7b-7bac-4997-97e0-
4ef59364e011',
type: 'com-example-samplelibrary-
customer-location',
rxData: {
customerName: componentDefinition.
propertiesByName.customerName
},
rxInspector: {
inputs: {
rxData: {
customerName: {
label: 'Customer Name',
type: 'rx-inspector-
expression-node-field',
group: 'properties',
index: 0
}
}
},
groups: {
properties: {
label: 'General',
index: 1
}
}
}
});
}
getDataDictionaryBranch rxViewComponentManager. async data

componentDescriptor
getDataDictionaryBranch dictionary
(componentDescriptor, componentDefinition, componentDefinition configuration
expressionTypeMap); expressionTypeMap
Returns data dictionary that is used by the expression builder and the
property inspector.
getSettableProperties rxViewComponentManager.getSettableProperties async settable

componentDescriptor
(componentDescriptor, componentDefinition); properties
componentDefinition
Returns properties that can be set during runtime by setProperty
actions.
Expressions
An expression is a string that can be evaluated to a value during runtime.

For example:
expression: '1 + 2'

evaluated value: 3
When you register a view component, you can mark any property with enableExpressionEvaluation. It means that the
property value is automatically evaluated at runtime and passed to the runtime directive. Expressions may contain
references to properties of multiple view components in the current view, as well as view input parameters and
keywords. This mechanism allows view components to share data.
Additional resource
To add your resources such as images, JavaScript, and so on to a custom view component, see the developer community
post How to add your resources to a custom view component.
Section 508 compliance

All BMC built-in view components in BMC Helix Innovation Suite and all BMC built applications running on BMC Helix
Innovation Suite are Section 508 compliant and are accessible by the visually impaired.
Note
BMC certifies web clients that are using supported versions of browsers with the JAWS18 screen
reader.
BMC Helix Innovation Suite uses WAI-ARIA 1.1 specification to improve interoperability with assistive
technologies.
Related topics
Example of creating a custom view component (see page 835)
Creating custom view components for record editor (see page 853)
Creating custom actions (see page 860)
Naming conventions for AngularJS objects (see page 869)
Example of creating a custom view component

Consider a custom view component named Star Rating. The Star Rating view component allows the user to choose the
rating by a click on a star. The rating is stored in a record instance field after the click on a star.
Note

You must ensure that you follow naming conventions (namespacing) for all angular object names and all
HTML filenames in shared code. See Naming conventions for angular objects (see page 869).
To create Star Rating view component, perform the following steps:
1. Create basic configurations (see page 836).
2. Configure component property (see page 837).
3. Create design time view component (see page 839).
4. Create design manager and model (see page 840).
5. Validate model (see page 843).
6. Create Properties pane editor (see page ).
7. Enhance view component (see page 847).
8. Interact with other view components (see page 848).
Creating basic configurations
1. Define an angular module for the view component in the star-rating.module.js file.
Sample code:
angular.module('com.example.samplelibrary.view-components.star-rating', [
'com.bmc.arsys.rx.standardlib.view-component',
'com.bmc.arsys.rx.standardlib.record.definition'
]);
2. Create an angular directive that represents how the component is displayed in a view definition in the star-rating.
directive.js file.
Sample code:
angular.module('com.example.samplelibrary.view-components.star-rating')
.directive('comExampleSamplelibraryStarRating', function () {
return {
restrict: 'E',
template: '<h1>Star Rating Component</h1>',
scope: {
}
};
});
3. Register the view component in the star-rating.config.js file.

Sample code:
angular.module('com.example.samplelibrary.view-components.star-rating')
.config(function (rxViewComponentProvider) {
var starRatingDescriptor = {

name: 'Star Rating',

group: 'Sample Components',
icon: 'star',
type: 'com-example-samplelibrary-star-rating', // the name of runtime directive
bundleId: 'com.example.samplelibrary'
};
rxViewComponentProvider.registerComponent(starRatingDescriptor);
});
4. If you are creating the view component for a smart library, add the dependency of the view component module
in the main library module.
Sample code:
// com.example.samplelibrary.module.js
angular.module('com.example.samplelibrary', [
'com.example.samplelibrary.view-components.star-rating'
]);
If you are creating the view component for an application, add the dependency of the view component module in
the extension module of the application.
Sample code:
// com.example.myapplication-ext.module.js
angular.module('com.example.myapplication-ext', [
'com.example.myapplication.view-components.star-rating'
]);
After these basic steps are completed and the com.example.samplelibrary bundle is deployed, you can view the Star
Rating view component in the View designer.
Configuring component property

You can add the view component configuration properties during component registration.
The Star Rating view component requires the following properties:
Record Definition Name—record definition name
Record Instance ID—ID of the record instance in which the star rating will be saved

Field ID—ID of the field in which the star rating will be saved
Stars—number of stars to show
Sample code in star-rating.config.js file:
star-rating.config.js
angular.module('com.example.samplelibrary.view-components.star-rating').config(function
(rxViewComponentProvider) {
name: 'Star Rating',
group: 'Sample Components',
icon: 'star',
type: 'com-example-samplelibrary-star-rating', // the name of runtime directive
// define component properties

propertiesByName: [
{
name: 'recordDefinitionName',
isConfig: true,
isRequired: true
},
{
name: 'recordInstanceId',
isConfig: true,
isRequired: true
},
{
name: 'fieldId',
isConfig: true,
isRequired: true
},
{
name: 'stars',
isConfig: true,
isRequired: true
}
]
};
});
All properties marked with isConfig flag are available in the View designer Properties pane.
All properties marked with isRequired flag are validated.

Creating design time view component

Design time view component is a regular angular directive that represents the view component on the View designer
canvas.
1. Create design time directive in star-rating-design.directive.js file.

Sample code:
star-rating-design.directive.js
angular.module('com.example.samplelibrary.view-components.star-rating').directive('comExampleSamplelibr
aryStarRatingDesign', function () {
return {
restrict: 'E',
templateUrl: 'scripts/com.example.samplelibrary/view-components/star-rating/com-example-
samplelibrary-star-rating-design.directive.html',
scope: {
},

// view component configuration will be stored in $scope.rxConfiguration.model
updateStars();
// subscribe to rxData property change

$scope.rxConfiguration.model.on('change:rxData', updateStars);
function updateStars() {
var stars = Number($scope.rxConfiguration.model.prop('rxData/stars'));
}
$scope.getStars = function (stars) {

return new Array(stars);
};
}
};
});
Add the following code in com-example-samplelibrary-star-rating-design.directive.html file:
com-example-samplelibrary-star-rating-design.directive.html
<span ng-repeat="star in getStars(stars) track by $index" class="d-icon-star"></span>
2.
2. Register the design time view component.
// ...
designType: 'com-example-samplelibrary-star-rating-design' // register design directive

};
});
After the above steps are completed and the bundle is redeployed, the Star Rating view component is displayed
in the View designer canvas as shown in the following image:
Creating design manager and model

You can create a model and design manager for the view component, if it requires more complex configurations in
design time.
1. Create model for the view component in star-rating-model.service.js file. The model should extend the
rxViewComponentModel. The following code illustrates a simple configuration:
star-rating-model.service.js
angular.module('com.example.samplelibrary.view-components.star-rating').factory('comExampleSamplelibrar
yStarRatingModel', function (rxViewComponentModel) {
return rxViewComponentModel.extend({});
});
The following code illustrates how to load a record definition every time changes the record definition name
configuration property.
yStarRatingModel', function (rxViewComponentModel, rxRecordDefinitionResource) { return
rxViewComponentModel.extend({
initialize: function () {
// launch parent initialize method
rxViewComponentModel.prototype.initialize.apply(this, arguments);
// add listener for rxData

this.listenTo(this, 'change:rxData', this._onChangeRxData);

this._initRecordDefinition();
},
_initRecordDefinition: function () {
if (this.prop('rxData/recordDefinitionName')) {
var me = this;
// load Record Definition

rxRecordDefinitionResource.get(this.prop('rxData/recordDefinitionName')).then(function
(recordDefinition) {
me.recordDefinition = recordDefinition;
}).catch(function () {
me.recordDefinition = null;
});
} else {
this.recordDefinition = null;
}
},
_onChangeRxData: function (model, rxData, changedProperty) {

if (changedProperty.propertyPath === 'rxData/recordDefinitionName') {
this._initRecordDefinition();
}
}
});
});
2. Create custom design manager in star-rating-design.service.js file. The following code illustrates a simple
configuration for design manager:
star-rating-design.service.js
yStarRatingDesign', function () {
return {};
});
The following code illustrates design manager that implements the getModel method:
yStarRatingDesign', function (comExampleSamplelibraryStarRatingModel, rxGUID, RX_DEFINITION_PICKER) {
function getRxConfig(componentDefinition) {
return {
id: componentDefinition.guid || rxGUID.generate(),
type: componentDefinition.type,
rxData: getRxData(componentDefinition),
rxInspector: getRxInspector()
};
}
function getRxData(componentDefinition) {
return {
recordDefinitionName: componentDefinition.propertiesByName.recordDefinitionName,
recordInstanceId: componentDefinition.propertiesByName.recordInstanceId,
fieldId: componentDefinition.propertiesByName.fieldId,
stars: componentDefinition.propertiesByName.stars || 5
};
}
function getRxInspector() {
return {

inputs: {
rxData: {
recordDefinitionName: {
label: 'Record Definition Name',
type: 'rx-inspector-definition-picker', // special editor for selecting
definitions
definitionType: RX_DEFINITION_PICKER.definitionTypes.regularRecord.type, //
define which definition user can select
group: 'general',
index: 1
},
recordInstanceId: {
label: 'Record Instance ID',
type: 'rx-inspector-expression-node-field',
group: 'general',
index: 2
},
fieldId: {
label: 'Field ID',
group: 'general',
index: 3
},
stars: {
label: 'Stars',
group: 'general',
index: 4
}
}
},
groups: {
general: {
label: 'General',
index: 1
}
}
};
}
return {
// should return a model instance
return new comExampleSamplelibraryStarRatingModel(getRxConfig(componentDefinition));
}
};
});
3. Register the design manager service in star-rating.config.js file.
// ...
designManagerService: 'comExampleSamplelibraryStarRatingDesign'
};
});

After this step is complete and the bundle is redeployed, you can view that the record definition name field is
displayed as a dropdown.
Validating model
The model is responsible for the view component configuration property value validation in design time. The following
code shows how to add the validation to the Stars configuration property:
angular.module('com.example.samplelibrary.view-components.star-rating').factory('comExampleSamplelibraryStarRa
tingModel', function (rxViewComponentModel, rxRecordDefinitionResource) {
return rxViewComponentModel.extend({
// ...
validate: function () {
var me = this;
// execute default validation method

return rxViewComponentModel.prototype.validate.apply(this, arguments).then(function
(validationIssues) {
// check that the number of stars is at least 5
if (me.prop('rxData/stars') < 5) {
validationIssues.push({
elementId: me.get('guid'),
elementName: 'Star Rating',
propertyName: 'stars',
type: 'error',
message: 'The number of stars should be greater or equal to 5.'
});
}
return validationIssues;
});
}
});
});
After you redeploy the bundle, you can view a validation error message if the number of stars is less than 5.

Creating Properties pane editor

Create an editor that helps a user to select a field in which the rating is stored. In this example, let us use a record
definition Record with rating that has an integer Rating field.
The Properties pane editor is a regular angular directive that should implement the UI where the user can edit the model
property. The directive has the following properties configured on its scope:
$scope.cell—model that stores all component properties
$scope.path—defines the path to the property whose value are edited
$scope.options—all options which are defined in the rxInspector configuration for the field
For example:
{
label: 'Field Id',
group: 'general',
index: 3
}
The following code illustrates a simple Properties pane editor implementation:
angular.module('com.example.samplelibrary.view-components.star-rating').directive('comExampleSamplelibraryInsp
ectorStarRatingFieldSelect', function () {
return {

restrict: 'E',
templateUrl: 'scripts/com.example.samplelibrary/view-components/star-rating/editor/com-example-
samplelibrary-inspector-star-rating-field-select.directive.html',

// $scope.path - e.g. 'rxData/fieldId'
// get current model value

var currentModelValue = $scope.cell.get($scope.path);
// set new value

$scope.cell.get($scope.path, 536870913);
}
};
});
The following code illustrates the full implementation for the Properties pane editor:
inspector-star-rating-fied-select.directive.js
angular.module('com.example.samplelibrary.view-components.star-rating').directive('comExampleSamplelibraryInsp
ectorStarRatingFieldSelect', function (RX_RECORD_DEFINITION) {
return {
restrict: 'E',
templateUrl: 'scripts/com.example.samplelibrary/view-components/star-rating/editor/com-example-
samplelibrary-inspector-star-rating-field-select.directive.html',

$scope.data = {
fields: [],
selectedField: null
};
init();
function init() {
initializeFields();
// reinitialize fields when user change Record Definition

$scope.$watch('cell.recordDefinition', initializeFields);
$scope.$watch('data.selectedField', function (newValue) {

if (newValue) {
// set field id to the model
$scope.cell.prop($scope.path, $scope.data.selectedField.id);
}
}, true);
}
function initializeFields() {
if ($scope.cell.recordDefinition) {
$scope.data.fields = getFields();
$scope.data.selectedField = _.find($scope.data.fields, {
id: Number($scope.cell.prop($scope.path))
});
} else {
$scope.data.fields = [];
$scope.data.selectedField = null;
}
}
// get all integer fields from the selected Record Definition

function getFields() {
return _($scope.cell.recordDefinition.fieldDefinitions)

.filter({
resourceType: RX_RECORD_DEFINITION.dataTypes.integer.resourceType
})
.map(function (fieldDefinition) {
return {
id: fieldDefinition.id,
name: fieldDefinition.name
};
})
.value();
}
}
};
});
The following code is a template for the Properties pane editor directive:
com-example-samplelibrary-inspector-star-rating-field-select.directive.html
<label ng-class="options.attrs.label.class">
<rx-tooltip tooltip="options.tooltip"></rx-tooltip>
{{options.label}}:
</label>
<div ng-if="data.fields.length">
<select class="select" ng-options="field.name for field in data.fields track by field.id"
ng-model="data.selectedField"></select>
</div>
<div ng-if="!data.fields.length">
There are no fields for select
</div>
To use the created inspector editor, set the type property to the name of the directive in the inspector configuration:
angular.module('com.example.samplelibrary.view-components.star-rating').factory('comExampleSamplelibraryStarRa
tingDesign', function (comExampleSamplelibraryStarRatingModel,
rxGUID,
RX_DEFINITION_PICKER) {
// ...
function getRxInspector() {
return {
inputs: {
rxData: {
// ...
fieldId: {
label: 'Field Id',
type: 'com-example-samplelibrary-inspector-star-rating-field-select', // set our
directive as editor
group: 'general',
index: 3
},
stars: {
label: 'Stars',
type: 'number', // set number as editor for stars
min: 5, // minimal value
group: 'general',
index: 4
}

}
}
};
}
return {
return new comExampleSamplelibraryStarRatingModel(getRxConfig(componentDefinition));
}
};
});
After you create the editor and redeploy the bundle, you can view that the Field ID property is displayed in the Properties
pane as a dropdown.
Enhancing view component

To retrieve a record instance, the rxRecordInstanceResource service is used.
angular.module('com.example.samplelibrary.view-components.star-rating', [
'com.bmc.arsys.rx.standardlib.view-component',
'com.bmc.arsys.rx.standardlib.record.definition',
'com.bmc.arsys.rx.standardlib.record.instance' // contains rxRecordInstanceResource resource
]);
The runtime directive gets access to configuration properties using the $scope.rxConfiguration.propertiesByName
method.
star-rating.directive.js
angular.module('com.example.samplelibrary.view-components.star-rating').directive('comExampleSamplelibraryStar
Rating', function (rxRecordInstanceResource) {
return {
restrict: 'E',
templateUrl: 'scripts/com.example.samplelibrary/view-components/star-rating/com-example-samplelibrary-
star-rating.directive.html',
scope: {
},
link: function ($scope, $element) {

var config = $scope.rxConfiguration.propertiesByName;

var recordInstanceResource = rxRecordInstanceResource.withName(config.recordDefinitionName);

var recordInstance = null;
$scope.stars = [];
$scope.onStarSelectHandler = function (event) {

var selectedIndex = _.indexOf($element.find('span'), event.target);
if (selectedIndex !== -1) {

$scope.stars = buildStarsConfiguration(selectedIndex);
// update rating value

recordInstance.setValue(config.fieldId, selectedIndex);
recordInstance.save();
}
};
function initialize() {
recordInstanceResource.get(config.recordInstanceId).then(function (_recordInstance) {
recordInstance = _recordInstance;
$scope.stars = buildStarsConfiguration(recordInstance.fieldInstances[config.fieldId].
value || 0);
$scope.stars = [];
});
}
function buildStarsConfiguration(starCount) {
var stars = [];
for (var i = 1; i <= config.stars; i++) {

stars[i] = {
icon: i <= starCount ? 'd-icon-star' : 'd-icon-star_o'
};
}
return stars;
}
initialize();
}
};
});
Sample directive template:
com-example-samplelibrary-star-rating.directive.html
<div ng-click="onStarSelectHandler($event)">
<span ng-repeat="star in stars track by $index" class="{{star.icon}}"></span>
</div>
After you redeploy the bundle, the Start Rating view component is displayed as shown in the following image:
Interacting with other view components

View components can exchange data using expressions.

Receiving data from other components

After you configure a constant value for the Record Instance ID configuration property at design time, you can also
update the Star Rating view component to use a dynamic value for the Record Instance ID configuration property. The
following example shows how to retrive value from a record selected in the record grid view component.
1. Mark the view component properties that can accept expressions with the enableExpressionEvaluation flag in the
star-rating.config.js file.
// ...
propertiesByName: [
// ...
{
name: 'recordInstanceId',
isRequired: true,
isConfig: true,
enableExpressionEvaluation: true // the property will be automatically evaluated at
runtime and passed to the runtime directive
}
]
};
});
The property value is evaluated automatically during runtime and the actual value is passed to the view
component runtime directive.
2. Add a record grid view component to the canvas and bind it to the same record definition as the Star Rating view
component and ensure that you set row selection to Single row.
3. For recordInstanceId property, select Record Grid > Selected Rows > First Selected Row > ID expression.

3.
4. Implement a watcher on the recordInstanceId property in the star-rating.directive.js.

When user selects a record instance in the grid, the Star Rating view component receives the ID of the selected
record instance. To react to the record instance ID changes, you must implement a watcher.
Sample code:
aryStarRating', function (rxRecordInstanceResource) {
return {
restrict: 'E',
samplelibrary-star-rating.directive.html',
scope: {
},

var config = $scope.rxConfiguration.propertiesByName;
var recordResource = rxRecordInstanceResource.withName(config.recordDefinitionName);
var recordInstance = null;
$scope.stars = [];


recordInstance.fieldInstances[config.fieldId].value = selectedIndex;
}
};
initialize();
function initialize() {
// reinitialize configuration each time when recordInstanceId is changed
$scope.$watch('rxConfiguration.propertiesByName.recordInstanceId', initializeStars);
}
function initializeStars() {
if (config.recordInstanceId) {

recordResource.get(config.recordInstanceId).then(function (recordInstanceResource)
{
recordInstance = recordInstanceResource;
$scope.stars = buildStarsConfiguration(recordInstanceResource.fieldInstances
[config.fieldId].value || 0);
$scope.stars = [];
});
} else {
$scope.stars = [];
}
}
function buildStarsConfiguration(starCount) {
var stars = [];
for (var i = 1; i <= config.stars; i++) {

stars[i] = {
icon: i <= starCount ? 'd-icon-star' : 'd-icon-star_o'
};
}
return stars;
}
}
};
});
After you redeploy the bundle, the Star Rating view component reflects the rating from the record instance selected in
the record grid.
Sharing data with the other view components

Consider that the other view components need the current rating value in the Star Rating view component. In this case,
the Star Rating view component has to expose the its properties:
1. During component registration, mark property as isProperty :
// ...
propertiesByName: [
{
name: 'stars',
isConfig: true,

isProperty: true, // property will be available for building expressions

defaultValue: 5
}
]
};
});
This makes the Star Rating property available in the data dictionary at design time. It can be used in expressions
for other view component properties.
2. Notify the view about the changes to this property. When the stars property changes, the view component
triggers a propertyChanged event. When the view catches this event, it evaluates all expressions that use the stars
property and passes the updated value to other view components.
Sample code in star-rating.directive.js file:
aryStarRating', function (rxRecordInstanceResource, rxViewComponentEventManager) {
return {
restrict: 'E',
samplelibrary-star-rating.directive.html',
scope: {
},

// ...
// create event manager

var eventManager = rxViewComponentEventManager.getInstance($scope);
$scope.stars = [];


// trigger the change property event

eventManager.propertyChanged({

property: 'stars', // name of the property that changed

newValue: selectedIndex
});
recordInstance.setValue(config.fieldId, selectedIndex);
}
};
}
};
});
Related topics
Creating custom view components (see page 826)
Naming conventions for angular objects (see page 869)
Creating custom view components for record editor

Record editor is a view component that is used to create or edit record instances. Record editor may contain field
components (for example, select group, dropdown, attachment) which are available on the View designer palette.
Record editor field component is a view component that can be embedded in a record editor.
To create a record editor field component, perform the following steps:
1. Create a directive for record editor field component (see page 853).
2. Create design time directive (see page 855).
3. Create a design manager for view component (see page 855).
4. Create model for record editor field component (see page 856).
5. Register the record editor field component (see page 859).
Creating record editor field component directive

The default controller, RxRecordEditorFieldComponentController, implements the default logic required for a record
editor field component. To run the default logic you must use the controller init method and configure
RxRecordEditorFieldComponentController injectable $scope and $element locals. The
RxRecordEditorFieldComponentController#init performs the following tasks:
Updates fieldDefinition and fieldInstance properties on the $scope object
Updates fieldInstance.value based on propertiesByName.value expression
Sets component API

Example of directive for Regular Expression Text component:
angular.module('com.example.samplelibrary.view-components.regular-expression-text')
.directive('comExampleSamplelibraryRegularExpressionTextField', function ($controller) {
return {
restrict: 'E',
templateUrl: 'scripts/view-components/regular-expression-text-field/com-example-samplelibrary-
regular-expression-text-field.directive.html',
scope: {
},
require: '^form',
link: function ($scope, $element, attrs, formController) {

var fieldComponentCtrl = $controller('RxRecordEditorFieldComponentController', {
$scope: $scope,
$element: $element
});
fieldComponentCtrl.init();
$scope.form = formController;
}
};
});
Record editor can be displayed in two states, READ and EDIT. Every record editor field component should be correctly
rendered in both states.
The following code illustrates a directive template:
div ng-if="!rxConfiguration.propertiesByName.hidden"
on="rxConfiguration.propertiesByName.state"
ng-switch>
<div ng-switch-when="READ">
<div class="d-textfield">
<label class="d-textfield__label">
<span class="d-textfield__item">{{::fieldDefinition.name}}</span>
</label>
<p>{{fieldInstance.value}}</p>
</div>
</div>
<div ng-switch-when="EDIT">
<div class="d-textfield"
ng-class="{
'd-textfield_required': fieldDefinition.fieldOption == 'REQUIRED',
'd-textfield_invalid' : form[fieldDefinition.name].$dirty && form[fieldDefinition.
name].$invalid
}">
<label class="d-textfield__label">
<span class="d-textfield__item">{{rxConfiguration.propertiesByName.label}}</span>
<input type="email"
name="{{fieldDefinition.name}}"
ng-model="fieldInstance.value"
ng-disabled="rxConfiguration.propertiesByName.disabled"
maxlength="{{rxConfiguration.propertiesByName.maxLength}}"
class="d-textfield__input"
ng-pattern="rxConfiguration.propertiesByName.regularExpression"
ng-required="fieldDefinition.fieldOption == 'REQUIRED'">

</label>
<p class="d-error"
ng-if="form[fieldDefinition.name].$dirty && form[fieldDefinition.name].$invalid">
<span class="d-error__message">
Invalid Value
</span>
</p>
</div>
</div>
</div>
Creating design time directive

Design time directive represents how a view component is displayed on the canvas in the View designer and its usage. A
custom angular directive to use a field component in the View designer must have isolated scope. You can use the the
default RxRecordEditorFieldComponentDesignController controller. The directive gets componentDefinitionId and
model properties from rxConfiguration.
The following sample code illustrates a directive that uses the default RxRecordEditorFieldComponentDesignController
controller:
.directive('comExampleSamplelibraryRegularExpressionTextFieldDesign', function ($controller) {
return {
restrict: 'E',
templateUrl: 'scripts/view-components/regular-expression-text-field/com-example-samplelibrary-
regular-expression-text-field-design.directive.html',
scope: {
},
controller: function ($scope) {

$controller('RxRecordEditorFieldComponentDesignController', {$scope: $scope});
}
};
});
Creating design manager

Design manager is used to prepare model configurations and create the model instance for a record editor field
component. rxRecordEditorFieldComponentDefaultDesignManager is the default manager class for record editor field
component that defines the standard steps to create the model. You must create a instance of the default manager and
expose getModel method.
Sample code:
.factory('comExampleSamplelibraryRegularExpressionTextFieldDesignManager', [
'rxRecordEditorFieldComponentDefaultDesignManager',
function (rxRecordEditorFieldComponentDefaultDesignManager) {
// create manager instance
var designManager = new rxRecordEditorFieldComponentDefaultDesignManager();
return {
// expose getModel method
return designManager.getModel(componentDefinition);
}

};
});
If you need any customization, you can extend the default design manager using the following methods:
getRxInspector—returns configuration for inspector
getRxData—returns object with rxData configuration
getRxConfig—returns model configuration
getModel—returns model instance
Sample code:
.factory('comExampleSamplelibraryRegularExpressionTextFieldDesignManager', [
'rxRecordEditorFieldComponentDefaultDesignManager',
'comExampleSamplelibraryRegularExpressionTextFieldModel',
function (rxRecordEditorFieldComponentDefaultDesignManager,
RegularExpressionTextFieldModel) {
var RegularExpressionTextFieldDesignManager =
rxRecordEditorFieldComponentDefaultDesignManager.extend({
// rewriting getModel method
// RegularExpressionTextFieldModel - custom model
// still use default getRxConfig method for getting model configurations
return new RegularExpressionTextFieldModel(this.getRxConfig(componentDefinition));
}
});
var designManager = new RegularExpressionTextFieldDesignManager();
return {
return designManager.getModel(componentDefinition);
}
};
});
Creating model for record editor field component

rxRecordFieldDefinitionModel is the default model for building field components. You can extend the default model or
override the methods of the default model to create a custom model to add custom editors, user input validations, and
changes to JSON structure.
rxRecordFieldDefinitionModel methods
The record editor field component default model consists of the following methods:
Method Description Return value
reateListeners Creates handlers for model data and parent model value
changes
onFieldDefinitionChanged Called when changes to field ID changes and component {Promise} a promise that is resolved when default preparation
initialization finished
Parameters:
{Object} fieldDefinition (new field definition)

Method Description Return value
{(Object|undefined)} previousFieldDefinition (old field

definition)
getFieldNameOptions Gets a list of record editor fields supported by current field {Promise} a promise that is resolved with fieldNameOptions
model
getRecordDefinition Gets the record definition associated with the record editor {Object}
getRecordEditorId Gets the ID of the record editor view component {String}
getRecordEditorState Gets the current record editor state {('EDIT'|'CREATE')}
getRecordDefinitionName Gets the name of the record definition bound to the record {String}
editor
getCurrentFieldDefinition Gets the field definition for a selected Field ID {Promise} a promise is resolved with field definition
setInspector Refreshes the inspector
Parameters:
{Object} rxInspector
getRxInspector Gets the default field inspector configuration {Promise} a promise that is resolved with rxInspector
configuration
Examples of overriding rxRecordFieldDefinitionModel methods

The following sample code is an example of overriding rxRecordFieldDefinitionModel by
comExampleSamplelibraryRegularExpressionTextFieldModel:
.factory('comExampleSamplelibraryRegularExpressionTextFieldModel', [
'rxRecordEditorFieldComponentDesignModel',
function (rxRecordEditorFieldComponentDesignModel) {
return rxRecordFieldDefinitionModel.extend({
describeViewComponent: function () {},
getRxInspector: function () {},
validate: function () {}
});
}
]);
The following table provides examples of overriding rxRecordFieldDefinitionModel methods:
Method Description Sample code
getRxInspector This method is can be overridden to add a new editor to

the inspector that is used by the regularExpression
getRxInspector: function () {
property.
return
rxRecordEditorFieldComponentDesignModel.
prototype.getRxInspector.call(this)
.then(function (rxInspector) {
rxInspector.inputs.rxData.
regularExpression = {
label: 'Input Format',
type: 'com-example-
samplelibrary-inspector-input-with-dropdown',
group: 'general',
index: 3,
tooltip: 'It accepts regular
expression as value'

};
rxInspector.inputs.rxData.value.
index = 4;
rxInspector.inputs.rxData.
disabled.index = 5;
rxInspector.inputs.rxData.hidden.
index = 6;
return rxInspector;
});
}
describeViewComponent This method can be overridden to add a new property,

regualrExpression, to the view component model.
describeViewComponent: function () {
var descriptor =
rxRecordFieldDefinitionModel.prototype.
describeViewComponent.call(this);
descriptor.propertiesByName.
regularExpression = this.get('rxData').
regularExpression || '';
return descriptor;
},
validate This method can be overridden to add validation for the

regularExpression field.
validate: function () {
var me = this;
/**
* call validate method from
rxRecordFieldDefinitionModel to get default
validation issues for the field
*/
return rxRecordFieldDefinitionModel.
prototype.validate.call(this)
.then(function (validationIssues) {
validationIssues =
validationIssues || [];
/**
* Check if user input is valid
RegExp pattern
* reference http://stackoverflow.
com/a/17250859
*/
try {
// eslint-disable-line no-new
new RegExp(me.prop('rxData
/regularExpression'));
} catch (e) {
validationIssues.push({
elementId: me.get('id'),
elementName: 'Regular
Expression Text',
componentProperty: true,
propertyName: 'regularExpr
ession',

type: 'error',
message: 'Regular
Expression field should be a valid RegExp
pattern'
});
}
return validationIssues;
});
}
Registering a record editor field component

Record editor field component has the following additional properties as compared to a generic view component:
canBeEmbeddedInRecordEditor—must set to true to embed in record editor
supportedFieldResourceTypes—an array of field data types from RX_RECORD_DEFINITION.dataTypes

enumeration
If required, you can modify the default properties. You can get the default properties by using the
rxRecordEditorFieldComponentConfiguratorProvider#getFieldComponentDescriptorDefaults method.
The following is list of properties that are returned by getFieldComponentDescriptorDefaults method:
recordDefinition Defines expression pointing to the record definition.
This is a mandatory field for record editor field component.
recordInstance Defines expression pointing to the record instance
fieldId Defines field ID bound to the component
disabled Defines an expression that determines whether a component should be disabled
hidden Defines an expression that determines whether a component should be hidden
label Defines a localizable label
value Defines an expression that defines the field value
The following sample code illustrates how to register a record editor field component:
name: 'Regular Expression Text',
canBeEmbeddedInRecordEditor: true,
supportedFieldResourceTypes: [RX_RECORD_DEFINITION.dataTypes.character.resourceType],
...
propertiesByName: rxRecordEditorFieldComponentConfiguratorProvider
.getFieldComponentDescriptorDefaults()
.propertiesByName
.concat([
{
name: 'regularExpression',
type: 'string',
isConfig: true
}
])

});
Section 508 compliance

All BMC built-in view components in BMC Helix Innovation Suite and all BMC built applications running on BMC Helix
Innovation Suite are Section 508 compliant and are accessible by the visually impaired.
Note
BMC certifies web clients that are using supported versions of browsers with the JAWS18 screen
reader.
BMC Helix Innovation Suite uses WAI-ARIA 1.1 specification to improve interoperability with assistive
technologies.
Related topics
Creating custom actions

Custom action is a service (AngularJS service) that allows you to map an action to the UI elements in the View designer.
You can create a custom action (JavaScript action) that can be mapped to an action button or a cell in a record grid in a
view definition.
For example, if you want to display an alert box (that displays an alert message) on the click of an action button, you can
create an action for the alert box (via code) and then map the action to an action button in the View designer.
Note
You must ensure that you follow naming conventions (namespacing) for all angular object names and all
HTML filenames in shared code. See Naming conventions for angular objects (see page 869).

To create a custom action
1. Create a service that implements the functionality for the action.

The functionality of the action is define in the execute method. This method accepts a list of parameters
specified in the action descriptor. The name of the service should match the name of the action specified in the
action descriptor. To support chaining of actions, an action needs to return a promise and resolve it when its
completed. The following sample code illustrates Open view action:
angular.module('com.bmc.arsys.rx.standardlib.actions.open-view').service('rxOpenViewAction', function
(rxLog) {
execute: function (viewDefinitionName, viewParams, presentation) {
return getViewDefinition(viewDefinitionName).then(function (data) {
var stateParams = _.map(data.inputParams, function (param) {
return viewParams[param.name];
});
switch (presentation.type) {
case RX_OPEN_VIEW.type.fullWidth: {
openFullWidth(viewDefinitionName, presentation, stateParams);
return $q.reject();
}
case RX_OPEN_VIEW.type.centeredModal: {
return openModal('rx-runtime-view-dialog modal__', viewDefinitionName,
presentation, stateParams, RX_OPEN_VIEW.template.modal);
}
case RX_OPEN_VIEW.type.dockedRightModal: {
return openModal('rx-runtime-view-dialog d-action-blade action-blade__',
viewDefinitionName, presentation, stateParams, RX_OPEN_VIEW.template.blade);
}
case RX_OPEN_VIEW.type.dockedLeftModal: {
return openModal('rx-runtime-view-dialog d-action-blade is-left action-blade__',
viewDefinitionName, presentation, stateParams, RX_OPEN_VIEW.template.blade);
}
default: {
openFullWidth(viewDefinitionName, presentation, stateParams);
return $q.reject();
}
}
});
}
});
You can use rxAction service to run an action. The following sample code illustrates usage of Open View action.
rxAction.executeAction('rxOpenViewAction')({
propertiesByName: {
viewDefinitionName: 'com.example.taskmanager:AnyView',
presentation: {
title: 'Edit Record',
modalSize: RX_OPEN_VIEW.modalSize.large,
type: RX_OPEN_VIEW.type.dockedRightModal
}
}
});
2. Register the action using rxActionProvider.

2.
To make the action available in the View designer (Add/Remove Actions dialog), you must register with
rxActionProvider. To register an action, must use rxActionProvider#registerAction class. This class consists of the
following properties:
name Name of the action. This is a required property. For example, rxSaveAction, rxDeleteRecordsAction.
bundleId Name of the bundle. This is a required property.
label User friendly action name that is displayed in the View designer
hidden A boolean flag that determines whether an action is hidden in the View designer action list
parameters An array of action parameters.

This property of an action descriptor is used to list all parameters that are passed to the execute method. Every parameter is saved in
action component definition.
The parameter descriptor has the following options:
name—Parameter name
label—User friendly parameter name displayed in the action list.
enableExpressionEvaluation—Boolean flag used to enable expression evaluation for the parameter value. The default value is
false.
editor—name of a UI control used to set parameter value (implemented as angular directive). The default value is rx-
expression-field for a parameter with enableExpressionEvaluation set to true and rx-editor-input for others.
isRequired—Boolean flag to enable auto validation for empty values. The default value is false.
defaultValue—Default value for a parameter.
You can specify additional properties in parameter descriptor.
The following sample code illustrates how to register and action using rxActionProvider:
rxActionProvider.registerAction({
name: 'rxOpenViewAction',
label: 'Open View',
bundleId: RX.bundleId,
parameters: [
{
name: 'viewDefinitionName',
label: 'View',
editor: 'rx-view-definition-selector',
isRequired: true,
definitionType: RX_DEFINITION_PICKER.definitionTypes.view.type
},
{
name: 'viewParams',
editor: 'rx-view-definition-params',
},
{
name: 'presentation',
editor: 'rx-view-presentation-params'
}
]
});

getOutputParams function
In the View designer, in the Add/Remove Actions, you can add, remove, rearrange and configure actions associated with a
actionable view component. When you configure actions you can set the execution order of actions by placing them in a
sequence. Every action configuration section contain editors that allow you to set the action parameters. Each action can
expose data that is available to the following action in the action chain. These exposed properties are referred as action
output parameters. If an action has output parameters, the service that defines the action should consist of
getOuputParameters method and execute method. The getOuputParameters function accepts the configured action
data and returns an array of objects, where each object has name property that specifies a parameter name.
Sample code:
module.service('rxOpenViewAction', function () {
return {
execute: function() {},
getOutputParams: function (actionConfig) {
// returns the list of output parameters exposed by the selected view
if (actionConfig.viewDefinitionName) {
return getViewDefinition(actionConfig.viewDefinitionName).then(function (viewDefinition) {
return _.map(viewDefinition.outputParams, function (outputParam) {
return {
name: outputParam.name
};
});
});
}
}
}
}
Storing actions
An action is stored in the view definition in the componentDefinitions property as a view component with rx-action type.
Action input parameters are stored in the propertiesByName property. Actionable view components must be defined as
containers in order to keep the associated actions as their child view components.
The following sample code illustrates how to define an action as a service
"resourceType": "com.bmc.arsys.rx.services.view.domain.ContainerViewComponentDefinition",
"id": "93ba11a4-8e58-470d-95ac-23a8aa0ddcb7",
"type": "rx-action-button",
"componentDefinitions": [
{
"resourceType": "com.bmc.arsys.rx.services.view.domain.ViewComponentDefinition",
"id": "2a3d227d-2643-4b3b-9a29-a5ea72243988",
"type": "rx-action",
"propertiesByName": {
"index": 0,
"name": "rxOpenViewAction",
"viewDefinitionName": "com.example.taskmanager:Edit Task",
"viewParams.taskId": "${view.api}",
"presentation.type": "fullWidth",
"presentation.launchBehavior": "newWindow"
}
}

Example to create an alert box action

Let us consider you want to display an alert box (that displays an alert message) on the click of an action button. To
implement this, you can create an action for the alert box (via code) and then map the action to an action button in the
View designer.
Creating action to display an alert box

In Eclipse, open the library project, navigate to projects\<library>\bundle\src\main\webapp\scripts\actions, and perform
the following steps:
1. Declare the AngularJS module for the action.

For example, declare show-alert AngularJS module in show-alert.module.js.
(function () {
'use strict';
angular.module('com.example.samplelibrary.actions.show-alert', [
'com.bmc.arsys.rx.standardlib.action'
]);
})();
2. Define service for the action.

For example, define an AngularJS service which invokes alert() from the execute() method in show-alert.service.
js.
(function () {
'use strict';
angular.module('com.example.samplelibrary.actions.show-alert')
.service('comExampleSamplelibraryShowAlertAction', function () {
this.execute = function (message) {
alert(message);
};
});
})();
3. Register the action and its parameter with BMC Helix Innovation Studio.
For example, register the action in show-alert.config.js.
(function () {
'use strict';
angular.module('com.example.samplelibrary.actions.show-alert').config(function (rxActionProvider) {
rxActionProvider.registerAction({
name: 'comExampleSamplelibraryShowAlertAction',
label: 'Show Alert',
parameters: [
{
name: 'message',
label: 'Alert Message',
}
]
});
});

})();
If you are creating actions in an application bundle, you must ensure that the path to the JavaScript files that
implements the action is referenced in bundle.conf.json.
For example,
"ext": {
"scripts": [
...
"scripts/actions/**/*.module",
"scripts/actions/**/*.config",
"scripts/actions/**/*.service",
...
],
4. Add a dependency on the action's module to the main library module in com.example.samplelibrary.module.js, or
to the application's extension module (for example, com.example.myapp-ext.module.js), if you are adding a
custom action to an application bundle.
Sample code:
angular.module('com.example.samplelibrary', [
// Existing View components (not shown here)
// Actions
'com.example.myapp.actions.show-alert'
]);
5. Build and deploy the project.

Sample code:
projects\samplelibrary> mvn clean install -Pexport -Pdeploy
Mapping the action code to an action button in a view definition
1. Log in to BMC Helix Innovation Studio, and navigate to the application for which you have created the action.
2. Navigate to Views tab and create a view definition.
3. Enter the required details for the view definition.
4. Add an action button in the view definition.
a. Enter the required details for the action button.
b. Select the Action button and in the Actions section, click Add/Remove Actions.

5. In the Available Actions list, select the action that you create (Show Alert) using the button:
6. Click action parameter Alert Message to define the message you want to display.
7.
7. Provide a message parameter, such as "My Alert really works!" and click OK.
8. Click Save to save the actions.
10. To test the action, preview the view definition.

On the preview page, click Show Message. The alert box with your message is displayed.
Related topics
Examples of AngularJS services

The following code snippets are examples of using AngularJS services. You can use these services to create a new record
instance, get record instance data, update record instance data, get configuration data, and get user data.

Get data page from record
var queryParams = {
propertySelection: "179,7", // ids of fields to get
queryExpression: "'7'!= 3" //not rejected
};
var foo = rxRecordInstanceDataPageResource.withName('<package>:<recordname>');
foo.get(1000,0,queryParams).then()
Get user data
rxCurrentUser.get()
Get configuration data
AdminSettingResource.getComponentSettingData('test').then(function(data) {
$scope.mode=data.values[0].settingValue;
});
Create a new record instance
var objectRecord = rxRecordInstanceResource.withName('de.materna.tf.TestTF:Object');

var createRecord = function () {
objectRecord.getNew().then(function (record) {
var fields = record.fieldInstances;
fields[536870917].value = 0;
fields[8].value = 'test description';
return objectRecord.post(record);
});
};
Get a record

objectRecord.get('IDxzy').then(
function(record) {
console.log(record.getValue(8));
}
);
Update a record

objectRecord.get('IDxzy').then(
function(record) {
record.setValue(8, 'new description');
record.put();
}
);
Related topics

Naming conventions for angular objects

Namespacing helps you to organize the objects of your Digital Service application so that they can be identified uniquely
when shared and collisions with other objects or variables in the global namespace are avoided.
To ensure global uniqueness of angular object names in the shared JavaScript code of your application, you must ensure
that you follow the following naming conventions:
All angular object names in shared code (services, factories, providers, controllers, directives, constants, filters)
must be prefixed with bundle ID and converted to camelCase (for example,
comExampleTaskmanagerTmsServiceOne).
Following sample code shows how to apply namespacing for angular objects:
/**
* The code BEFORE applying the namespacing changes
*/
angular.module('com.example.taskmanager.services')
.service('tmsServiceOne', function (tmsServiceTwo) {});
.service('tmsServiceTwo', function () {});
angular.module('com.example.taskmanager.filters')
.filter('tmsFilter', function (...) {});
angular.module('com.example.taskmanager.view-components')
.directive('tmsViewComponent', function (...) {});
/**
* The code AFTER applying the namespacing changes
*/
// NOTE: DI annotations can be added explicitly as shown below in order to keep the short names for
the function parameters
.service('comExampleTaskmanagerTmsServiceOne', ['comExampleTaskmanagerTmsServiceTwo', function
(tmsServiceTwo) {}]);
.service('comExampleTaskmanagerTmsServiceTwo', function () {});
angular.module('com.example.taskmanager.filters')
.filter('comExampleTaskmanagerTmsFilter', function (...) {});
.directive('comExampleTaskmanagerTmsViewComponent', function (...) {});

All HTML filenames in shared code (for example, view and directive templates) must be prefixed with the bundle
ID.
Following sample code shows how to apply namespacing for HTML files:
.directive('comExampleTaskmanagerTmsViewComponent', function () {
return {
templateUrl: 'scripts/view-components/com-example-taskmanager-tms-view-component.directive.
html',
...
};
});
Related topics
Creating a custom interface with REST

You can use REST APIs for a client to communicate with your custom bundle deployed in BMC Helix Innovation Suite
server. The REST API uses the base URL for the web service, such as https://<host>:<port>/api/
Each API is called by issuing a standard HTTP request method: POST, GET, PUT, or DELETE (more commonly known as
the CRUD operations: Create, Read, Update, and Delete).
The client creates new resources by issuing POST requests. The details of an individual resource are retrieved using a
GET request. The client issues PUT requests to modify a resource object. When a resource is no longer needed, the
client issues a DELETE request to remove the resource.
Communicating with BMC Helix Innovation Suite server by using REST API
You can use REST APIs for clients to communicate with BMC Helix Innovation Suite server. The following table lists the
APIs that can be used for login and records:
API type Description Action
User and Authenticate Authenticate User POST
Get User GET
Logout User POST
Records Create record definition POST
Get Record Definition GET
Get Record Definition Data Page GET
Get Record New Record Instance GET
Create Record Instance POST
Get Record Instance Data Page GET

API type Description Action
Delete Record Definition DELETE
For more information on REST APIs, see API documentation (see page 1003).
For example:
You can define a service named lxDishDataPageResource, which connects the Restful API Get Record Definition Data
Page.
(function () {
'use strict';
angular.module('lunch-order.home').factory('lunchOrderLxDishDataPageResource', function
(rxRecordInstanceDataPageResource, DISHES) {
return rxRecordInstanceDataPageResource.withName(DISHES.definitionName);
});
})();
To get the data, use the following code:
lxDishDataPageResource.get().then(function (dataPage) {
$scope.dishes = _.map(dataPage.data, function (dish) {
return {
dish: dish[DISHES.fields.dish],
description: dish[DISHES.fields.description],
price: dish[DISHES.fields.price],
quantity: 0
};
});
});
Sample REST API

The following sample code illustrates how to use a REST API in your Java code:
The class WorkOrderCostResource implements rx.service.common.RestfulResource. It is annotated with @Path that

describes the URL prefix @Path(“example/workordercost”). It contains a get() method annotated with HTTP verb
@GET and an authorization directive.
package
com.example.resource;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import
javax.ws.rs.PathParam;
import com.bmc.arsys.rx.services.bundle.BundleService;
import com.bmc.arsys.rx.services.common.RestfulResource;
import com.bmc.arsys.rx.services.common.annotation.AccessControlledMethod;
import com.bmc.arsys.rx.services.common.annotation.AccessControlledMethod.AuthorizationLevel;
import com.bmc.arsys.rx.services.common.annotation.RxDefinitionTransactional;
import com.example.service.WorkOrderService;
/**
* The Class WorkOrderCost
*/
@Path("example/workordercost")
public class WorkOrderCostResource implements RestfulResource {

private WorkOrderService workOrderService = null;

/**
* Gets the cost associated with a work order.
*
* @return the cost.
*/
@GET
@Path("/{workorderid}")
@RxDefinitionTransactional(readOnly = true)
@AccessControlledMethod(authorization = AuthorizationLevel.ValidUser)
public String get(@PathParam("workorderid") String workOrderId) {
StringBuilder response = new StringBuilder();
Integer cost = getWorkOrderService().getCost(workOrderId);
response.append("{workorder:\"");
response.append(workOrderId);
response.append("\", cost:\"");
response.append(cost);
response.append("\"}");
return response.toString();
}
private WorkOrderService getWorkOrderService() {

if (workOrderService == null) {
BundleService bundleService = ServiceLocator.getBundleService();
workOrderService = (WorkOrderService)
bundleService.getService("com.example.service.WorkOrderService");
}
return workOrderService;
}
}
To test this, you can use a custom client, a generic REST client such as POSTMAN or, since this is a GET operation, you
can use the browser URL directly (as long as the browser is logged in to an active session). The URL syntax is:
https://<host>:<port>/api/bundle-id/url-path (followed by any URL parameters).
For the above sample code, the following image shows how to test it in POSTMAN:
Related topics
API documentation (see page 1003)

Creating a DataPageQuery REST interface

DataPageQuery is a standard resource that allows your custom Java classes to return a set of paginated data (syntax
supports the notion of page size and start index for returning data in chunks to the client) to a client without defining
special parameters for a GET syntax. DataPageQuery class (com.bmc.arsys.rx.services.common.DataPageQuery)
represents a generic query that is executed via DataPageResource on @Get call. You can extend this class and overload
execute().
DataPageQuery sample code

The following code snippet illustrates sample DataPageQuery code format:
public
abstract class DataPageQuery implements Registerable {
/** The data page query parameters. */

private final DataPageQueryParameters dataPageQueryParameters;
…
/**
* Execute the logic of DataPageQuery.
* @return the data page
*/
public abstract
DataPage execute();
…
}
Creating DataPageQuery
Let us consider that there is some data source that is not available via the record service (data is not represented by a
record definition). You can create a way to perform a query for network information in the form of Node data that looks
as follows in JSON:
{
"count": 6,
"ip": "14.233.555.33",
"status": "Loading",
"model": "C-245Z",
"manufacturer": "C-245Z"
}
You can retrieve such data using a REST call. To retrieve data, implement a class that extends the framework class com.
bmc.arsys.rx.services.common.DataPageQuery. The framework class implements the execute() method which returns
an object called DataPage.
The following code snippet represents a sample DataPageQuery class:
import com.bmc.arsys.rx.services.common.DataPageQuery;
import com.bmc.arsys.rx.services.common.DataPageQueryParameters;
import com.bmc.arsys.rx.services.common.QueryPredicate;
public class NetworkDataPageQuery extends DataPageQuery {

public class Node {

// Define the data members to represent a network node
}
@Override
public DataPage execute() {
List<Node> = getNodeData(); // Pseudo-code to represent loading or creation of Node data.
// Process the pagesize and startindex parameters to isolate the correct

// chunk of data in a DataPage object.
int start = getDataPageQueryParameters().getStartIndex();
if (start >= list.size()) {
return new DataPage(0, new ArrayList<Node>());
}
int end = Math.min(start + getDataPageQueryParameters().getPageSize(), list.size());
List<Node> page = list.subList(start, end);
return new DataPage(page.size(), page);
}
}
The full implementation of this class can be found in the com.example.query package in the sample code. This includes a
line of registration code in the MyLibrary bundle class.
public class MyLibrary extends RxBundle {

registerClass(NetworkDataPageQuery.class);
. . .
You can test the code using an authenticated session in Postman and sending GET operation to the generic resource api
/rx/application/datapage.
Related topics
PDFs, videos, and API documentation (see page 1003)
Creating a command REST interface (see page 874)
Creating a custom REST resource (see page 875)
Handling exceptions (see page 877)
Login information (see page 880)
Creating a command REST interface

Command (com.bmc.arsys.rx.services.common.Command) is a built-in resource that provides a simple way of providing
a custom execute method with parameters. The purpose of command is to execute some code using parameters
supplied with the PUT operation. Commands are the operations that have some operational effect on the system, such
as starting a server, or take some business action (for example, close an incident).

Sample command Rest interface:
@JsonTypeInfo(use = JsonTypeInfo.Id.CLASS, include =

JsonTypeInfo.As.PROPERTY, property = "resourceType")
public
abstract class Command implements Registerable
…
public
class ClearApplicationDataCommand extends Command {
…
@AccessControlledMethod(authorization
= AuthorizationLevel.SubAdministrator, licensing = LicensingLevel.Application,
checkSchemaForSpecialAccess = true, promoteStructAdmin = true)
@Override
public URI execute(UriInfo uriInfo) {
processService =
ServiceLocator.getProcessService();
recordService = ServiceLocator.getRecordService();
deleteNoteTaskInstances();
deleteSetOfProcessDefinition();
return null;
}
}
Related topics
Creating a DataPageQuery REST interface (see page 873)
Creating a custom REST resource

You can create a new REST-based resource using BMC Helix Innovation Suite. The REST resource you create can support
all the standard HTTP operations (GET, PUT, POST and DELETE).
1. Create a Java class that implements RestfulResource interface (com.bmc.arsys.rx.services.common.

RestfulResource). RestfulResource is a Marker interface.
For example:
/**
* JAX-RS Resource for handling requests
related to Login Content. The class uses jersey specific
* implementation of Multi-Part. There is a
request for providing portable attachment support in
* JAX-RS please refer
https://java.net/jira/browse/JAX_RS_SPEC-413
*/
@Path("rx/application/logincontent")

public
class LoginContentResource
implements RestfulResource {
…
}
@GET
@Path("/favicon.ico")
public Response getLoginFavicon(@Context HttpHeaders httpHeaders)
{
try {
byte[] faviconContent = getLoginContentService().getFavicon(getHostName(httpHeaders));
if (faviconContent != null) {
StreamingOutput stream = new
StreamingOutput() {
@Override
public void
write(OutputStream outputStream) throws IOException,
WebApplicationException {
outputStream.write(faviconContent);
};
return Response.ok(stream,
MediaType.valueOf(LoginContentService.FAVICON_MEDIA_TYPE)).build();
} else {
return Response.ok().build();
}
} catch (RxException exception) {
… throw exception;
}
}
Annotation @Path describes the URL prefix.
2. Register the resource class in the bundle class (in activator start method).
3. Compile the code using Maven.
4. Deploy the REST resource using the following command:
You can test the REST resource using POSTMAN.
Related topics

Handling exceptions
While working with BMC Helix Innovation Suite services APIs, you might come across runtime exceptions ( RxException)
that contain error codes. You can use these error codes to define a mapping of exceptions with HTTP error responses.
The error codes can be used with @RxRestError annotation in a JAX-RS resource. For example, you can configure an
annotation in way that the error code is associated with a 404 response code and the Jersey error handler can
automatically set the response code correctly. Errors are modeled through the RxException class.
You can extend the RxException class (com.bmc.arsys.rx.services.RxException.java in BMC Helix Innovation Suite
SDK).
You can customize the HTTP status code sent to a REST API client for an exception in our custom REST resource
class using an annotation.
You can specify which error code should result in HTTP status 404.
You also can add an application level error message that is displayed before any other messages in RxException.
Overview of REST API error messages

A REST API returns two levels of error information:
HTTP error codes and messages in the response header
A JSON object in the response body with additional details
The error message information is provided in the following format:
message type
message number
message text
appended text
The following code sample represents the format of the message you receive when an error occurs:
[
{
"messageType": "ERROR",
"messageNumber": 303,
"messageText": "Record Definition does not exist on server.",
"appendedText": "com.example:non-existent-rd"
}
]
When any Digital Service application license related error occurs, REST API returns the HTTP response status 403
(Forbidden).

@RxRestError annotation
The @RxRestError annotation lets you specify the framework how to handle uncaught exceptions and specify which
error code should result in HTTP status 404. It also allows you to specify an application level error code for any
occurrence of uncaught exception.
Handling exceptions using RxException subclass

When you create Java service APIs, you can use the RxException subclass (com.bmc.arsys.rx.services.RxException.java in
BMC Helix Innovation Suite SDK) to handle exceptions.
1. Create an exception class that extends the RxException class. The following is a sample code:
public class MyException extends RxException {
private static final String BUNDLE_ID = "com.example.myapplication";
public MyException(int messageNum) {

this(messageNum, null, (Throwable) null);
}
public MyException(int messageNum, String appendedText) {

this(messageNum, appendedText, (Throwable) null);
}
public MyException(int messageNum, String appendedText, RxException e) {

super(messageNum, BUNDLE_ID, appendedText, e);
}
public MyException(int messageNum, String appendedText, Throwable t) {

super(messageNum, BUNDLE_ID, appendedText, t);
}
2. Define message constants or enum.

Create a constant class for message numbers that you want to put in LocalizationService. This provides you a
single location to reference your message numbers. The following is a sample message constant class:
public final class MyMessage {
public static final int ITEM_NOT_FOUND = 10_100;
public static final int ITEM_ACCEPTED = 10_101;
public static final int ERROR_CREATING_ITEM = 10_102;
/**
* Make the default constructor private since this class is not meant to be instantiated.
*/
private MyMessage() {
}

You can define enum instead of constant files. If you define enum, you must change your MyException class to
accept the enum instead of int. The following is a sample code:
public enum MyMessage {
ITEM_NOT_FOUND(10_100),
ITEM_ACCEPTED(10_101),
ERROR_CREATING_ITEM(10_102);
private final int intValue;
MyMessage(int intValue) {
this.intValue= intValue;
}
public int intValue() {

return messageNum;
}
public class MyException extends RxException {
private static final String BUNDLE_ID = "com.example.myapplication";
public MyException(MyMessage errorMessage, String appendedText, RxException e) {

super(errorMessage.intValue(), BUNDLE_ID, appendedText, e);
}
3. For every message that you have defined, add a message text in LocalizationService. See Localizing error
messages (see page 972).
4. (Optional) If you are creating application layer classes (for example, resources, commands, or data page queries),
you can add @RxRestError annotation to specify an application level error message and declare the error code
that should result in HTTP status 404.
The following is a resource sample:
public class MyResource implements RestfulResource {
@GET
@Path("{name}")
// removing other annotations for brevity
@RxRestError(notFoundErrorCode = MyMessage.ITEM_NOT_FOUND)
public Item get(@PathParam("name") String name) {
// TODO
return null;
}
@POST
// removing other annotations for brevity
@RxRestError(applicationErrorCode = MyMessage.ERROR_CREATING_ITEM)
public String post(Item item) {
// TODO
return null;
}

Related topics
Login information
All REST API calls must be authenticated. Instead of passing the full credentials on every REST API call, REST uses a token.
A new token is generated for each user request. The token is valid for a configurable amount of time and acts like a
temporary password. The expiry time of the token depends on the idle timeout and absolute timeout.
Login API example

The following code is a sample REST call to login a user:
POST http://localhost:8008/api/rx/application/command
Host: localhost
Accept: application/json
X-Requested-By: XMLHttpRequest
Content-Type: application/json;charset=UTF-8
{
"resourceType":
"com.bmc.arsys.rx.application.user.command.LoginCommand",
"username": "user",
"password": "userpassword",
"locale": "en-us"
}
The "locale": "en-us" name value pair in the above code is optional.
Extending session time

If a user requests to extend the session time before the idle timeout expiry, the session remains active till absolute
timeout expiry.
The following code is a sample REST call to keep a session active:
POST http://localhost:8008/api/rx/application/command
Host: localhost
Content-Type: application/json
AR-JWT-Refresh-From: Tue, 15 Nov 2016 08:12:31 GMT
default-bundle-scope: task-manager
Content-Length: 78
{
"resourceType" :"com.bmc.arsys.rx.application.user.command.KeepAliveCommand"
}
AR-JWT-Refresh-From is the HTTP header which indicates the starting time for calculating idle timeout of a user
session.
For the requests that do not need token refresh, you must include the Suppress-Token-Refresh HTTP headers in
the REST call. The value of Suppress-Token-Refresh is 1*<any US ASCII character except CTLs or separators>.

The following is a sample decoded JSON Web Token:
{
"sub": "GudJDqg4Ww8JLIjqKEU0Ui/N3SR0hN7mu0hvNfran1hOi9P52UA92CrLZXAUC
/VE7ROXFL6qUPIo9jj08HyZFWS9Z4KtXMQAwyJL6zWhJdJ0orDdvunWDQ==",
"nbf": 1467238964,
"_password": "OArJGmlNs6w8V29vZmWHUur5fxaiNCBV3mVuxmg650JMnS9e3RSTqmvUItnWAV5y/c54NDaaJD+8
//RC+oMV4YnG+65Tqc0OerGRWtoZTQWK+U+exU4BoA==",
"_impersonatedUser": null,
"iss": "clm-aus-013734.clm-mgmt.clm.bmc.com",
"_authString": "tph8/mleHvEN5hBqFchHiOhKJFsr6yTuzKNoWrF
/C0RVsXx66TKIVvB3TN4spAie41ICkwB1dFx+FaFjDQbRFbN5t8LkGn07D3D24S9J4IdML+wmV+Xorg==",
"_cacheId": 27,
"exp": 1467242684,
"iat": 1467239084,
"jti": "IDGAA5V0GFFS2AOJKAXIOIOKSQ4SHK",
"_absoluteExpirationTime": 1467325484
}
exp (Expiration Time)—JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z
UTC till specified UTC date/time, ignoring leap seconds. It represents the user session expiry time, when the user
is idle. It is calculated based on the Session-Idle-Timeout configuration.
_absoluteExpirationTime—JSON numeric value representing the number of seconds from 1970-01-01T00:00:

00Z UTC till specified UTC date/time, ignoring leap seconds. It represents the maximum time to which the
current user session can be extended. It is calculated based on the Session-Absolute-Timeout configuration.
Related topics
Customizing an application with REST APIs

BMC Helix Innovation Suite provides a few services that contain REST APIs; these REST APIs communicate with your
custom bundle deployed in the server. The REST API uses the base URL for the web service, such as https://<host>:<port>
/api/.
Each API is called by issuing a standard HTTP request method: POST, GET, PUT, or DELETE (more commonly known as
the CRUD operations: Create, Read, Update, and Delete).
List of REST APIs available for communicating with the server

You can use the following REST APIs to communicate with the custom bundle deployed in the server:
API Usage
RecordInstanceDataPageQuery REST API (see Used to retrieve record instances

page 882)
Approval REST APIs (see page 884) Used to access approvals directly in your application code, such as get approval request details or update
an approval request.
Foundation Service REST APIs (see page 892) Used to fetch the Foundation data and associations and feed the data to the consuming applications.

Related topics
Creating a custom interface with REST (see page 870)
Retrieving record instances using REST API

The RecordInstanceDataPageQuery REST API is used to retrieve record instances from any record definition based on
certain filtering conditions or query predicates.
Use the following syntax for RecordInstanceDataPageQuery:
<<URL>>/api/rx/application/datapage/?dataPageType=com.bmc.arsys.rx.application.record.datapage.
RecordInstanceDataPageQuery
&pageSize=<<any valid number as pageSize>>
&startIndex=<<any valid number as startIndex>>
&recorddefinition=<<fully qualified name of the recorddefinition>>
&propertySelection=<<comma separated fieldIds>>
&sortBy=<<comma separated fieldIds>>
&<<fieldID>>=<<fieldvalue>>
Which includes the following parameters:
dataPageType
Specifies the fully qualified class name of the RecordInstanceDataPageQuery.
This is a mandatory query parameter.
Note: Do not change the value of this parameter.
pageSize
Specifies how many records should be fetched in this page.
startIndex
Specifies the first record's index of the "page".
For example:
If startIndex=0 and pageSize=50, the dataPageQuery will return the first 50 records from the dataset.
If startIndex=50 and pageSize=50, then the dataPageQuery will return the records 50 - 100 from the dataset.
If startIndex=500 and pageSize=50, then the dataPageQuery will return the records 500 - 550 from the dataset.
If pageSize=-1, then all records are returned. Be careful when using this option because it may return a very large number of
records.
recorddefinition
Specifies the name of the record definition.
propertySelection
Specifies the list of comma separated properties which should appear in the response object, that is, the DataPage.data.
The propertySelection parameter accepts numeric fieldIds.
This is an optional query parameter.
For example,

&propertySelection=1,2,4,7
Here, we used only the fieldIds in the propertySelection.
sortBy
Specifies the list of comma separated properties by which data should get sorted.
The sortBy parameter accepts numeric fieldIds.
To indicate descending sort, prefix the value with hyphen (-).
For example:
To sort the data in an ascending order, specify the setting as sortBy = 1,2.
This means that the data is sorted in the ascending order of property ID 1 then by 2.
To sort the data in a descending order, specify the setting as sortBy=-3,-7.

This means that the data is sorted in the descending order of property Id 3 then by status.
To sort the data in an ascending and descending order, specify the setting as sortBy=1,-3,7.
This means that the data is sorted in the ascending order of property Id 1 then by descending order of property Id 3 and
then by ascending order of property status.
fieldId
Specifies the filtering condition of the query, using field IDs of the record definition.
You can specify multiple name-value pairs and the relational qualification between these name-value pairs is always set as AND.
For example:
&7=new
This means that retrieve only those records whose 'status' field's value is new.
&7=new&name=Jack
This means that retrieve only those records whose 'status' field's value is new and 'name' field's value is Jack.
queryExpression
Specifies complex queries that should be supported by RecordInstanceDataPageQuery.
You can specify attribute Id in place of attribute name.
You can specify the existing way of adding qualifications.
Ensure that you follow the URL encoding rules while specifying queryExpression.
For example:
To specify complex query supported by RecordInstanceDataPageQuery.

&queryExpression=('Description' LIKE "%A%" AND 'TaskID' > 29 )&startIndex=0&pageSize=-1
To specify atrribute Id for Description and TaskID attribute name.

&queryExpression=('536870913' LIKE "%A%" AND '536870915' > 29 )&startIndex=0&pageSize=-1
To specify the URL encoding rules.

&queryExpression=('Character Field1' = %27Character Field1%27%3D%22some description%22), where %27 represents ', %3D
represents =.
Example 1
To fetch the tasks where the 'status' of the task is new, use the following REST API call:
&pageSize=500&startIndex=0&recorddefinition=com.example.taskmanager-lib:Task&7=new

In this example, the instances will be fetched from com.example.taskmanager-lib:Task RecordDefinition and 7 is one of
the FieldDefinitinition's ID on this RecordDefinition.
Example 2
To fetch the tasks where the 'status' of the task is new and data is to be fetched for fieldIds 1, 8, 7, 379 and the tasks
should be sorted on fieldId 1, use the following REST API call:
RecordInstanceDataPageQuery&
pageSize=500&startIndex=0&recorddefinition=com.example.taskmanager-lib:Task&7=new&propertySelection=1,8,7,379&
sortBy=1
In this example, the instances will be fetched from com.example.taskmanager-lib:Task RecordDefinition and 7 is one of
the FieldDefinition's ID on this RecordDefinition. 1, 8, 7, 379 are Ids of the FieldDefinitions on this RecordDefinition.
Example 3
To fetch the tasks where the 'Description' of the task is Printing, use the following REST API call:
&pageSize=500&startIndex=0&recorddefinition=com.example.taskmanager-lib:Task&queryExpression=(%27Description%2
7%3D%22Printing%22)
In this example, the instances will be fetched from com.example.taskmanager-lib:Task RecordDefinition.
Related topics
Using Approval REST APIs

The Approvals library contains REST APIs that enable you to access approvals directly in your application code. Using the
ApprovalSignatureResource REST APIs, you can get approval request details or update an approval request.
You can use the Approval REST APIs to perform the following tasks:
Get the approval request details.
Approve or reject the approval requests.

View the approval requests assigned to users.
Search for specific approval requests.
Approval REST APIs

The ApprovalSignatureResource resource provides the following APIs:
API Description
getApprovals (see page 886) Returns a list of all approval requests assigned to all users.
getApprovalsByUserId (see page 887) Returns all the approval requests that contain the specified approver.
listApprovalDetailsByEntryIds (see page 888) Returns the approval requests that contain the specified entry ID such as approval ID.
getSingleApproval (see page 889) Returns the details of the single specified approval ID
getSignature (see page 889) Returns the approval request signature of the specified approval ID.
updateStatus (see page 890) Updates an approval request with the specified status.
searchApprovalsByUserAndSearchText (see page 891) Searches for approval requests that contain the specified user and search text.
Sample response
All the GET Approval APIs have similar response format. The following code snippet illustrates the a sample JSON that is
returned by a GET Approval REST API:
{
"totalSize": 1,
"data": [
{
"actionDate": null,
"summary": "testing sig",
"requester": "DellAdmin",
"priority": "Normal",
"application": "com.example.taskmanager:TestRD",
"status": "Pending",
"request": "000000000000401",
"signatureID": "000000000000301",
"createDateSig": "2017-03-29T10:41:19.000Z",
"approverSignature": null,
"alternateSignature": null,
"process": "testWFAD",
"order": 1,
"approvalID": "000000000000302",
"nextGlobalEscalationTime": null,
"signatureInstanceID": "AGGAABDUC2YGIAONKO2VOMOQCICO9T|AGGAABDUC2YGIAONKO2WOMOQCICOK9",
"assigneeGroupPermissions": "402;0;",
"completed": null,
"statusDtl": "Pending",
"approvers": "DellAdmin;testing;testingDellAdmin;testing:DellAdmin",
"processInstanceId": "AGGJ980ICQU7QAONJLZLOM3OD1EOL4",
"modifiedDateSig": "2017-03-29T10:41:19.000Z",
"notes": null,
"nextActionEscalationDate": null,
"sigTermStateDate": null,
"justification": null,
"otherDetail1": null,
"requireJustificationOnRejection": "No",
"justificationField": null,

"canReassign": "Yes",
"toolTip": null
}
]
}
Get approvals list

u can use the getApproval method to get a list of all approvals assigned to all users.
URL
The following URL is the syntax for the getApproval method:
GET rx/application/approval?
Parameters
The following parameters are supported by the getApproval method:
Parameter Description Example
URL parameters
pageSize Specifies how many records should be returned in this page. GET rx/application/approval/{userId}?
&pageSize=10&status=Pending&status=Approved
startIndex Specifies the first record index of the page. GET rx/application/approval/{userId}?
&startIndex=0&status=Pending&status=Approved
propertySelection Specifies the list of comma-separated properties that should GET rx/application/approval/{userId}?&propertySelection=application,
appear in the response object. summary,requester,status,request,createDateSig
The propertySelection parameter accepts numeric fieldIds or a

string of fieldNames or a combination of both.
status Specifies status types for which want to get approvals. GET rx/application/approval?status=Pending&status=Approved
Query parameters
modified-before Returns a list of approvals modified before the specified date. GET rx/application/approval?modified-before=2017-04-21T07:22:
21.000Z
modified-after Returns a list of approvals modified after the specified date. GET rx/application/approval?modified-after=2017-04-21T07:22:21.000
Z
created-before Returns a list of approvals created before the specified date. GET rx/application/approval?created-before=2017-04-21T07:22:21.000
Z
created-after Returns a list of approvals created after the specified date. GET rx/application/approval?created-after=2017-04-21T07:22:21.000Z
Example: Using multiple values in query parameters

You can also use multiple values in the query parameters. If you provide multiple values in the query parameters, the
method returns the approvals that match any property value.
If you want the list of approvals with pending status and approved status that were modified after a specific date, use the
following URL:
rx/application/approval?modified-after=2017-04-21T07:22:21.000Z&status=Pending&status=Approved

Related topics
Get approval details by using entry ID (see page 888)
Get single approval (see page 889)
Get approval details by using user ID

You can use the getApprovalsByUserId method to get all the approvals that contain the specified user as the approver.
URL
The following URL is the syntax to use the getApprovalsByUserId method:
GET rx/application/approval/{userId}?
Parameters
The following parameters are supported by the getApprovalsByUserId method:
URL parameter
pageSize Specifies how many records should be returned in this page. GET rx/application/approval/{userId}?
&pageSize=10&status=Pending&status=Approved
startIndex Specifies the first record index of the page. GET rx/application/approval/{userId}?
&startIndex=0&status=Pending&status=Approved
propertySelection Specifies the list of comma-separated properties, that should GET rx/application/approval/{userId}?&propertySelection=application,
appear in the response object. summary,requester,status,request,createDateSig
The propertySelection parameter accepts numeric fieldIDs or

string fieldNames or a combination of both.
status Returns the list of approvals with the specified status. GET rx/application/approval/{userId}?status=Pending&status=Approved
Query parameter
modified-before Returns the list of approvals that were modified before the GET rx/application/approval/{userId}?modified-before=2017-04-21T07:
specified date. 22:21.000Z
modified-after Returns the list of approvals that were modified after the GET rx/application/approval/{userId}?modified-after=2017-04-21T07:22:
specified date. 21.000Z
created-before Returns the list of approvals that were created before the GET rx/application/approval/{userId}?created-before=2017-04-21T07:
specified date. 22:21.000Z
created-after Returns the list of approvals that were created after the GET rx/application/approval/{userId}?created-after=2017-04-21T07:22:
specified date. 21.000Z
Example: Using multiple values in query parameters

You can also use multiple values in the query parameters. If you provide multiple values in the query parameters, the
method returns the approvals that match any property value.

If you want the list of approvals with pending status and approved status that were modified after a specific date, you can
use the following URL:
GET rx/application/approval/{userId}?modified-after=2017-04-21T07:22:21.000Z&status=Pending&status=Approved
Related topics
Get approvals list (see page 886)
Get approval details by using entry ID

You can use the listApprovalDetailsByEntryIds method to get all approvals that contain the specified entry IDs.
URL
The following URLs are the syntax to use the listApprovalDetailsByEntryIds method:
GET rx/application/approval?
Or
GET rx/application/approval/{userId}?
Parameters
The following parameters are supported by the listApprovalDetailsByEntryIds method:
URL parameter
pageSize Specifies how many records should be returned in this page.
startIndex Specifies the first record index of the page.
propertySelection Specifies the list of comma separated properties that should appear in the response object.
The propertySelection parameter accepts numeric fieldIDs or a string of fieldNames or a combination of both.
Query parameter
request Indicates the request IDs of the approval for which you want the approval details.
application Indicates the record definition name of the approval for which you want the approval details.
You must specify the fully qualified record definition name.
Example
To get the approval details of the approval with ID 000000000000001 and approval with ID 000000000000002.
GET rx/application/approval?application=com.example.online-exam:AppRD&request=000000000000001&request=00000000
0000002

Related topics
Get approval details by using user ID (see page 887)
Get single approval

You can use the getSingleApproval method to get a single approval with the specified ID.
URL
The following URL is the syntax to use the getSingleApproval method:
GET rx/application/approval/single/{identifier}
where identifier is the signatureInstanceID property of the approval signature.
Example
If you want to get the approval with the signatureInstanceID
AGGAA5V0HGZZVAOORA10ONVA9CKZZ4|AGGAA5V0HGZZVAOORA10ONVA9CLAAF, use the following URL:
GET rx/application/approval/single/AGGAA5V0HGZZVAOORA10ONVA9CKZZ4|AGGAA5V0HGZZVAOORA10ONVA9CLAAF
where AGGAA5V0HGZZVAOORA10ONVA9CKZZ4|AGGAA5V0HGZZVAOORA10ONVA9CLAAF is signatureInstanceID

property of the approval signature.
Related topics
Get approval signature

You can use the getSignature method to retrieve the signature of an approval. This method retrieves details such as
approval status, escalation time, signature due date, and so on.
URL
The following URL is the syntax of the getSignature method :
GET rx/application/approval/preview/{id}
where id is the ID of the approval signature.
Sample response
The following code snippet illustrates a sample JSON that is returned by the getSignature method:
{
"totalSize": 1,

"data": [
{
"signatureId": "000000000000103",
"approvalStatus": "Pending",
"approvers": "Jonnie",
"nextActionEscalationTime": null,
"application": null,
"signatureDueDate": null,
"sigTermStateDate": null,
}
]
}
Example
If you want to get the signature of the approval that has the ID 000000000000005 , use the following URL:
GET approval/preview/000000000000005
Related topics
Update approval status

You can use the updateStatus method to update the status of an approval. This method allows you to set the status of
an approval to Approved, Rejected, Reassign, or OnHold for the specified approval request ID. The updateStatus method
returns the status 200 when it updates the approval successfully.
URL
The following URL is the syntax for the updateStatus method:
PUT rx/application/approval/single/{identifier}
Parameters
The following query parameters are supported by the updateStatus method:
command (Required) Specifies the approval status in this parameter. You can specify the PUT rx/application/approval/single/{identifier}
status as Approved, Rejected, Reassign, or OnHold.
{
"command":"Rejected",
justificationOrReason Specifies your comment for the approval status . This parameter is optional for all PUT rx/application/approval/single/{identifier}
approval statuses except the Rejected status.
{
If you provide the status as Rejected in the command parameter, you must provide "command":"Approved",
the justification comment. "justificationOrReason":"CanbeApproved"
}
assignToApprovers Specifies the approver name when the status is Reassign. PUT rx/application/approval/single/{identifier}

When you specify the status as Reassign, in this parameter you must provide the {
approver name to whom the request needs to be assigned.
"command":"Reassign",
This parameter supports only one user. You cannot reassign the approval to
"assignToApprovers:"Approver names to
multiple users.
whom request needs to be reassigned"
Related topics
Get approval signature (see page 889)
Search approval by user and by search text (see page 891)
Search approval by user and by search text

You can use the searchApprovalsByUserAndSearchText method to get all the approvals that contain the specified users
who are approvers and the search text. The search is performed only on the character fields. This method does not
support search on date fields and integer fields.
URL
The following URL is the syntax for the searchApprovalsByUserAndSearchText method:
GET rx/application/approval/search?
Parameters
The following parameters are supported by the searchApprovalsByUserAndSearchText method:
userId Specifies the user ID of the approver user GET rx/application/approval/search?userId=Allen
searchText (Required) Specifies the text that you want to search. GET rx/application/approval/search?userId=Allen&searchText=Where Is My
Approval
searchBy Specifies the attributes from the Signature domain object

GET rx/application/approval/search?userId=Allen&searchText=Where Is My
on which you want to search. You can provide attributes
Approval&searchBy=justification&searchBy=process&searchBy=application
such as justification, process, and application.
The search is performed against the justification, process, application
You can use the following searchBy attributes to search attributes of Signature domain object.
the AP:Detail-Signature fields: GET rx/application/approval/search?userId=Allen&searchText=Where Is My
Approval
summary—14506 field
The search is performed against all character attributes in the Signature
application—10051 field domain object.
request—10050 field
process—10000 field
notes— 14513 field
toolTip—14512 field

justification—14518 field
otherDetail1—14508 field
Note: If you do not specify the searchBy attribute, the

search is performed on all the character fields of the
Signature objects.
Related topics
Get approval signature (see page 889)
Update approval status (see page 890)
Using Foundation Service REST APIs

The Foundation Service contains REST APIs that you can use in your application to fetch the Foundation data and
associations and feed the data to the consuming applications.
Foundation Service provides the following types of APIs:
Common REST APIs that enable developers to get Foundation data and associations.
Specific REST APIs that enable developers to consume only the Foundation constructs and data.
Using the REST APIs, you can get the following Foundation data:
Person data such as profile photo, primary site, department, and support group.
Organization data such as the following:
Organization name and organization ID.
Primary organization data such as operating organization, service provider, manufacturer, and vendor
organizations.
Secondary organization data such as business unit, department, and support group.
Category data.
Location data such as region, site, and site area.
For more information about Foundation data, see Creating or modifying Foundation data (see page 661).
Types of Foundation Service APIs

The following table provides information about the Foundation Service APIs:

API Description
To retrieve Person data
Get person details (see page 894) Gets the details of any person within the organization. The person can be an employee, agent, customer, or
vendor.
Get person details by using person ID (see page Gets the contact details of any person within the organization by using the person ID. The person can be an
896) employee, agent, customer, or vendor.
Get card by search text (see page 896) Gets the contact details of any person that matches the search criteria. The person can be an employee,
agent, customer, or vendor.
Get person information by notification (see Gets the details of persons who are associated with a specific organization.
page 898)
To retrieve Organization data
Get Organization information (see page 898) Gets details of any type of organization.
Get list of organizations (Data page) (see page Gets all the organizations of a specific type by searching with the organization type.
899)
Get organization details by using organization ID Gets details of any type of organization by using the organization ID.
(see page 901)
To retrieve Categorization data
Get category details by using search criteria Get details of all categories that match the search criteria.
(see page 902)
Get category details by using category ID (see Get details of any type of category by using the category ID.
page 903)
To retrieve Region data
Get region by search text (see page 904) Gets details of all the regions that match the search criteria.
Get region information by ID (see page 905) Gets the details of any region by using the region ID.
To retrieve Site data
Get sites by search text (see page 906) Gets the details of all sites that match the search criteria.
Get site details by using site ID (see page 907) Gets details of a site by using the site ID.
Get person for site (see page 907) Gets the persons associated with a specific site ID.
Get organization details for a site by using site ID Gets the organizations that are associated with a site by using the site ID.
(see page 908)
To retrieve Site Area data
Get site area details by using site ID (see page Gets the site areas that are associated with a site by using the site ID.
909)
Get site area details by using search criteria (see Gets the details of all the site areas that match the search criteria.
page 910)
Get site area details by using site area ID (see Gets details of a site area by using the site area ID.
page 911)

Sample response
All the GET Foundation Service APIs have similar response format. The following code snippet illustrates a sample JSON
that is returned by a GET Foundation Service REST API:
{ "personSelection": {
"value": "Employee",
"id": 300
}
"fullName": "Bob Baxter",
"thumbnail": "iVBORw0KGgoAAAAN…",
"primaryEmail": "B.Baxter@calbroservices.com",
"primaryPhone": "1 212 555-5454 (22)",
"loginId": "Bob",
"personId": "PPL000000000014",
"id": "d0820c35-e959-416c-96d5-b3eeb959e2aa",
"isManager": "true",
"VIP": {
"id": 0,
"value": "false"
},
"primaryOrganization": {
"id": "1234567890",
"name": "Calbro Services",
},
"primarysite": {
"name": "Boston Support Center",
"address": {
"street": "1114 Eighth Avenue, 31st Floor",
"city": {
"name": "Buffalo",
"id": "52465637-dc21-427f-b408-b488297483d8"
},
"state": {
"name": "New York",
"id": "52465637-dc21-427f-b408-b488297483d7"
},
"country": {
"name": "United States",
"id": "52465637-dc21-427f-b408-b488297483d6"
},
"zip": "10036"
},
"region": {
"name": "Americas",
"id": "GUIDRGN"
}
},
"createdBy": "rmitcham1705",
"createdDate": "2017-03-07T19:02:38.000Z",
"modifiedBy": "rmitcham1705",
"modifiedDate": "2017-03-07T19:02:38.000Z",
}
Get person details

The get Person Information method enables you to fetch the contact details of any person within the organization. The
person can be an employee, agent, customer, or vendor.

URL
Use the following URL for get Person Information method:
/api/com.bmc.arsys.rx.foundation/person?pageSize=<<any valid number as pageSize>>

&propertySelection=<<comma separated fieldIds or fieldNames>>
&queryExpression=<<any valid query expression>>
&loginId=<<any valid login Id>>
&personId=<<any valid person Id>>
&organizationId=<<any valid organization Id>>
Parameters
The following table provides information about the parameters of the get Person Information method.
pageSize Specifies how many records should be returned in this page. /person?pageSize=35
If you do not specify this parameter, the method fetches 50 records

by default.
startIndex Specifies the first record's index of the page. /person?startIndex=50
propertySelection Specifies the list of comma-separated properties that should appear /person?
in the response object. queryExpression='personSelection' LIKE
"Employee"&propertySelection=loginId,
The propertySelection parameter accepts numeric fieldIds or string
fullName
fieldNames or a combination of both.
sortBy Specifies the list of comma-separated properties by which data /person?sortBy=-fullName

should get sorted.
The sortBy parameter accepts numeric fieldIds or string fieldNames

or a combination of both. To indicate a descending sort, prefix the
value with hyphen (-)
queryExpression Specifies the search criteria to fetch the persons. /person?

queryExpression='personSelection' LIKE
"Employee"
loginId Specifies a comma-separated list of login IDs and returns all the /person?loginId=employee9
persons that match the login IDs.
personId Specifies a comma-separated list of person IDs and returns all the /person?personId=EMPID9
persons that match the person IDs.
organizationId Specifies a comma-separated list of organization IDs and returns all /person?
the organizations that match the organization IDs. organizationId=ORGMO10BU1DEPT1SG1
Example
To fetch the person details for a given login ID, person ID, and organization ID, use the following URL:
/api/com.bmc.arsys.rx.foundation/person?propertySelection=loginId,
id&loginId=employee9&personId=EMPID9&organizationId=ORGMO10BU1DEPT1SG1
In the example, loginId and id are person fields. employee9 is a valid login ID, EMPID9 is a valid person ID, and
ORGMO10BU1DEPT1SG1 is a valid organization ID.

Related topics
Get person details by using person ID (see page 896)
Get person information by notification (see page 898)
Get person details by using person ID

The get card by person ID method enables you to fetch the contact details of any person within the organization by
using the person ID. The person can be an employee, agent, customer, or vendor. The method can also be used with
various INCLUDE parameters to fetch additional details of the person.
URL
Use the following URL for the get card by person ID method:
/api/com.bmc.arsys.rx.foundation/person/cards/{id}
OR
/api/com.bmc.arsys.rx.foundation/person/cards/{id}?include=thumbnail,primarySite,departments,
memberSupportGroups,assocMemberSupportGroups,managesPersons
Parameter
The following table provides information about the parameter of the get card by person ID method.
id Specifies a valid person ID. /person/cards/{id}
include Gets additional information of the person. For example, information /person/cards/{id}?include=thumbnail,
such as thumbnail, primary site, departments, manages persons, primarySite,departments,
member of support groups, and associate member of support groups. memberSupportGroups,
assocMemberSupportGroups,managesPersons
Example
To fetch the employee details along with the thumbnail, primary site, and departments that the employees belong to, use
the following URL:
/api/com.bmc.arsys.rx.foundation/person/cards/80D5BA1D6F6D43CFBCE07AF00018DD14?include=thumbnail,primarySite,
departments
Related topics
Get person details (see page 894)
Get person information by notification (see page 898)
Get person details by using search criteria

The get card by search text method enables you to fetch the contact details of any person that matches the search
criteria. The person can be an employee, agent, customer, or vendor. The method can also be used with various
INCLUDE parameter to fetch additional details of the persons.
URLs
The following table provides information about the URLs used to fetch the person details:

Goal URL
To get /api/com.bmc.arsys.rx.foundation/person/cards
contact
details of all
persons
To get a list /api/com.bmc.arsys.rx.foundation/person/cards?queryExpression=<<valid query expression>>

of all
person
details
based on
the search
criteria
To get /api/com.bmc.arsys.rx.foundation/person/cards?queryExpression=<<valid query

additional expression>>&include=thumbnail,primarySite,departments,memberSupportGroups,
details assocMemberSupportGroups,managesPersons&pageSize=<<any valid number as
along with pageSize>>&startIndex=<<any valid number as startIndex>>&propertySelection=<<comma
list of separated fieldIds or fieldNames>>&sortBy=<<comma separated fieldIds>>
person
cards
Parameter
The following table provides information about the parameter of the get card by search text method:
include Gets additional information of the person. For example, /api/com.bmc.arsys.rx.foundation/person

information such as thumbnail, primary site, /cards?queryExpression=<<valid
departments, manages persons, member of support queryexpression>>&include=thumbnail,
groups, and associate member of support groups. primarySite,departments,memberSupportGroups,
assocMemberSupportGroups,managesPersons
primaryOrganization Gets a list of search results based on the primary /api/com.bmc.arsys.rx.foundation/person

organization. /cards?
primaryOrganization=<someOrganizationGuidHere>
supportOrganization Gets a list of search results based on the support /api/com.bmc.arsys.rx.foundation/person

organization. /cards?
supportOrganization=<someOrganizationGuidHere>
employeeId Gets a list of search results based on the employee ID. Exact match: /api/com.bmc.arsys.rx.foundation
/person/cards?employeeId=<EMPID>
Similar match: /api/com.bmc.arsys.rx.foundation

/person/cards?employeeId=<EMPID%>
Example
To get all the contact details of agent persons along with their thumbnails and details of support groups they are a
member of, use the following URL:
/api/com.bmc.arsys.rx.foundation/person/cards?queryExpression='personSelection' LIKE "Agent"&include=thumbnail

,memberSupportGroups&pageSize=30&sortBy=fullName
Related topics

Get person information for an organization

The person information by notification method enables you to fetch details about persons who are associated with a
specific organization.
URL
Use the following URL for the person information by notification method:
/api/com.bmc.arsys.rx.foundation/organization/person?orgName=<<Organization name>>
&orgId=<<Organization Id>>
Parameters
The following table provides information about the parameters of the person information by notification method:
Parameter Description Syntax
orgName Gets a comma-separated list of organization names, which includes /api/com.bmc.arsys.rx.foundation/organization

information about persons who are related to the organization. /person?orgName=<<Sample Org name>>
You must provide either the orgName or the OrgId parameters.
orgId Gets a comma-separated list of organization names, which includes /api/com.bmc.arsys.rx.foundation/organization

information about persons who are related to the organization. /person?orgId = <<Sample Org Id>>
You must provide either the orgName or the OrgId parameters.
Example
To get the person information for notification for a given organization name or organization ID, use the following URL:
/api/com.bmc.arsys.rx.foundation/organization/person?orgName=ORG SP1 BU2 SG1&orgId=ORGMO1BU1DEPT1SG1
In the example, ORGMO1BU1DEPT1SG1 is a valid organization ID and ORG SP1 BU2 SG1 is a valid organization name.
Related topics
Get person details by using search criteria (see page 896)
Get organization details

The get Organization Information method enables you to fetch the details of any type of organization.
URL
Use the following URL for the get Organization information method:
/api/com.bmc.arsys.rx.foundation/organization?pageSize=<<any valid number as pageSize>>

&orgId=<<Organization Id>>

&orgName=<<Organization Name>>
Parameters
The following table provides information about the parameters of the get Organization Information method.
pageSize Specifies how many records should be returned in this page. /organization?pageSize=35
If you do not specify this parameter, then the method fetches 50

records by default.
startIndex Specifies the first record's index of the page. /organization?startIndex=50
propertySelection Specifies the list of comma-separated properties which should /organization?

appear in the response object. queryExpression='personSelection' LIKE
"Employee"&propertySelection=loginId,
fullName
sortBy Specifies the list of comma-separated properties by which data /organization?sortBy=-fullName

should get sorted.

value with hyphen (-)
queryExpression Specifies the search criteria to fetch the persons. /organization?

queryExpression='personSelection' LIKE
"Employee"
orgID Specifies a comma-separated list of organization IDs and returns all /organization?
the organizations that match the organization ID. orgId=AGGAA5V0HHFM9AOO45DAON85PX1AL9
orgName Specifies a comma-separated list of organization names and returns /organization?orgName=Manufacturer Org 3
all the organizations that match the organization name.
Example
To get organization names and distribution list information for given organization ID and organization name, use the
following URL:
/api/com.bmc.arsys.rx.foundation/organization?orgId=AGGAA5V0HHFM9AOO45DAON85PX1AL9&orgName=Manufacturer Org 3&

propertySelection=organizationName,notificationEmailList
In the example, organizationName and notificationEmailList are organization fields,

AGGAA5V0HHFM9AOO45DAON85PX1AL9 is a valid organization ID, and Manufacturer Org 3 is a valid organization name.
Related topics
Get list of organizations (Data page) (see page 899)
Get organization details by using organization ID (see page 901)
Get organization details by using organization type

The get list of organizations (Data page) method enables you to fetch all the organizations of a specific type by searching
with the organization type. The method can also be used with various include parameter to fetch additional details of the
organizations.

URLs
The following table provides information about the URLs used to fetch organization details:
Goal URL
To get a list of all organizations based on organization /api/com.bmc.arsys.rx.foundation/organization/{organization

type type}
To get additional details along with list of the

/api/com.bmc.arsys.rx.foundation/organization/{organization type}?
organizations of a specific type
queryExpression=<<valid query expression>>
include=parentHoldingCompany,parentServiceProvider,parentOrg,childOrgs
&pageSize=<<any valid number as pageSize>>
Parameters
The following table provides information about the parameters of the get list of organizations (Data page) method:
organization type Specifies the type of the organization. /organization/supportgroup?include=parentOrg
The organization can be of either of the following types:
primaryorg
businessunit
department
supportgroup
queryExpression Specifies the search criteria to fetch the set of organizations /organization/primaryorg?
that match the query. queryExpression='organizationName' LIKE "%
Internal%"
propertySelection Specifies the list of comma-separated properties which /organization/department?

should appear in the response object. queryExpression='organizationName' LIKE "%
Internal%"&propertySelection=groupId,
The propertySelection parameter accepts numeric fieldIds
organizationName
or string fieldNames or a combination of both.
pageSize Specifies the number of records that should be returned in /organization/supportgroup?pageSize=35

this page.
If you do not specify this parameter, then the method

fetches 50 records by default.
sortBy Specifies the list of comma-separated properties by which /organization/department?sortBy=-groupId

data should get sorted.
The sortBy parameter accepts numeric fieldIds or string

fieldNames or a combination of both. To indicate a
descending sort, prefix the value with hyphen (-).
startIndex Specifies the first record's index of the page. /organization/supportgroup?startIndex=50

Example
To get all the organizations of support groups type along with their parent organizations, use the following URL:
/api/com.bmc.arsys.rx.foundation/organization/supportgroup?include=parentOrg&pageSize=20&startIndex=5&sortBy=o
rganizationName
Related topics
Get organization details (see page 898)
Get organization details by using organization ID (see page 901)
Get organization details by using organization ID

The get organization by ID method enables you to fetch details of any type of organization by using the organization ID.
The method can also be used with various include parameters to fetch additional details of the of the organization.
URLs
The following table provides information about the URLs used to fetch organization details:
Goal URL
To get a list of all organizations based on organization /api/com.bmc.arsys.rx.foundation/organization/{organization

type type}/{organization Id}
To get additional details along with list of the

/api/com.bmc.arsys.rx.foundation/organization/{organization type}/
organizations of a specific type
{organization Id}?
include=parentHoldingCompany,parentServiceProvider,parentOrg,childOrgs
Parameters
The following table provides information about the parameters of the get organization by ID method:
organization Specifies the type of the organization. /organization/supportgroup?

type include=parentOrg
The organization can be of either of the following types:
primaryorg
businessunit
department
supportgroup
organization Specifies the ID of the organization.

/organization/primaryorg
Id
/AGGAA5V0GE9LDAOM42FWOL85QCKNQZ
include Gets additional information of the organization. For example, information such as parent
/organization/primaryorg
holding company, parent service provider, parent organization, child organization, and related
/AGGAA5V0GE9LDAOM42FWOL85QCKNQZ?
sites.
include=parentHoldingCompany,
parentServiceProvider

Example
To get the details of operating organization with additional details such as service provider and related sites, use the
following URL:
/organization/operatingorg/AGGAA5V0GE9LDAOM42FWOL85QCKNQZ?include=parentServiceProvider,relatedSites
Related topics
Get Organization information (see page 898)
Get list of organizations (Data page) (see page 899)
Get category details by using search criteria

The get category by search text method enables you to get details of all categories that match the search criteria.
URLs
The following table provides information about the URLs used to fetch category details:
Goal URL
To get a list of all categories based on the /api/com.bmc.arsys.rx.foundation/categorization/{categorization

categorization type type}
The categorization can be any of the following types:
product
operational
rootcause
resoultion
To get a list of all categories based on /api/com.bmc.arsys.rx.foundation/categorization/{categorization

categorization type and search criteria type}?searchText=<<Search Text>>
To get list of categories based on search /api/com.bmc.arsys.rx.foundation/categorization/{categorization

criteria and include all child categories type}?searchText=<<Search Text>>&directChildren=true
Parameters
The following table provides information about the parameters of the get category by search text method:
categorization Specifies the type of the category. The categorization can be of either /categorization/product/
type of the following types: {AGGAA5V0GE9LDAOM42FWOL85QCKNQZ}
product
operational
rootcause
resoultion
searchText Returns all categories that match the search text in either the name /categorization/{categorization type}?
or the description. searchText=Operating
System&searchText=laptop
You can use multiple search text in the same query to get the final
search result.

directChildren Returns all the child categories that are associated with requested /categorization/product?
categories. searchText=Microsoft&directChildren=true
propertySelection Specifies the list of comma-separated properties which should appear /categorization/product?
in the response object. searchText=Microsoft&
propertySelection=categorizationName,
categorizationDescription
pageSize Specifies how many records should be returned in this page. /categorization/resoultion?pageSize=35
If you do not specify this parameter, then the method fetches 50

records by default.
sortBy Specifies the list of comma-separated properties by which data /categorization/rootcause?

should get sorted. sortBy=categorizationName

value with hyphen (-).
startIndex Specifies the first record's index of the page. /categorization/rootcause?startIndex=50
Example
To get all product categories that have Calpro in the name or description and the children categories, use the following
URL:
/api/com.bmc.arsys.rx.foundation/categorization/product?searchText=Calpro&directChildren=true
Related topic
Get category details by using category ID (see page 903)
Get category details by using category ID

The get specific category by ID method enables you to fetch details of any type of category by using the category ID.
URLs
The following table provides information about the URLs used to fetch category details:
Goal URL
To get details of a specific category /api/com.bmc.arsys.rx.foundation/categorization/{categorization type}/

{Category Id}
The categorization can be any of the following types:
product
operational
rootcause
resoultion
To get details of a category along with /api/com.bmc.arsys.rx.foundation/categorization/{categorization type}/

the children categories {Category Id}?directChildren=true

Parameters
The following table provides information about the parameter of the get specific category by ID method:
categorization Specifies the type of the category. The categorization can /categorization/product/
type be any of the following types: {AGGAA5V0GE9LDAOM42FWOL85QCKNQZ}
product
operational
rootcause
resoultion
Category Id Specifies the ID of the category. /categorization/product/

{AGGAA5V0GE9LDAOM42FWOL85QCKNQZ}
directChildren Returns all the child categories associated with the /categorization/product
requested category. /AGGAA5V0GE9LDAOM42FWOL85QCKNQZ?
directChildren=true
Example
To get details of the operational category along with the child categories, use the following URL:
/api/com.bmc.arsys.rx.foundation/categorization/operational/AGGAA5V0GE9LDAOM42FWOL85QCKNQZ?directChildren=true
Related topic
Get category details by using search criteria (see page 902)
Get region details by using search criteria

The get region by search text method enables you to fetch details of all regions that match the search criteria.
URL
Use the following URL for the get region by search text method:
/api/com.bmc.arsys.rx.foundation/location/region?pageSize=<<any valid number as pageSize>>

Parameters
The following table provides information about the parameters of the get region by search text method:

/location/region?pageSize=35
If you do not specify this parameter, then the method fetches 50 records by default.
startIndex Specifies the first record's index of the page. /location/region?startIndex=50
propertySelection Specifies the list of comma-separated properties which should appear in the response /location/region?
object. propertySelection=locationName

The propertySelection parameter accepts numeric fieldIds or string fieldNames or a

combination of both.
sortBy Specifies the list of comma-separated properties by which data should get sorted. /region/rootcause?
sortBy=regionName
The sortBy parameter accepts numeric fieldIds or string fieldNames or a combination
of both. To indicate a descending sort, prefix the value with hyphen (-).
queryExpression Specifies the search criteria to fetch the regions. /location/region?

queryExpression='status' like
"Enabled"
Example
To get all the region names with the status Enabled, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/region?propertySelection=locationName&queryExpression='status' like
"Enabled"
In the example, locationName and status are region fields.
Related topic
Get region information by ID (see page 905)
Get region details by using region ID

The get region information by ID method enables you to fetch the details of any region by using the region ID.
URL
Use the following URL for the get region information by ID method:
/api/com.bmc.arsys.rx.foundation/location/region/<<Region Id>>?include=<<allParentRegions>>
Parameters
The following table provides information about the parameters of the get region information by ID method:
Region Id Specifies a valid region ID. If an invalid or incorrect region ID is provided, a response code 500 is returned.
/location/site
Additionally, the following message is displayed:
/foundation_region_00001
[ERROR (302): Entry does not exist in database; com.bmc.arsys.rx.
foundation:Region:foundation_region_000077]
In the above message, foundation_region_000077 is an invalid region ID.
include Gets additional information of the region, such as all parent regions.
/location/region?
include=allParentRegions
Example
To fetch regions with all parent regions for a given region ID, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/region/foundation_region_00001?include=allParentRegions

In the example, foundation_region_00001 is a valid region ID.
Related topic
Get region by search text (see page 904)
Get site details by using search criteria

The get sites by search text method enables you to fetch the details of all sites that match the search criteria.
URL
Use the following URL for the get sites by search text method:
/api/com.bmc.arsys.rx.foundation/location/site?pageSize=<<any valid number as pageSize>>

Parameters
The following table provides information about the parameters of the get sites by search text method:
pageSize Specifies how many records should be returned in this page. /location/site?pageSize=35
If you do not specify this parameter, then the method fetches 50 records by
default.
startIndex Specifies the first record's index of the page. /location/site?startIndex=50
propertySelection Specifies the list of comma-separated properties that should appear in the /location/site?
response object. propertySelection=siteName,
siteDescription
The propertySelection parameter accepts numeric fieldIds or string fieldNames or
a combination of both.
sortBy Specifies the list of comma-separated properties by which data should get sorted. /location/site?sortBy=siteName
The sortBy parameter accepts numeric fieldIds or string fieldNames or a

combination of both. To indicate a descending sort, prefix the value with hyphen (-
).
queryExpression Specifies the search criteria to fetch the set of organizations that match the query. /location/site?
queryExpression='siteName'
LIKE "%Internal%"
Example
To get all site names and descriptions where the location description contains the word Residential, use the following
URL:
/api/com.bmc.arsys.rx.foundation/location/site?queryExpression='locationDescription' like "%Residential%"&prop

ertySelection=locationName,locationDescription
In the example, locationDescription and locationName are site fields.

Related topics
Get site details by using site ID (see page 907)
Get person for site (see page 907)
Get organization details for a site by using site ID (see page 908)
Get site details by using site ID

The get sites by ID method enables you to fetch details of a site by using the site ID.
URL
Use the following URL for get sites by ID method:
/api/com.bmc.arsys.rx.foundation/location/site/<<Site Id>>?include=<<parentRegion Or allParentRegions>>
Parameters
The following table provides information about the parameters of the get sites by ID method:
Site Id Specifies a valid site ID. If an invalid or incorrect site ID is provided, a response code 500 is
/location/site
returned. Additionally, the following message is displayed:
/foundation_site_00001
[ERROR (302): Entry does not exist in database; com.bmc.
arsys.rx.foundation:Site:foundation_site_000011]
In the above message, foundation_site_000011 is an invalid site ID.
include Gets additional details of the site, such as parent region and all parent regions.
/location/site
/foundation_site_00001?
include=allParentRegion
Example
To get details of a site along with all the parent regions, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/site/foundation_site_00001?include=allParentRegion
In the example, foundation_site_00001 is a valid site ID.
Related topics
Get sites by search text (see page 906)
Get persons associated with a specific site by using site ID

The get person for site method enables you to fetch the persons associated with a specific site ID by using the site ID.

URL
Use the following URL for get person for site method:
/api/com.bmc.arsys.rx.foundation/location/site/<<Site Id>>/persons/?sitetype=<<primary Or secondary>>
Parameters
The following table provides information about the parameters of the get person for site method:
Site Id Specifies a valid site ID. If an invalid or incorrect site ID is provided, a response code
/location/site/foundation_site_00001
500 is returned. Additionally, the following message is displayed:
[ERROR (302): Entry does not exist in database; com.

bmc.arsys.rx.foundation:Site:foundation_site_000011]
sitetype Specifes the type of the site. If you do not specify this parameter, all the persons location/site/<<Site Id>>
associated with the site are fetched. /persons/?sitetype=<<primary Or
secondary>>
You can specify either of the following site types:
Primary: Returns all persons that have the specified site as their primary site.
Secondary: Returns all persons that have the specified site as their secondary
site.
Example
To get persons for a given site ID with the secondary site type, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/site/foundation_site_00001/persons?sitetype=secondary
Related topics
Get organization details for a site by using site ID

The get organizations for site method is used to fetch the organizations that are associated with a site by using the site
ID.
URL
Use the following URL for get organizations for site method:
/api/com.bmc.arsys.rx.foundation/location/site/<<Site Id>>/organizations

Parameter
The following table provides information about the parameters of the get organizations for site method:
Site Id Specifies a valid site ID. If an invalid or incorrect Site ID is provided, a response code 500 is returned.
/location/site/
foundation_site_00001
foundation:Site:foundation_site_000011]
In the above message, foundation_sitearea_000011 is an invalid site ID.
Example
To get all the organizations that are associated with a site, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/site/foundation_site_00001/organizations
Related topics
Get site area details by using site ID

The get site areas for site method is used to fetch the site areas that are associated with a site by using the site ID.
URL
Use the following URL for get site areas for site method:
/api/com.bmc.arsys.rx.foundation/location/site/<<Site Id>>/sitearea
Parameter
The following table provides information about the parameter of the get site areas for site method:
Site Id Specifies a valid site ID. If an invalid or incorrect site ID is provided, a response code 500 is returned.
/location/site
/foundation_site_00001
foundation:Site:foundation_site_000011]
Example
To get site areas for a given site ID, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/site/foundation_site_00001/sitearea

Related topics
Get site area details by using search criteria (see page 910)
Get site area details by using site area ID (see page 911)
Get site area details by using search criteria

The get site area by search text method enables you to fetch the details of all the site areas that match the search
criteria.
URL
Use the following URL for the get site area by search text method:
/api/com.bmc.arsys.rx.foundation/location/sitearea?pageSize=<<any valid number as pageSize>>

Parameters
The following table provides information about the parameters of the get site area by search text method:

/location/sitearea?pageSize=35
If you do not specify this parameter, the method fetches 50 records by default.
startIndex Specifies the first record's index of the page. The default start index is 0. /location/sitearea?
startIndex=50
propertySelection Specifies the list of comma-separated properties that should appear in the response /location/sitearea?
object. propertySelection=locationName
The propertySelection parameter accepts numeric fieldIds or string fieldNames or a

combination of both.
sortBy Specifies the list of comma-separated properties by which the data should get /region/rootcause?
sorted. sortBy=siteareaName
The sortBy parameter accepts numeric fieldIds or string fieldNames or a

combination of both. To indicate a descending sort, prefix the value with hyphen ( -).
queryExpression Specifies the search criteria to fetch the regions. /location/sitearea?

queryExpression='status' like
"Enabled"
Example
To get all site area names where the location description contains the word Pune, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/sitearea?propertySelection=locationName&queryExpression='locationDes
cription' like "%Pune%"
In the example, locationName and locationDescription are site area fields.

Related topics
Get site area details by using site ID (see page 909)
Get site area details by using site area ID (see page 911)
Get site area details by using site area ID

The get site area by ID method enables you to fetch details of a site area by using the site area ID.
URL
Use the following URL for get site area by ID method:
/api/com.bmc.arsys.rx.foundation/location/sitearea/<<SiteArea Id>>
Parameter
The following table provides information about the parameters of the get site area by ID method
SiteArea Specifies a valid site ID. If an invalid or incorrect SiteArea ID is provided, a response code 500 is returned.
/location/sitearea/
Id Additionally, the following message is displayed:
foundation_sitearea_00001
foundation:Site Area:foundation_sitearea_000011]
In the above message, foundation_sitearea_000011 is an invalid site area ID.
Example
To get the site area by searching with the site area ID, use the following URL:
/api/com.bmc.arsys.rx.foundation/location/sitearea/foundation_sitearea_00001
In the example, foundation_sitearea_00001 is a valid site area ID.
Related topics
Get site area details by using site ID (see page 909)
Get site area details by using search criteria (see page 910)
Using authorization REST APIs to consume BMC Remedy Single Sign-On

BMC Helix Innovation Suite supports OAuth 2.0 authentication provided by BMC Remedy Single Sign-On (BMC Remedy
SSO). For API-based client applications (such as data loading applications) or any other API clients that are integrated
with BMC Helix Innovation Suite, you can use the BMC Remedy SSO OAuth 2.0 authentication to interact with BMC Helix
Innovation Suite. For information about the BMC Remedy SSO OAuth 2.0, see Configuring OAuth 2.0 authentication in
the BMC Remedy Single Sign-On documentation.
After an application is configured to consume BMC Remedy SSO and when any REST API call occurs, the application
receives a token from the BMC Remedy SSO server and passes the token to BMC Helix Innovation Suite through the
HTTP header. BMC Helix Innovation Suite then uses the token to authenticate a user and allow the operations based on
the user's privileges.

For example, an API-based client generates report of open high priority tickets. The client fetches the high priority ticket
data from BMC Helix Innovation Suite by performing REST API GET calls on a particular incident management record
definition. While performing REST API calls, the client gets a token from the BMC Remedy SSO server and passes it to
BMC Helix Innovation Suite. BMC Helix Innovation Suite then validates the token and allows the client to get the high
priority ticket data.
To use BMC Remedy SSO OAuth 2.0 authentication in your application

You can use BMC Remedy SSO OAuth 2.0 authentication in your application only when BMC Remedy SSO is configured
for your applications.
1. Configure your application to get the OAuth 2.0 token from the BMC Remedy SSO server by using the following
REST API calls:
REST API call for authorization request:

Request Description
Request GET <authorizationURL>/oauth2/authorize

type <authorizationURL>is the URL to the BMC Remedy SSO server.
Request You must provide the following parameters in the request:

parameter
Response Type: CODE <default value, implicitly set>
Client ID: Client ID <clientID>

<clientID>must correspond to the client ID specified in the registeredclient table.
Redirect URI: Redirect URI <redirectURI>

<redirectURI> must correspond to the redirect URI specified in the registeredclient table.
Scope: Optional parameter
State: Optional parameter
Response Authorization Code

output The following sample shows a REST call:
REST API URL: http:// <localHostName> :8080/rsso/oauth2/authorize
Client ID: innovationsuite
Redirect URI: https://app.getpostman.com/oauth2/callback

The following response shows the sample REST call:
code=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.
eyJpYXQiOjE1MDcyNzUzMTgsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzI3NTQ5OC
wianRpIjoiMDJlMjAyMmItOTI2My00MDNhLThhNjMtNGQ2ZDQ4NWY4ODJjIiwic3ViIjoiYWRtaW4i
LCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImF1dGhvcml6YXRpb25Db2RlIn
REST API call for access token request:

Request Description
Request POST <authorizationURL>/oauth2/token

type
Request You must provide the following parameters in the request to get access token:
parameter
Grant Type: AUTHORIZATION CODE <default value. Implicitly set>

<clientID> must correspond to the client ID specified in the registeredclient table. You must specify the client ID that
is specified in the REST call for authorization request.

Request Description
Secret: secret <secretValue>

<secretValue> must correspond to the secret value specified in the registeredclient table.
Authorization Code: Specify the authorization code that is retrieved in the response of the REST API call for
authorization request.
Redirect URI: Redirect URI <redirectURI>

<redirectURI> must correspond to the redirect URI specified in the registeredclient table. You must specify the
redirect URI that is specified in the REST API call for authorization request.
You must provide the following parameters in the request to get new access token by providing a refresh token:
Grant Type: refresh_token

<clientID> must correspond to the client ID specified in the registeredclient table. You must specify the client ID that
is specified in the REST call for authorization request.
Secret: secret <secretValue>

<secretValue> must correspond to the secret value specified in the registeredclient table.
refreshToken: <refreshTokenValue>
Response Access token and refresh token

output The following sample shows the REST call:
REST API URL: http:// <localHostName> :8080/rsso/oauth2/token
Client ID: innovationsuite
Secret: secret3
Redirect URI: https://app.getpostman.com/oauth2/callback
The complete URL is as follows:
http://<localHostName>:8080/rsso/oauth2/token?
grant_type=authorization_code&client_id=innovationsuite&client_secret=secret3&code=e
yJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.
eyJpYXQiOjE1MDcyNzU3NDksImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzI3NTkyOSwianRp
IjoiYmQ0MTgwZTMtMzEzNy00ZjI3LWFmODUtODJkOGE1Y2YzODExIiwic3ViIjoiYWRtaW4iLCJyZWFsbSI6
IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImF1dGhvcml6YXRpb25Db2RlIn0.
o33KLHWsdmPZwCCnCuBFWeOZpgS153ATBqEXjE0lLDVMygAHXD8hf4Rc0QleI7bmSOrDnHYFjIZR2-
OlSwiDlCpwxAlCvD4AXAmrK3Nimt7py9fm_FvsDQ5NpMjy91uMhGBAug3VvZJagb9YfeSPfBEsU8UAp4hU85
qkR89Yn6gTKr4oQ2EV2PO__bglE36faSXKO7Wdes9jn96f-cYsebRzesdKzg-NpaTuKfOC70h4xVrFj-
ZLiVYVSJawuJf-Ws-
7g8s1gDYroSdExS55NaPi6Mtpfht1A8jZMo1_fywCCD9b7ydz5IPZNiVSBpCAcrEL1VHl2HKvqUwPVPVrZw&
redirect_uri=https%3A%2F%2Fwww.getpostman.com%2Foauth2%2Fcallback&
The following tokens are the sample REST call response:
access_token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.
eyJpYXQiOjE1MDcyMTY3NzYsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzIxNzM3Ni
wianRpIjoiYWQ5MDMyZTEtYTAxNC00MWU1LWE5ODctNDQyN2QyODM3NDM3Iiwic3ViIjoiYWRtaW4i
LCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImFjY2Vzc1Rva2VuIn0.VhL0ap-
HUiVQcXak3MMHlPN-
HYKQmpai3AkGSh3Du0qh7jwF13yliVnMPUlQBGz0HlFZRGX3blMSxneaKJLaj_aLN-
AMYMxPURNcy_LwPzTvp9pUyk0quN1iY7ZSjd5A2DNejVOBAXo_kSsmgDoW5_MXLih73d6XU-
8VOpsywqY8vNj56JgVE4eT1Z2r7s480OLIvwUDeJfZAbGrD567XsWYAvDaTD7Gy5ieK9lFCrIviCqk
jXDRqpDo-XolxClOvJe0pzM0gwKJfXx_9xqwq2i7GQ9nlegBHxkal1KHYLB8-
eRGIO1Wpqd3CwYhI96RzoBYw256thkjZNLV4RrjuQ

Request Description
refresh_token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.
eyJpYXQiOjE1MDcyMTY3NzYsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzIyMDM3Ni
wianRpIjoiMzQ4M2YwNTQtYTlhYi00NzIyLWJlYjAtZTliMDZlM2YwMzQ1Iiwic3ViIjoiYWRtaW4i
LCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6InJlZnJlc2hUb2tlbiJ9.
V_SCSd6KuWTOHj7274ry8Ndqs6B_g_EA0Qei9NEpxDMc0BJj2XvCzIZ6f4zdEwcaWVrbHCuslUwFrk
TIXFqL9TjGQ_10vJEqTqK1g0RBXj3W68Ex89noB46kB0Wm5_7tQ2H4WKFOJCpXyb6OP8O0fk0IuQ0z
Y56XVSQsKK6kAOEJy_xV25oOCaC_wvzyaVuZiWbWXNukWloRugys5KyruGyg9hf25shspD0eMLQZrx
APhjSneZTCeID_ofa83H6VO_EQTGVxiOQ0dhA7qw8Aziwr9bV_hy5W-
8U8VRdUcPaxgtezQqHKTV_NLsrHTkXt6w0v7rwIreg5ONM0nIaJAw
2. Configure your application to send the token received from the BMC Remedy SSO server to BMC Helix
Innovation Suite (through HTTP header) by using the following REST API call for access to resource request:
Request Description
Request GET <resourceServerURL>

type POST <resourceServerURL>
Request Authorization: Bearer <bearerValue>

header You must specify the access token that is retrieved in the REST call of access token request.
Response Access to a resource in the resource server in the form of JSON response.
output The following sample shows the REST call:
REST API URL: BMC Helix Innovation Suite Resource URL.

For example, http:// <localHostName> :8008/api/rx/application/record/recorddefinition/com.bmc.arsys.rx.foundation%3AAgent
Request header: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.

eyJpYXQiOjE1MDcyMTY3NzYsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzIxNzM3NiwianRpIjoiYWQ5MDMyZTEtYTAxNC00MWU1LWE5O
VhL0ap-HUiVQcXak3MMHlPN-HYKQmpai3AkGSh3Du0qh7jwF13yliVnMPUlQBGz0HlFZRGX3blMSxneaKJLaj_aLN-AMYMxPURNcy_LwPzTvp9pUyk0quN
8VOpsywqY8vNj56JgVE4eT1Z2r7s480OLIvwUDeJfZAbGrD567XsWYAvDaTD7Gy5ieK9lFCrIviCqkjXDRqpDo-XolxClOvJe0pzM0gwKJfXx_9xqwq2i7GQ9n
The following is a sample JSON response of the sample REST call:
{
"resourceType": "com.bmc.arsys.rx.services.record.domain.RegularRecordDefinition",
"version": "0",
"lastUpdateTime": "2017-08-29T11:48:40.000+0000",
"lastChangedBy": "ARSERVER",
"owner": "com.bmc.arsys.rx.foundation",
"name": "com.bmc.arsys.rx.foundation:Agent",
"tags": null,
"description": null,
"overlayGroupId": "0",
"developerId": "com.bmc.arsys",
"scope": "PUBLIC",
"guid": "6cf135d208bc89478be8d9cc8c2e65b3",
"fieldDefinitions": [
………..
………..
}
Related topic
Remedy Single Sign-On 9.1 in BMC Remedy Single Sign-On documentation.

Getting your Digital Service application ready for use

This section provides you information on packaging and testing your Digital Service application to make it available for
users.
Action Reference
Create a deployment package Deploying the custom code-based applications to development environments (see page 915)
Test the application Testing and debugging (see page 917)
Provide a deployment package with the correct version Releasing a version of your bundle (see page 965)
Localize the application definitions and data Localizing a Digital Service application (see page 968)
Create a smart library by using BMC Helix Innovation Suite Creating a smart library of reusable components (see page 972)
The following video (3:48) provides details on how to package the application for deployment.
https://youtu.be/2-DQ8l_Cy5Q
Deploying the custom code-based applications to development environments

BMC Helix Innovation Suite enables you to deploy the custom code-based applications to BMC Helix Innovation Studio.
After you customize an application, you must create a deployment package, that contains all definitions, data, and code
required by the application or library, and deploy the package to BMC Helix Innovation Suite. This capability enables you
to move application customization and data across environments quickly and easily.
Before you begin

Ensure that you create a deployment package (see page 915) of the custom code-based application, so that you can
deploy the custom application and data to development environments.
To create a deployment package

When you create a deployment package, the application definitions and data is exported from the BMC Helix Innovation
Suite server to a deployment package.
To create a deployment package, perform the following tasks:
1. On the command prompt, navigate to the application's parent project directory.

For example:
mvn install -Pexport
For example:
\projects\suggestion-box> mvn install -Pexport

The deployment package, that contains the project source code, is created as a ZIP file at the target directory of the
project. For example, \projects\suggestion-box\package\target\com.example.suggestion-box-1.0.0.SHAPSHOT.zip file. The
application definitions and data are exported to the ZIP file, which contains a db folder and all individual object definition
files. For example, \projects\<application name>\package\target\db folder. All individual object definition files are available
in the following folders:
association
configuration
named-list
process
record
rule
view
Note
When you export the definitions and data to a deployment package, if there is an existing db folder, the new db
folder overwrites the data of the existing db folder.
To deploy code-based applications

After you create deployment package for a custom code-based application or library, you can deploy the deployment
package to BMC Helix Innovation Suite.
To deploy a package to the same environment, perform the following tasks:
1. On the command prompt, navigate to the application's parent project directory.

For example:
For example:
The deployment package, that contains all definitions, data, and code required by an application or a library, is deployed
to BMC Helix Innovation Suite.

To undeploy code-based applications

On the command prompt, n avigate to the application parent directory and run the following command:
mvn com.bmc.arsys:rx-sdk-maven-plugin:undeploy -N
For example:
\projects\suggestion-box> mvn com.bmc.arsys:rx-sdk-maven-plugin:undeploy -N
Related topics
Releasing a version of your bundle (see page 965)
Testing and debugging (see page 917)
Undeploying a version of your application (see page 975)
Testing and debugging

To test the code of your application, you should must create a deployment package (see page 915) of your application. If
you make changes to the application code or data definitions, you should again deploy the package to the BMC Helix
Port for remote debug

The arserver.config file contains the jvm.option entry.
jvm.option.17=-agentlib:jdwp=transport=dt_socket,address=12444,server=y,suspend=n
This port is open for AWS development configurations that can be used for remote debugging.
Note
For JavaScript testing and debugging, you should use Grunt.

This section provides you the information about how to test your application logic, how to test your application UI, and
the available test methods.
Action Reference
Install and configure the automation framework so you can build and bundle automation tests that Testing application logic with the automation
test your application logic. framework (see page 918)
Understand the methods available in the automation framework. Automation framework methods (see page 927)
Understand the use of automation framework in a sample application, Task Manager. Example of using automation framework (see page 930
)
Understand changes made in the automation framework since its first release in BMC Helix Changes in the automation framework (see page 942)
Innovation Suite.

Action Reference
Install and configure the UI automation framework so you can build and bundle automation tests Testing the user interface with the UI automation
that test your application interface elements. framework (see page 945)
Understand the methods available in the UI automation framework. UI automation framework methods and sample code
(see page 954)
Understand changes made in the UI automation framework since its first release in BMC Helix Changes in UI automation framework (see page 963)
Innovation Suite.
Testing application logic with the automation framework

While developing a Digital Service application, you may want to know how your application logic works. You can test the
working of your application logic, by creating tests for your application. To create tests for your application, BMC Helix
Innovation Suite provides an automation framework.
The automation framework facilitates you to create the tests, run the tests, and view the test results. You can create test
cases to test your application logic such as business rules or process.
The process of using the automation framework to create tests comprises the following stages:
Before you begin
To install the automation framework (see page 918)
To access the automation Java project (see page 918)
To initially configure the automation Java project (see page 919)
To install the automation framework

BMC Helix Innovation Suite SDK consists of the automation framework JAR file that you can use to create automated
tests for your applications. When you install BMC Helix Innovation Suite SDK, the automation framework is installed
automatically and added to local the Maven repository. When you create an application using the Maven archetype and
BMC Helix Innovation Suite SDK, a Java project named automation is included in your application. This Maven project
contains Java automated test layout that you can modify to create tests.
To install the automation project in your existing applications or smart libraries, see Upgrading BMC Helix Innovation
Suite SDK to 18.11.01: Patch 01 (see page 27)
To access the automation Java project
The source code for the automation project is located at /automation/src/test/ folder. You can access the project by
using Eclipse.
1. In Eclipse, navigate to File > Import.
2. Select Maven > Existing Maven Projects and click Next.
3. Click Browse and select your project main folder and import the automation project, and click OK.

3.
To initially configure the automation Java project

The properties.config file in the automation folder contains the information to run your tests. Before running your first
test, you must provide the following information in the properties.config file.
1. Modify the name parameter and set it to your developer instance.
#ServerInfoList
#primaryServer
name=developerxxxx.innovate.bmc.com
rpc=0
tcp=0
dbadmin=
dbpassword=
jettyPort=0
protocol=https
overlayOption=
#End primaryServer
2. Modify the developer account credentials and set the username and password to the credentials that you use to
access your Amazon instance environment.
#userInfo
username=developer
password=developer
auth=
locale=en_US
#
3. Run the following script to check if the use cases that you defined are covered in your process, that is, to check
for the process coverage. The processes that are in the list of bundles defined in the bundles property are
analyzed and exported.
bundles=com.example.taskmanager-lib
ignoreProcessCoverage=false
By default:

The bundles is set to your current application or smart library. To add several bundles, use a comma ( ,) as
a separator.
The process coverage is executed at the end of all the use cases as the ignoreProcessCoverage property
is set to false.
Creating, running, and bundling test cases
To create a class from a record definition (see page 920)
To create automation tests (see page 922)
To run automation tests from the command line (see page 922)
To run automation tests from Eclipse (see page 923)
To review the automation test results (see page 925)
To review the process coverage test results (see page 925)
To bundle the automation test cases with application (see page 927)
To create a class from a record definition

In the Task Manager automation example project, the Task record definition exists and can be manipulated as a class,
extending the BaseRecordInstancebase class. This class bundles the get method and set method to access the fields as
well as enumerated types to modify the status values as shown in the following image:
To create this Java class through the Automation Framework utility, perform the following steps:
1. Open Windows command line and navigate to the application or library project available in /projects
/<projectName>/ folder.
2. Run the command mvn clean install in your project to generate all necessary libraries. Alternatively, you can run
the command mvn -Dit.test=* verify from your project automation folder, such as /projects/<projectName>
/automation/ folder.
3. Open a Windows command line in the /projects/<projectName>/automation/target/ target folder of the

automation project.
4.
4. Run the following command to generate a class for a record definition.
java -cp <class path> com.bmc.rx.test.framework.util.CreateRecordDefinitionSupportClass "developerxxxx

.innovate.bmc.com" "https" "<Jetty path>" "<user name>" "<password>" "<bundle name>" "<record
definition>" "<package name>" "<export path>"
For example:
java -cp com.example.taskmanager-lib-1.0-SNAPSHOT-automation-tests.jar;lib/*;%RX_SDK_HOME%/lib/*com.

bmc.rx.test.framework.util.CreateRecordDefinitionSupportClass "developerxxxx.innovate.bmc.com" "https"
"0" "developer" "password" "com.example.taskmanager-lib" "com.example.taskmanager-lib:dummy actions" "c
om.example.automation.test" "C:\\temp\\test\\"
This command includes the following parameters:

com.example.taskmanager-lib-1.0-SNAPSHOT- The class path must contain the following folder paths:
automation-tests.jar;lib/*;%RX_SDK_HOME%/lib/
Name of the JAR file in the automation project that contains the class required to create
a Java class, such as com.example.taskmanager-lib-1.0-SNAPSHOT-automation-tests.jar
Name of the /lib folder in the /target folder, such as lib/
Name of the SDK library folder, such as %RX_SDK_HOME%/lib/
developerxxxx.innovate.bmc.com Server host
https Protocol to access your BMC Helix Innovation Suite server
0 Jetty port of your BMC Helix Innovation Suite server. Enter the Jetty port value as 0.
developer User name to connect to the BMC Helix Innovation Suite server.
Important
BMC recommends that you use the tenant user account, instead of the developer
account, to test the runtime behaviour of applications.
password Password to connect to the BMC Helix Innovation Suite server.
com.example.taskmanager-lib Bundle name where your record definition is located
com.example.taskmanager-lib:dummy actions Record definition (with the bundle name) that you want to convert to a Java class
com.example.automation.test Package name that is used in the Java class
c:\temp\test\” is escaped so “c:\\temp\\test\\ Path to the folder where you want to place the Java class file, such as C:\\temp\\test\\
Enter the export path with two double slashes ("\\") because one slash is used as an escape
character.
The Java file is available in the specified folder location, as shown in the following image:

To create automation tests

The automation project consists of the following folders:
main This folder contains the MainAutomationClass.java file that you can use to execute all the test scripts in the automation project.
sample This folder contains AutomationSuite.java file that you can use as a master test script where you can define all your test cases. The AutomationSuite.
java file also contains sample test code.
This folder also contains the steps folder that consists of the following jGiven class templates:
AutomationSuiteGivenState—Contains the functions that act as test pre-conditions
AutomationSuiteWhenState—Contains the functions that act as actual test actions
AutomationSuiteThenState—Contains the functions that act as actual test verification
You can extend the BaseTest class to create your test cases. For information about the methods available in the
automation framework, see Automation framework methods (see page 927)
To run automation tests from the command line
You can verify all the test classes or verify a specific test class.
1. In a command prompt, navigate to to the automation folder.
2. Run the test cases by issuing one of the followings commands:

To Command
verify
All test mvn -Dit.test=* verify

classes For example,

To Command
verify
A mvn -Dit.test=className#methodName verifyFor example, mvn -Dit.

specific test=TaskManager#VerifyTaskManagerCanCreateTaskAndAssociateWithGroup verify
test
case
To run automation tests from Eclipse

The automation framework uses jGiven and testNG framework to allow you to create tests cases in Java. For more
information, see jGiven and testNG.
1. Install testNG Eclipse plugin.
2. In Eclipse, test all the methods and classes.

To test a method, select the method and debug it.
To test a class, run the complete class.
3. View the test results in the Results of running class tab.
If you encounter the following error:

"org.osgi.framework.BundleReference"'s signer information does not match signer information
of other classes in the same package site:icedtea.classpath.org
To resolve this error, in /automation/pom.xml file, delete the following code:
<dependency>
<groupId>org.eclipse</groupId>
<artifactId>osgi</artifactId>
<version>${equinox.framework.version}</version>
</dependency>

When you run testNG unit tests from Eclipse, you may receive an error that the class you are testing is not found.
For example, Class com.example.automation.AutomationSuite is not in the classpath. To resolve this
error, clean your automation project (Project > Clean).
To review the automation test results

When you run a test, a test report is created in the /automation/target/jgiven-reports/html/ folder. The following image
illustrates a sample test report:
To review the process coverage test results

After all the tests are run, a process coverage report is generated in HTML format as well as JSON format. You can
access the report, which is located in this folder /automation/AutoLog/. The following image illustrates a sample test
result:
A JSON file is created for every class, and contains statistics about the process and the activities that are executed, as
shown in the following image:

The graphical process coverage files are available in the following folders:
Each folder contains a HTML file and a Javascript file. To see the process coverage, you must open the file index.html in
Mozilla Firefox or Google Chrome browsers:
The HTML file contains all processes listed in bundles property from the properties.config file. Select a process to see
the process coverage. Activities highlighted in green denote that the activity is covered. Activities highlighted in red
denote that the activity was not reached or completed.

See the following image for more information:
To bundle the automation test cases with application

After you create your tests, you can bundle them with your application by using the following command in your project
folder:
mvn clean install
The ZIP bundle generated contains a JAR file that contains the tests, alongside your application or library.
Automation framework example

Example test cases are provided in the BMC Helix Innovation Suite SDK sample application, the Task Manager. See
Example of using automation framework (see page 930).
Related topics
Changes in the automation framework (see page 942)
Testing the user interface with the UI automation framework (see page 945)
Automation framework methods

The automation framework provides a comprehensive set of methods that ease your tasks while creating test cases for
your application. The following sections describe the different classes and methods provided by the automation
framework.
BaseTest class
The BaseTest class is located in the com.bmc.rx.test.framework package. You can e xtend the BaseTest class to create
your test cases. You can find the sample code for the BaseTest class in the Task Manager automation project. The Task
Manager automation sample project provided in the BMC Helix Innovation Suite SDK. For information about use of
automation framework in Task Manager application, see Example of using automation framework (see page 930).
For information about the methods available in the BaseTest class, see API documentation (see page 1003).
Note

To access the automation framework API Java documentation, download the

AutomationAPIJavaDocumentation file and unzip the contents of the Zip file and open the index.html file.
TestHelper class
The TestHelper class is located in the com.bmc.rx.test.framework.connection package. The TestHelper class provides the
following methods:
String dateToJsonDate(Date date) This method converts a Java date object

to a valid ISO 8601 formatted string.
Date date = new Date(); //04/07
The following is the string format: /2017 09:40:46 PDT
String stringDate = TestHelper.
"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" dateToJsonDate(date); //2017-07-
10T09:40:46.894Z
String createClassName(String name) This method converts a string to a Java

variable name.
String name = "Test 012#@";
String fixedName = TestHelper.
createClassName(name);//Test_012__
List<BaseRecordInstance> This method loads record instances

LoadRecordInstanceFromCSVFile(String fileName, from a CSV file.
Excel Example( first row is a
String className)
header with field names):
Creator,Status
Demo,New
Demo2,Assigned
List<BaseRecordInstance> records =
TestHelper.
LoadRecordInstanceFromCSVFile("test
.csv", "TaskRecordInstance");
TaskRecordInstance
teskRecordInstance = new
TaskRecordInstance(records.get(0));
server.createRecordInstance(
teskRecordInstance);
Hashtable<String, BaseRecordInstance> This method loads record instances

LoadRecordInstanceFromJSONFile(String fileName, from a JSON file.
JSON Example( 2 RECORDS):
String className)
[
{"name":"testRecord1","data":[{"nam
e":"Creator","value":"Demo"},{"name
":"Status","value":"New"}]},
{"name":"testRecord2","data":[{"nam
e":"Creator","value":"Demo2"},{"nam
e":"Status","value":"Assigned"}]}
]
Hashtable<String,
BaseRecordInstance> records =
TestHelper.
LoadRecordInstanceFromJSONFile("tes
t.txt",
"TaskRecordInstance");

Set<String> keys2 = records.

keySet();
for(String key2: keys2){
TaskRecordInstance
teskRecordInstance = new
TaskRecordInstance(records.get
(keys2));
server.createRecordInstance
( teskRecordInstance);
}
For more information about the methods available in the Testhelper class, see API documentation (see page 1003).
Note

TestServer class
The TestServer class is located in the com.bmc.rx.test.framework.connection package.
The following table describes the PostRequestwithAssoc method available in the TestServer class:
createRecordInstanceWithAssoc This method creates a record instance

(RecordInstance, assoc) and its associated record instances.
/* This method creates a record instance as well as
associated record Instances.
An example if provided in the Task Manager
automation project. */
<pre>
{@code
String groupGUID = findGroupGUIDByName
(groupName);
AssociateOperation ao = new
AssociateOperation();
ao.setAssociationDefinitionName("com.
example.taskmanager-lib:Task To Task Group Customers"
);
ao.setNodeSide(NodeSide.nodeB);
ArrayList<String> recordInstanceIds = n
ew ArrayList<String>();
recordInstanceIds.add(groupGUID);
ao.setRecordInstanceIds
(recordInstanceIds);
TaskRecordInstance task = new
TaskRecordInstance();
ArrayList<AssociateOperation> assoc = n
ew ArrayList<AssociateOperation>();
assoc.add(ao);
taskId = serverREST.
createRecordInstanceWithAssoc(TaskRecordInstance.
bundleName, task, assoc);
}
</pre>

@param entry (BaseRecordInstance)

BaseRecordInstance object to create {@link
BaseRecordInstance}. It will be automatically casted
to a RecordInstance object.
@param assocs (List AssociateOperation) List
of associated Record instances
@return (String) Record Request Instance
ID of the created Record Instance.
@throws RxServicesException Exception
@throws JSONException Exception
For information about the methods available in the TestServer class, see API documentation (see page 1003).
Note

Related topic
Testing application logic with the automation framework (see page 918)
Example of using automation framework

This topic describes the use of automation framework in a sample application, Task Manager. Task Manager is available
as a Digital Service application and a smart library in BMC Helix Innovation Suite SDK.
Goal Instruction
To understand the working of automation framework, installation, and Testing application logic with the automation framework (see page 918)
deployment
To install Task Manager Setting up Task Manager
To understand the Task Manager in detail Working with Task Manager
To access the Task Manager Java projects

Task Manager application and Task Manager library automation project examples are located in the automation project
(they contain the same code). The source code for the automation project is located at /automation/src/test/ folder. You
can access the project by using Eclipse.
1. In Eclipse, navigate to File > Import.
3. Click Browse, select the main project folder of Task Manager and import the project, and click OK.

Task Manager test cases

Task Manager consists of default dummy test cases which are located at com.example.automation and com.example.
automation.steps, in the class Automationsuite.
The Automationsuite class has the following test case structure where given, when, and then are called steps:
given()
.user_login(userName, userPassword);
when()
.user_creates_company(userCompany);
then()
.user_has_created_company(userCompany);
Each step consists of a class, AutomationsuiteGivenState, AutomationSuiteThenState, and AutomationWhenState. For

example, the given step user_login code is located in the class AutomationsuiteGivenState:
public AutomationSuiteGivenState user_login(@Hidden String userName, @Hidden String userPassword) throws

Exception {
// Login operation can be here.
return self();
}
The Task Manager bundle consists of eight test cases that you can use to test the application process. There are four
main test cases and four alternate versions of using the process methods to verify if a method has been reached or
completed. The test cases are located in the package com.example.taskmanagement.taskmanager. For more information
on Task Manager use case scenario, see Working with Task Manager.
The Task Manager bundle consists of the following main test cases:
VerifyTaskManagerCanCreateTaskAndAssociateWithGroup

The following code snippet illustrates the VerifyTaskManagerCanCreateTaskAndAssociateWithGroup test case:
given()
.task_manager_login(taskManagerName, taskManagerPassword);
when()
.task_manager_creates_task_related_to_$_group(groupName);
then()
.task_has_been_created();
Step Description
Given The given step of the test case calls a login step.
To generate a login object, the automation framework uses the UserInfo method located in the class TaskManagerGivenState.
To set the connection, the automation framework uses the connectToRESTServer method.
To login to the Amazon instance, the automation framework uses the AutoConfig object and the properties.config file, where you set up
information such as your Amazon instance URL.
To access the automation framework, the serverREST is the object is used. For example, to create a record instance.
Sample code:
UserInfo connectUser = new UserInfo(taskManagerName, taskManagerPassword);

(...)
serverREST = AutoConfig.connectToRESTServer(connectUser, AutoConfig.getTestServers().get(0));
(...)
serverREST.login();
When In this step, the Task Manager creates a Task and associates the Task to a Customer Group using the task_manager_creates_task_related_to_$_group
method. To create a Task record Instance and associates it to a Customer Group, the automation framework uses the following methods:
AssociateOperation—Declares an association object
setAssociationDefinitionName—Sets the association
setNodeSide
setRecordInstanceIds—Adds a list of the instance IDs to associate (here the GUID from the Customer Group)
add—Creates the association
Sample code:
uniqueTaskDescription = java.util.UUID.randomUUID().toString();
String groupGUID = findGroupGUIDByName(groupName);
AssociateOperation ao = new AssociateOperation();
ao.setAssociationDefinitionName("com.example.taskmanager-lib:Task To Task Group Customers");
ao.setNodeSide(NodeSide.nodeB);
ArrayList<String> recordInstanceIds = new ArrayList<String>();
recordInstanceIds.add(groupGUID);
ao.setRecordInstanceIds(recordInstanceIds);
ArrayList<AssociateOperation> assoc = new ArrayList<AssociateOperation>();
assoc.add(ao);
Then
To create a record instance of the Task record definition, the automation framework uses the TaskRecordInstance class.
Sample code:
TaskRecordInstance task = new TaskRecordInstance();

task.setRelation_Type(TaskRecordInstance.Relation_TypeOption.Parent);

Step Description
task.setTask_Manager(serverREST.getUserName());
task.setDescription(uniqueTaskDescription);
where,
TaskRecordInstance—is the main class.
setRelation_Type—sets the field TaskRecordInstance.Relation_Type to a value. This method calls BMC FieldInstance method to set a field to a
value.
public static final int Relation_Type = 10029003;

(...)
FieldInstance fieldInstance = new FieldInstance(TaskRecordInstance.Relation_Type, "" + value.id);
setTask_Manager and setDescription—sets the field value.
To create association between a task and a customer group, the automation framework uses the createRecordInstanceWithAssoc method
Sample code:
taskId = serverREST.createRecordInstanceWithAssoc(task, assoc);
VerifyTaskWillBeAutoAssigned
The following code snippet illustrates the VerifyTaskWillBeAutoAssigned test case:
given()
.task_manager_login(taskManagerName, taskManagerPassword)
.task_manager_knows_number_new_and_assigned_tasks();
when()
then()
.new_task_number_incremeted_by_1()
.and()
.waits_for_$_min(2)
.task_automatically_got_assigned()
.and()
.two_child_tasks_will_be_created()
.and()
.default_work_note_has_been_created()
.and()
.$_customers_were_related_to_task(2);
Step Description
Given This step calls a login step and checks the number of new tasks.
To generate a login object, the automation framework uses the UserInfo method located in the class TaskManagerGivenState.
To set the connection, the automation framework uses the connectToRESTServer method.
To login to the Amazon instance, the automation framework uses the AutoConfig object and the properties.config file, where you set up
information such as your Amazon instance URL.
To get the list of entries for a record definition, the automation framework uses the getRecordInstanceListJSON method.

Step Description
Sample code:
JSONArray searchResult = serverREST.getRecordInstanceListJSON(TaskRecordInstance.name,

TaskRecordInstance.bundleName, "379", "'10029003' = 0 AND '7' = 0", "", 0, 200);
When In this step, to create a Task and associate it to a Customer Group, the automation framework uses the
task_manager_creates_task_related_to_$_group method.
Then In this step, the following actions are performed:
The number of assigned tasks with new status is incremented by 1,
wait for two minutes,
check that the new task is at assigned status,
check that there are two tasks associated with the created Task,
check that a note is created,
check that two users are associated to the Task.
The automation framework uses the following methods:
getrecordInstanceListJSON
getRecordInstance—Gets a record Instance using the record definition name and the record instance ID.
serverREST.getRecordInstance(TaskRecordInstance.name, taskId);
TestHelper.waitMinuts—Wait function
TestHelper.waitMinuts(min);
getRecordInstanceListByParentJSON—Gets the list of record instances associated with a parent record, the Tasks associated with the main
Task (Request).
JSONArray searchResult = serverREST.getRecordInstanceListByParentJSON("com.example.

taskmanager-lib:Task To Task", TaskRecordInstance.bundleName,
TaskRecordInstance.RECORD_ID_FIELD_ID + "," + TaskRecordInstance.Status +
"," + TaskRecordInstance.Display_ID + "," + TaskRecordInstance.Description +
"," + TaskRecordInstance.Task_Type + "," + TaskRecordInstance.
RECORD_ID_FIELD_ID, taskId, NodeSide.nodeA, "", 0, 200);
VerifyChildTaskCanBeClosed
The following code snippet illustrates the VerifyChildTaskCanBeClosed test case:
given()
when()
.task_manager_creates_task_related_to_$_group(groupName)
.and()
.task_manager_set_$_status(TaskRecordInstance.StatusOption.Assigned);
then()
.waits_for_$_min(2)

.task_manager_can_close_all_child_tasks();
VerifyTaskCanBeClosed
The following code snippet illustrates the VerifyTaskCanBeClosed test case:
given()
when()
.and()
.task_manager_set_$_status(TaskRecordInstance.StatusOption.Assigned)
.waits_for_$_min(2)
then()
.waits_for_$_min(2)
.task_manager_checks_tasks_are_closed();
The Task Manager bundle consists of the following alternate test cases:
VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity
This test case is an alternate version of the VerifyTaskManagerCanCreateTaskAndAssociateWithGroup test case. The
following code snippet illustrates the VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity test case:
given()
.task_manager_add_processes_from_bundle_$("com.example.taskmanager-lib")
.task_manager_add_processes_from_bundle_$("com.example.taskmanager");
when()
then()
.activity_$_reached("Waiting Request to be assigned")
The following table shows the comparison between VerifyTaskManagerCanCreateTaskAndAssociateWithGroup and

VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity:
VerifyTaskManagerCanCreateTaskAndAssociateWithGroup VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity
(looking for activity name)
given() given()
.task_manager_login(taskManagerName, .task_manager_login(taskManagerName,
taskManagerPassword); taskManagerPassword)
when() .task_manager_add_processes_from_bundle_$("c
. om.example.taskmanager-lib")
task_manager_creates_task_related_to_$_group .task_manager_add_processes_from_bundle_$("c
(groupName); om.example.taskmanager");
then() when()
.task_has_been_created(); .
task_manager_creates_task_related_to_$_group
(groupName);
then()
.activity_$_reached("Waiting Request to be
assigned")

(looking for activity name)
Step Description
Given The given step of the test case calls a login step.
The automation framework is requested to load the processes from the bundles com.example.taskmanager-lib and com.example.taskmanager.
given()
(...)
.task_manager_add_processes_from_bundle_$("com.example.taskmanager");
In the given class we can see we call the method refreshProcessList from the Automation framework. This method is tied
to BaseTestGiven class from automation framework. The information is stored in the current class in a ProcessHelper
object, processClass. The object processClass will be used later on in the When and Then classes of the test.
@ProvidedScenarioState(resolution = Resolution.NAME)
ProcessHelper processClass;
(...)
this.refreshProcessList(initBundleName, false);
processClass = this.processHelper;
In our process, we want to be sure we reached the Activity Waiting Request to be assigned:
We do the check in the then step. This method will return true if the activity has been reached within the 5 minutes
timeout limit:
then()
In the function activity_$reached, the method waitForProcessPauseOnActivity is used from the ProcessHelper Object
(processClass) that was initialized in the Given step. This method has several parameters:
public boolean waitForProcessPauseOnActivity(TestServer server,

String bundleName,
String contextKey,
String owner,
ProcessStatus processStatus,

String processName,
String activityName)
throws com.bmc.arsys.rx.services.internal.RxServicesException,
org.json.JSONException,
ParseException
This method will stop at the given Process Activity name until the Activity is reached or the checks are in timeout in 5
minutes. The poll is done every second.
Parameters:
server - (TestServer) TestServer object used for the connection to your instance.
bundleName - (String) Bundle name containing your process.
contextKey - (String) Process context key (can be null).
owner - (String) Process owner (can be null)
processStatus - (ProcessStatus) ProcessStatus enum, it is strongly advised to define a value.
processName - (String) Process Name where is the Activity (with the bundle name)
activityName - (String) Activity label (name).
processClass.waitForProcessPauseOnActivity(serverREST, "com.example.taskmanager-lib", null, null,

ProcessStatus.ACTIVE, "com.example.taskmanager-lib:Main Request Process", activityName);
BMC recommends to always define a processStatus. Here, the value is ACTIVE.
VerifyTaskWillBeAutoAssignedWithGroupWatchActivity
This is an alternate test case version of the VerifyTaskWillBeAutoAssigned test case. The following code snippet
illustrates the VerifyTaskWillBeAutoAssignedWithGroupWatchActivity test case:
given()
.task_manager_add_processes_from_bundle_$("com.example.taskmanager")
when()
then()
.new_task_number_incremeted_by_1()
.activity_$_finished("Waiting Request to be assigned")
.task_automatically_got_assigned()
.and()
.two_child_tasks_will_be_created()
.and()
.and()
.$_customers_were_related_to_task(2)
.activity_$_has_been_executed("com.example.taskmanager-lib:Main Request Process", "Create Note")
.activity_$_reached("Waiting for Associated Tasks to be completed");
The following table shows the comparison between VerifyTaskManagerCanCreateTaskAndAssociateWithGroup and

VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity:

VerifyTaskManagerCanCreateTaskAndAssociateWithGroup (with wait) VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity

(Looking for Activity Name)
given() given()
.task_manager_login(taskManagerName, .task_manager_login(taskManagerName,
taskManagerPassword) taskManagerPassword)
. .task_manager_add_processes_from_bundle_$("co
task_manager_knows_number_new_and_assigned_tasks( m.example.taskmanager-lib")
); .task_manager_add_processes_from_bundle_$("co
when() m.example.taskmanager")
. .
task_manager_creates_task_related_to_$_group task_manager_knows_number_new_and_assigned_tasks();
(groupName); when()
then() .task_manager_creates_task_related_to_$_group
.new_task_number_incremeted_by_1() (groupName);
.and() then()
.waits_for_$_min(2) .activity_$_reached("Waiting Request to be
.task_automatically_got_assigned() assigned")
.and() .new_task_number_incremeted_by_1()
.two_child_tasks_will_be_created() .activity_$_finished("Waiting Request to be
.and() assigned")
.default_work_note_has_been_created() .task_automatically_got_assigned()
.and() .and()
.$_customers_were_related_to_task(2); .two_child_tasks_will_be_created()
.and()
.and()
.$_customers_were_related_to_task(2)
.activity_$_has_been_executed("com.example.
taskmanager-lib:Main Request Process", "Create Note")
.activity_$_reached("Waiting for Associated
Tasks to be completed");
There is a mapping between the wait and waiting for an activity to be completed, as shown in the following table:
VerifyTaskManagerCanCreateTaskAndAssociateWithGroup VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity (looking for activity name)

(with wait)
then() then()
. .activity_$_reached("Waiting Request to be assigned")
new_task_number_incremeted_by_1() .new_task_number_incremeted_by_1()
In this version, right activity is checked before performing the test:

VerifyTaskManagerCanCreateTaskAndAssociateWithGroup VerifyTaskManagerCanCreateTaskAndAssociateWithGroupWatchActivity (looking for activity name)

(with wait)
then() then()
.waits_for_$_min(2) .activity_$_finished("Waiting Request to be assigned")
. .task_automatically_got_assigned()
task_automatically_got_assigned() .and()
.and() .two_child_tasks_will_be_created()
. .and()
two_child_tasks_will_be_created() .default_work_note_has_been_created()
.and() .and()
. .$_customers_were_related_to_task(2)
default_work_note_has_been_created() .activity_$_has_been_executed("com.example.taskmanager-lib:Main Request Pr
.and() Note")
.activity_$_reached("Waiting for Associated Tasks to be completed");
.$_customers_were_related_to_task(2);
Here, it is checked that a note is created with the activity Create Note a nd that activity Waiting for Associated Tasks to
Reached is not used for the Create Note activity is because the process will never stop there.
You can then verify if the activity is reached.

Task Sample code
To see if an activity is executed, you can get the latest process

execution by using the getLatestProcessInstanceId method for a
.activity_$_has_been_executed("com.example.taskmanager-
specific bundle name and process name.
lib:Main Request Process", "Create Note")
(...)
String processInstanceId = serverREST.
getLatestProcessInstanceId(TaskRecordInstance.bundleName,
null, null, ProcessStatus.ACTIVE, processName);
To get the executed activity list for the process, you can use the
getListExecutedActivities method. List<String> activityList = processClass.

getListExecutedActivities(serverREST.getProcessInstance
(TaskRecordInstance.bundleName, processName,
processInstanceId));
To check if the activity is in the list, you can use the activityList.
if (!activityList.contains(activityName)) {
Assert.fail("Activity " + activityName + " has not
been executed in process " + processName);
}
To check if a process is completed, you can use the

waitForProcessToCompleteActivity method.
(...)
processClass.waitForProcessToCompleteActivity(serverREST,
"com.example.taskmanager-lib", null, null, ProcessStatus.
ACTIVE, "com.example.taskmanager-lib:Main Request Process"
, activityName);
VerifyChildTaskCanBeClosedWatchActivity
This is an alternate test case version of the VerifyChildTaskCanBeClosed test case.
given()
when()
.and()
.task_manager_set_$_status(TaskRecordInstance.StatusOption.Assigned);
then()
.activity_$_reached("Waiting for Associated Tasks to be completed")
.task_manager_can_close_all_child_tasks()
.activity_$_finished("Waiting for Associated Tasks to be completed");
VerifyTaskCanBeClosedWatchActivity

This is an alternate test case version of the VerifyTaskCanBeClosed test case.
given()
when()
.and()
.task_manager_set_$_status(TaskRecordInstance.StatusOption.Assigned)
.activity_$_reached("Waiting for Associated Tasks to be completed")
then()
.activity_$_finished("Waiting for Associated Tasks to be completed")
.task_manager_checks_tasks_are_closed();
To configure the Task Manager project

You must configure the Task Manager project so that you can run the test cases available for the Task Manager.
1. Configure the properties.config file. See Testing application logic with the automation framework (see page 918).
2. Configure the Task Manager to have one customer group that consists of two customers and define one
customer as the Task Manager.
3. Configure the Java project.
a. In all the test cases in the class TaskManager (package com.example.taskmanagement.taskmanager), enter
the credentials of the Task Manager user.
For example:
String taskManagerName = "agent01tm";

String taskManagerPassword = "password";
b. If required, enter the customer group name.

For example:
String groupName = "BMC Santa Clara";
To run a test case
1. Open Windows command line and in the taskmanager project, navigate to the automation folder.
mvn -Dit.test=className verify
For example:

To review the test results

When you run a test, a test report is created in the /automation/target/jgiven-reports/html/ folder.
The following image illustrates a sample test report:
Related topic
Changes in the automation framework

The automation framework has undergone the following changes since its first release in BMC Helix Innovation Suite.
Changes in BMC Helix Innovation Suite version 17.5.1

Configuration file changes were made in the automation framework provided in BMC Helix Innovation Suite version 17.5.1.
The following table provides information about the newly-added properties in the properties.config file. You must add
these properties in the properties.config file (if they were not added earlier).
Property name Description
timeout Sets the default timeout in seconds which is used by the wait methods.
timeout=10
poolingInterval Defines the pooling interval in seconds.
poolingInterval=2

This section provides information about the changes made in the automation framework since its first release in BMC
Helix Innovation Suite version 17.02. The following table lists the modifications added to the automation framework that
might break your code:

API call changes (see page 943)
Archetype and project structure changes (see page 944)
Configuration file changes (see page 944)
API call changes

Previously, the getList APIs in the automation framework would return the JSON objects only. From 17.02.02 onwards,
the getList APIs can return either JSON object or Hashmap objects. Additionally, a few API calls are renamed. The
following table provides information about the changes made in the APIs:
API available in IS17.02 API modifications in IS17.02.02
getListEntries Includes the following changes:
getListEntries method is renamed to getRecordInstanceList .- The method returns Hashmap objects

instead of a JSON list.
To retrieve a list of Hashmap objects, use the getRecordInstanceList API.
To continue to retrieve a list of JSON objects, use the getRecordInstanceListJSON API.
Contains two new parameters as follows:
Integer startIndex
Integer pageSize
The following is an example of code that must be modified:
Before upgrade to 17.02.02:
JSONArray searchResult = serverREST.getListEntries(TaskRecordInstance.

name,
TaskRecordInstance.bundleName, "379", "'10029003' = 0 AND '7' = 0", null
);
After upgrade to 17.02.02:
JSONArray searchResult = serverREST.getRecordInstanceListJSON

(TaskRecordInstance.name,
TaskRecordInstance.bundleName, "379", "'10029003' = 0 AND '7' = 0", null
, 0 , 200);
The following rows list the changes to the method and object names
Old method name New method name
createRecord createRecordInstance
createRecordWithAssoc createRecordInstanceWithAttachents
createRecordWithAttachents createRecordInstance
updateRecord updateRecordInstance
getView getViewDefinition
getRecord getRecordDefinition
Old object name New object name
com.bmc.rx.test.framework.connection. com.bmc.rx.test.framework.connection.TestServer
ARServerUserREST

Archetype and project structure changes

The following table provides information about the changes made in the archetypes and project structure:
Project/Class Modification in IS SDK 17.02.02
Added a main class and a testng.list file that is used to define the tests to be run on BMC Helix
Class name: com.example.automation.main.
MainAutomationClass
The main class is used to trigger the tests by using a command line on the server. A testng.list file is
File: /automation/src/test/java/com/example
required which lists the classes to the test.
/automation/main/MainAutomationClass.java
Configuration file: /automation/testng.list Added an XML file that lists the automation classes to execute at run time.
Notes:
If you run the tests manually by using the Maven command (mvn-Dit.test=* verify
), you are not required to use enter the details in the XML file.
The XML file is used only if you run the automation .jar files.
The following is the format of the automation classes:
<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >

<suite name="Tests" verbose="5">
<test name="Test1">
<classes>
<class name="com.example.automation.AutomationSuite"/>
<class name="com.example.taskmanagement.taskmanager.
TaskManager"/>
</classes>
</test>
</suite>
Configuration file changes

The following table provides information about the newly-added properties in the properties.config file:
bundles This is a newly added property, which lists the bundles, separated by a comma (,). The processes that are inside those bundles are
exported as part of the process coverage.
For example, all processes from those bundles would be exported as part as the process coverage as shown in the following code
snippet:
bundles=com.example.taskmanager,com.example.taskmanager-lib
ignoreProcessCoverage This is a newly added property, which notifies the automation framework that the process coverage must run at the end of your test
cases. By default, the process coverage is enabled as shown in the following code snippet:
ignoreProcessCoverage=false

During creation, debugging, or execution of the test cases, you can execute the test cases faster by disabling the process coverage
as shown in the following code snippet:
ignoreProcessCoverage=true
Related topic
Testing the user interface with the UI automation framework

After you develop an application, you can create tests to monitor the effectiveness of how your application UI works as
end users access it. To create UI tests for your application, BMC Helix Innovation Suite provides an UI automation
framework.
By using UI automation framework, you can create UI tests, run the tests, and view the test results. It simplifies tasks such
as finding UI elements, interacting with all the UI elements for adequate test coverage, and so on. You can bundle all your
UI tests with your application.
For example, you want to publish your application to Marketplace and BMC Cloud, but first you must submit the
application to BMC for validation and approval. After you use the automation framework to test the application logic, use
the UI automation framework to do the following tasks:
Simulate and test end-user interaction with the application.
Automate UI tests to find and interact with the UI elements.
Bundle the UI tests with the application.
Submit the test results with your application package.
For information about the automation framework, see Testing application logic with the automation framework (see
page 918).
The process of using the UI automation framework to create UI tests comprises the following stages:
UI automation framework capabilities

To assist you in automating test for the application user interface, the UI automation framework provides the following
capabilities:
Supports all UI elements based from BMC Helix Innovation Studio.
Automatically loads Java classes for application pages (view definitions) by using the Page class loader utility.
Enables behavior-driven development by using the JGiven framework, which distinguishes between test pre-
condition, test steps, and test verification steps using given(), when() and then() keywords respectively, and
makes the test script readable.

Provides reusable utility methods, such as login functions and logout functions.
You can use the following browsers to run the UI automation framework:
Mozilla Firefox 52.1.1 ESR
Google Chrome version 68 to 70
UI automation framework guidelines and limitations

You can use the UI automation framework only when the following criteria are met:
Application Under Test (AUT) of your application is developed by using BMC Helix Innovation Studio.
Application is in the run-time phase. UI test of an application during design phase is not supported.
You must consider the following points while using the UI automation framework:
For custom UI elements in your application, you need to provide the element classes to work with the custom
elements.
Page class loader utility only locates UI elements based from BMC Helix Innovation Suite only. It cannot identify
the custom elements in your application.
Before you begin
To install the UI automation framework (see page 946)
To access the UI automation Java project (see page 946)
To initially configure the UI automation Java project (see page 947)
To enable Mozilla Firefox 52.1.1 ESR to run the UI automation framework (see page 948)
To install the UI automation framework

BMC Helix Innovation Suite SDK consists of the UI automation framework that you can use to create automated tests for
your applications. After you install BMC Helix Innovation Suite SDK and create an application using the Maven archetype,
a Java project named ui-automation is included in your application. When you run the below Maven command from the
ui-automation project, UI automation framework is installed automatically and added to local the Maven repository. This
Maven project contains Java automated test layout that you can modify to create UI tests.
If you have created an application by using BMC Helix Innovation Suite SDK 18.11.01, perform the following step:
Execute the following command from the parent folder of you application project or /automation/ and /ui-automation/
project to run the pom.xml file.
mvn clean install
If you have created an application by using BMC Helix Innovation Suite SDK earlier than version 18.11.01, to install the UI
automation project, see Upgrading BMC Helix Innovation Suite SDK to 18.11.01: Patch 01 (see page 27).
To access the UI automation Java project
The sample source code of ui-automation project is located in the /ui-automation/src/test folder. You can access the
project by using an IDE such as Eclipse or IntelliJ IDEA.
1. In Eclipse, select File > Import.

3. Click Browse and import the pom.xml file of ui-automation project, and click OK.
To initially configure the UI automation Java project

Before you run the first UI automation test, configure the properties.config file in the ui-automation folder.
1. In the properties.config file, change the name parameter to the name of your developer instance.
#ServerInfoList
#primaryServer
name=developerxxxx.innovate.bmc.com
rpc=0
tcp=0
dbadmin=
dbpassword=
jettyPort=0
protocol=https
overlayOption=
#End primaryServer
2. Change the developer username and password to the credentials that you use to access your Amazon instance
environment.
#userInfo
username=developer
password=developer
auth=
locale=en_US
#
3. Set the browser parameter to the browser value that you want to use to run the UI test cases.
# Browser to run UI tests. May be "FF" (firefox), "GC" (Chrome) and so on

browser=FF
#default
timeout in seconds
timeout=10
#pooling interval in seconds
poolingInterval=2
4. Support for flexible driver executables is added, which enables users to use browser driver of any version. To use
it, download and copy the drivers in the folder called drivers under the UI-automation and define the driver
location in the properties.config file. Add the following property to the properties.config file:
# If you want to use drivers of your own choice, download them in the folder called drivers and define
the below property.
# If you do not want to use the drivers of your own choice, leave the driversLocation attribute as
blank.
# For example, driversLocation=drivers -> this will pick up drivers.exe from drivers folder under the
ui-automation.
# driversLocation= -> By default this is set to blank. It then picks up drivers bundled in the ui
framework jars. These drivers are tested.
driversLocation=

Note
This feature is available only for Chrome browser .
To enable Mozilla Firefox 52.1.1 ESR to run the UI automation framework
1. Download Mozilla Firefox 52.1.1 ESR and install it with the following options:
a. Select the Custom installation option.
b. Uncheck the Mozilla Maintenance Service check box.
2. Navigate to C:\Users\*username*\AppData\Local\Mozilla\update\ and delete the folder present at this location.
3. Set your permissions on the update folder to Write.
a. In the update folder, right click, and open Properties.
b. Select the Security tab, select the user (your username), and click Edit.
c. Click Write and save the changes.
4. Open the Mozilla Firefox browser and press Alt key.
5. In the menu, navigate to Tools > Options > Advanced > Update and select Never check for updates (not
recommended: security risk). (The Advanced tab is located in the left navigation.)
This disables the automatic and manual updates to Mozilla Firefox.
6. Restart Mozilla Firefox.
Creating, running, and bundling test cases
To create a page class from a view definition (see page 948)
To copy the page classes to the ui-automation project (see page 950)
To create automation tests (see page 950)
To run UI automation tests from the command line (see page 951)
To run UI automation tests from Eclipse (see page 951)
To review the UI automation test results (see page 952)
To bundle the UI automation test cases with application (see page 953)
To create a page class from a view definition

Each UI page in an application corresponds to a view definition in BMC Helix Innovation Suite context. Use the Page class
loader utility to automatically create a page class that includes the declaration for all of the view components (such as UI
elements, record editor, and so on) in the view definition. The Page class loader utility is available in the BMC Helix
Innovation Suite SDK.
1.
1. Navigate to /projects/<projectName> and run the following command:
mvn clean install
This command creates all the all necessary libraries in your project.
2. Navigate to /projects/<projectName>/automation/target/ and run the following command:
java -cp <class path> com.bmc.rx.test.framework.util.CreateViewDefinitionSupportClass "developerxxxx.

innovate.bmc.com" "https" "0" "<username>" "<password>" "<bundle name>" "<view definition name>" "<test
package name>" "<inFile name>" "<export path>"
Notes
You must run this utility on the BMC Helix Innovation Suite server where you developed your
application.
You must enter the administrator credentials to connect to the BMC Helix Innovation Suite
server.
As shown in the following example, replace the parameters with the appropriate values.
java -cp com.example.taskmanager-lib-1.0-SNAPSHOT-automation-tests.jar;lib/*;%RX_SDK_HOME%/lib/* com.

bmc.rx.test.framework.util.CreateViewDefinitionSupportClass "developerxxxx.innovate.bmc.com" "https" "0
" "developer" "password" "com.example.taskmanager-app" "com.example.taskmanager-app:dummy View" "com.
mycompany.app.pageclasses" "C:\\temp\types.csv" "C:\\temp\\test\\"
The class file is created and available in the mentioned folder. The following table describes the command
parameters:
class path The class path must contain the following folder paths:
Name of the JAR file in the automation project that contains the class required to create a Java class, such as
com.example.taskmanager-lib-1.0-SNAPSHOT-automation-tests.jar
Name of the /lib folder in the /target folder, such as lib/
Name of the SDK library folder, such as %RX_SDK_HOME%/lib/
BMC Helix Server host

Innovation Suite
server
protocol Protocol to access your BMC Helix Innovation Suite server
Jetty port Jetty port of your BMC Helix Innovation Suite server. Enter the Jetty port value as 0.
username User name to connect to the BMC Helix Innovation Suite server.
Important

BMC recommends that you use the tenant user account, instead of the developer account, to test the
runtime behaviour of applications.
password Password to connect to the BMC Helix Innovation Suite server.
bundle name Bundle name where your view definition is located.
view definition View definition that you want to convert to a Java class.
name Note: If you pass this parameter value as a blank value, the Page class loader utility loads the page classes for all the
view definitions.
test package name Package name in which the classes created by the Page class loader utility are stored.
For example, if you provide the test package name as com.mycompany.app.pageclasses, the
classes created by the Page class loader utility contain the following declaration in the class code:
package com.mycompany.app.pageclasses;
inFile name inFile name that is used to load the custom element
Note: The inFile name parameter is not implemented in BMC Helix Innovation Suite. You must provide the value C:
\\temp\types.csv.
export path Path to the folder where you want to place the Java class file, such as C:\\temp\\test\\
Enter the export path with two double slashes ("\\") because one slash is used as an escape character.
To copy the page classes to the ui-automation project

After you create the page classes for a view definition by using the Page class utility, you must copy the page classes to
the ui-automation project.
1. By using an IDE such as Eclipse or IntelliJ IDEA, open the ui-automation project.
2. Create a package structure same as the test package name that you provide when you run the Page class loader
utility.
For example, if you provide the test package name value as com.mycompany.app.pageclasses, you must create the
pageclasses folder in the com.mycompany.app folder.
3. Copy all the view classes and the Record Editor classes created by the Page class loader utility in the test package
(for example, com.mycompany.app.pageclasses).
4. After you copy the classes, you may encounter some compilation errors. Fix the errors by using the following
workarounds:
UI elements with same label are loaded with the same variable names in the generated class. This results
to Java errors. In this case, you must rename the duplicate variable names in the Java classes.
Even if your view definition does not consist of a record editor, the Page class loader utility introduces an
import statement in the view class to point to non-existent folder. You must comment such import
statements.
To create automation tests

After you copy the page classes to the ui-automation project, you can start creating the test cases for your application.

The ui-automation project consists of the following folders:
Folder Description
main This folder contains the MainUIAutomationClass.java file that you can use to execute all the test scripts in the ui-automation project.
sample This folder contains UIAutomationSuite.java file that you can use as a master test script where you can define all your test cases. The
UIAutomationSuite.java file also contains sample test code.
This folder also contains the steps folder that consists of the following jGiven class templates:
TestUIGivenState—Contains the functions that act as test pre-conditions
TestUIWhenState—Contains the functions that act as actual test actions
TestUIThenState—Contains the functions that act as actual test verification
For information about implementation of sample test scripts, see Get started with UI automation framework and run a
sample script (see page 953).
For information about the UI automation framework methods, see UI automation framework methods and sample code
(see page 954).
Tip
Extend the test class from the UIBaseTest class. The UIBaseTest class contains initialization and reusable
functions such as login, logout, openApplication, and so on.
To run UI automation tests from the command line

You can verify all the test classes or verify a specific test class.
1. In a command prompt, navigate to to the ui-automation folder.
2. Run the test cases by issuing one of the followings commands:

To verify Command
All test classes mvn -Dit.test=* verify
A specific test mvn -Dit.test=<className>#<methodName> verify

case For example,
mvn -Dit.test=TaskManager#VerifyTaskManagerCanCreateTaskAndAssociateWithGroup
verify
To run UI automation tests from Eclipse

To create tests cases in Java, the UI automation framework utilizes the jGiven framework and the testNG framework. For
more information, see jGiven and testNG.
1. Install testNG Eclipse plugin .
2. In Eclipse, test all the methods and classes.
To test a method, select the method and debug it.

To test a class, run the complete class.
3. View the test results in the Results of running class tab.

The following image illustrates a sample test result:
To review the UI automation test results

When you run a test, a test report is created in the /ui-automation/target/jgiven-reports/html/ folder.
The following image illustrates a sample test report:

To bundle the UI automation test cases with application

After you create your UI test cases, you can bundle them with your application. To create the application bundle, run the
the following command from your project folder:
mvn clean install
A ZIP file is generated that contains a JAR file of the test cases and your application.
End-to-end example of using the UI automation framework

The following steps describe the use of UI automation framework in a sample application, Task Manager. Task Manager is
available as a Digital Service application and a smart library in BMC Helix Innovation Suite SDK.
Step Action Video
1 Install BMC Helix Innovation Suite SDK and create a sample The following video describes how to install BMC Helix Innovation Suite SDK
application. and create a sample application:
https://youtu.be/gmk9TWHDC_E
2 Get started with UI automation framework and run a sample script. The following video describes how to get started with UI automation
framework:
https://youtu.be/wNsE9Vyk6-4
3 Use the Page class loader utility. The following video describes how to use the Page class loader utility:
https://youtu.be/useIfB2k6UY
4 Use the JGiven framework. The following video describes how to use the JGiven framework:
https://youtu.be/4dPkFRR_Fdk
5 Copy the page classes, write test script for BMC Helix Innovation The following video demonstrates the how to write test script BMC Helix
Studio based UI elements and custom UI elements. Innovation Studio based UI elements and custom UI elements:
https://youtu.be/5qiTgvfPAjg
The following video demonstrates the UI automation code overview:
https://youtu.be/VhmeF21oV-4
For more information on the tools, see JGiven in JGiven documentation and Selenium in Selenium documentation.
Related topics
Changes in UI automation framework (see page 963)

UI automation framework methods and sample code

The UI automation framework provides a comprehensive set of methods for testing BMC Helix Innovation Suite based UI
elements and custom UI elements.
The following sections describe how to use several of the UI element methods that are provided by the UI automation
framework.
Consider a sampleView view definition that contains BMC Helix Innovation Suite UI elements such as Record Editor (
sampleEditor), Record Grid (sampleGrid), and so on. After you use the Page class loader utility to create the page classes
for the sampleView view definition, you can use the UI element methods provided by the UI automation framework to
create test cases. The UI element classes are located in the com.bmc.rx.test.framework.elements package.
UI automation sample: Initializing a view definition

The UI automation framework uses JGiven, which provides the stage classes such as TestUIGivenState, TestUIWhenState,
TestUIThenState, and so on.
The following code illustrates how to initialize the example view definition (sampleView):
sampleView myView = new sampleView (driver, errorHandler)
The driver and errorHandler are initialized in the Baseclasses such as BaseUITestGiven, BaseUITestWhen, and
BaseUITestThen.
UI automation sample: Testing a record editor element

Use the Record Editor (sampleEditor) examples to test the UI elements in the following table. The following table
contains the available classes and example code:
UI element UI element class Action Example
Attachment AttachmentField Uploads a file
File resume = new File("C:\\temp\text.

txt");
myView.sampleEditor.Attachment().setData
(resume);
Gets the file name of the file that is uploaded
myView.sampleEditor.Attachment().
getData();
Boolean BooleanField Sets the value of a Boolean field to true
myView.sampleEditor.boolean().setData("Tr
ue");
Sets the value of a Boolean field to false
myView.sampleEditor.boolean().setData("Fa
lse");
Gets a Boolean field value

myView.sampleEditor.boolean().getData();
Button ButtonField Clicks a button
myView.Save().click();
Date DateField Sets data for a Date field and pass the data in the string
format, "YYYY-MM-DD"
myView.sampleEditor.Date().setData("2017-
10-30");
DateTime DateTimeField Sets a Date field and pass the data in the string format
YYYY-MM-DD
myView.sampleEditor.DateTime().setData("2
017-10-30,01:05:AM");
Time TimeField Sets data for a Time field and pass the data in the string
format, "HH:MM:AM"
myView.sampleEditor.Time().setData("01:
05:AM");
Drop down DropDownField Selects the DropDown field
(single myView.sampleEditor.DropDownField().
selection) setData("Monday");
Drop down MultiSelectField Sets multiple values
(Multi- List<String> countries = Arrays.asList("P

select ) AK", "BAN", "AUS");
myView.sampleEditor.
MultiSelectDropDownField().setData
(countries);
Decimal, DecimalField, Provides a value to a Decimal field

Floating FloatingField
myView.sampleEditor.DecimalField().
setData("3.14");
Integer IntegerField Provides a value to an Integer field
myView.sampleEditor.IntegerField().
setData("10");
TextArea, TextAreaField, Provides a value to a TextArea field

Text TextField
myView.sampleEditor.TextAreaField().
setData("Hello World.");

UI automation sample: Testing a record grid

Use the following examples to test the record grid UI element:
Record RecordGridField Gets all of the values from a specific column

Grid
myView.RecordGridField().getAllValuesFromColumn("D
escription")
Selects a specific row
myView.RecordGridField().
selectRowByUniqueColumnValue("Month","February");
Applies a filter
List<String> monthsToBeSelected = Arrays.asList("J

anuary", "November");
myView.RecordGridField()
.openFilter()
.selectCheckBoxes(monthsToBeSelected,"Month"
)
.applyFilter();
UI automation sample: Testing the Approval Console

Use the ApprovalConsole class methods to test the Approval Console interface. The following table contains the available
methods and examples:
clickOnTab(String) Selects a tab in the

approve console such
myView.testApproveConsoleElement().clickOnTab("Pen
as Pending, On Hold,
ding");
and so on.
getRequestCount() Provides the row

count.
myView.testApproveConsoleElement().clickOnTab("Pen
ding");
int pendingCount =
sampleUIPage.testApproveConsoleElement().
getRequestCount();
selectMoreViewOptions(String) Selects the More Views

tab in the Approval
myView.testApproveConsoleElement().
Console.
selectMoreViewOptions("Approved");
selectRecordDefinitionByIndex(intValue) Selects a grid row

based on the index
specified.
selectRecordDefinitionByIndex(1);

deselectRecordDefinitionByIndex(intValue) Deselects a grid row

based on the index
specified.
deselectRecordDefinitionByIndex(1);
selectRecordDefinitionBasedOnUniqueCellValue Selects a record

(columnName, Value) definition based on the
column value specified.
selectRecordDefinitionBasedOnUniqueCellValue
("RecordDefinition","com.bmc.example.apr-assig-
config-test:TestRecord_Console3520");
deselectRecordDefinitionBasedOnUniqueCellValue Deselects a record

(columnName, Value) definition based on the
column value specified.
deselectRecordDefinitionBasedOnUniqueCellValue
("RecordDefinition","com.bmc.example.apr-assig-
config-test:TestRecord_Console3520");
clickRefresh() Refreshes record grid.
myView.testApproveConsoleElement().clickRefresh();
performAction(String) Clicks an action in the

Approve Console such
as Approve, Reject, and
selectRecordDefinitionByIndex(1);
Hold.
myView.testApproveConsoleElement().performAction("
Approve");
clickOkButton() Clicks the OK button in

a dialog box.
myView.testApproveConsoleElement().performAction("
Approve");
myView.clickOkButton();
initiateReassignDialogAndAssign(userName) Clicks the Reassign

button in a task and
assigns the task to the
initiateReassignDialogAndAssign("admin_ta");
specified user.
openVisibleColumnsDropDown() Opens the Visible

Column list to add or
remove a column in
openVisibleColumnsDropDown();
the record grid.
selectCheckBoxInVisibleColumnsMenuByText Selects the specified

(String) string in the Visible
Column menu.
selectCheckBoxInVisibleColumnsMenuByText
("Justification");

deselectCheckBoxInVisibleColumnsMenuByText Deselects the specified

(String) string in the Visible
Column menu.
deselectCheckBoxInVisibleColumnsMenuByText
("Justification");
closeVisibleColumnsDropDown() Closes the Visible

Column list.
closeVisibleColumnsDropDown();
initiateQuestionDialogAndAddQuestion(UserName, Clicks the New button

Question) in the Questions tab
myView.testApproveConsoleElement().clickOnTab("Que
and adds a question.
stions");
initiateQuestionDialogAndAddQuestion
("admin_ta","reason for this request");
initiateAndEnterCommentsDialog(userName) Clicks the New button

in the Comments tab
myView.testApproveConsoleElement().clickOnTab("Com
and adds a comment.
ments");
initiateAndEnterCommentsDialog("test");
getRequestFieldValues() Provides the list of

request field values in a
List<String> list = myView.
request.
testApproveConsoleElement().
getRequestFieldValues();
getRequestFieldNames() Provides the list of

request field names in
List<String> list1 = myView.
a request.
testApproveConsoleElement().
getRequestFieldNames();
setSearchText(String) Searches record

instances based on the
myView.testApproveConsoleElement().setSearchText("
search text.
com.bmc.example.apr-assig-config-test:
TestRecord_Console9118");
UI automation sample: Testing the BMC Modern Shell

Use the following example to test the BMC Modern Shell:
Navigation ApplicationGlobalHeader Works with the application global header that is the navigation
bar bar

sampleView myView = new

sampleView (driver,
errorHandler)
myView.header().
clickSubMenuItem("Consoles","
Task Manager Console");
myView.header().clickMenuItem
("SomeMenuItem");
UI automation sample: Testing an application configuration or setting

Use the following methods to test your application configurations or settings. These methods are available in the Base
class.
openApplicationConfiguration() Navigates to a particular application

configuration (or setting).
myView.openApplicationConfiguration();
filterSettings(String) Filters the setting component based

on the search string.
myView.openApplicationConfiguration().filterSettings("F
irst Component");
clearSettingsFilter() Clears the search text.
myView.openApplicationConfiguration().
clearSettingsFilter();
selectConfigurationNode Selects a configuration node from For example, the result of the following code automates the menu sequence is
(ArrayList Obj) the ArrayList object. Configure My Sever > People > Manage User Accounts.
ArrayList<String> filterPath = new ArrayList<String>();

filterPath.add("Configure My Server");
filterPath.add("People");
filterPath.add("Manage User Accounts");
myView.openApplicationConfiguration().
selectConfigurationNode(filterPath);
UI automation sample: Calling a wait method

While creating the UI test cases, you might need to call wait methods. The UI automation framework provides the wait
methods shown in the following sample code:
sampleView myView = new sampleView (driver, errorHandler)
myView.waitForExecutionComplete();
myView.waitForAllErrorMessagesToDisappear();
myView.waitForAllSpinnersToHide();
myView.waitForInfoMessagesToDisappear();
myView.waitForSuccessfulMessagesToDisappear();

UI automation sample: Testing custom UI elements

Using the UI framework, you can also create custom test classes for your custom UI elements. Custom UI elements can
be data fields (such as a text field) and control fields (such as a button). BMC recommends that you extend the
RXControlField abstract class and RXDataField abstract class to create your custom UI elements classes. The
RXControlField class and the RXDataField class are located in the com.bmc.rx.test.framework.elements package.
The following sample code illustrates how to test a custom control field:
package com.bmc.rx.test.framework.elements;
import com.bmc.rx.test.framework.listener.ErrorListener;
import com.bmc.rx.test.framework.utils.web.AngularJs;
import org.openqa.selenium.By;
import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.Rectangle;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebDriverException;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.interactions.Actions;
//This is the sample code snippet for the Custom Control field
public class CustomControlField extends RXControlField {
//Unique Locator for the Custom field

private static String cssButtonField = "[rx-view-component-id='%s'] button";
public CustomControlField(WebDriver drv,String guid,ErrorListener listener){

actualcssTag = String.format(cssButtonField, guid);
driver = drv;
addListener(listener);
}
/**
* This method is used to click on the getWebElement()
*/
@Override
public void click() {
getWebElement().click();
AngularJs.waitForAngularRequestsToFinish(driver);
}
/**
* This method is used to see if getWebElement() is enabled or not
*/
public boolean isEnabled() {
//Implement as per the Custom element's behavior
return true;
}
/**
* This method will be used to see if getWebElement() is visible or not.
*/
@Override
public boolean isVisible() {
//Implement as per the Custom element's behavior
return true;
}
@Override
public WebElement apply(WebDriver input) {
WebElement resultCountElement = null;
if(driver.findElements(By.cssSelector(actualcssTag)).size() > 0){

resultCountElement = driver.findElement(By.cssSelector(actualcssTag));
}
return resultCountElement;
}
}
The following sample code illustrates how to test a custom data field:
package com.bmc.rx.test.framework.elements;
import java.util.NoSuchElementException;
import org.jetbrains.annotations.Nullable;
import org.openqa.selenium.By;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.Rectangle;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebDriverException;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.interactions.Actions;
import org.openqa.selenium.support.FindBy;
import com.bmc.rx.test.framework.listener.ErrorListener;
/**
* This is a sample code snippet for Custom Data Field
*/
public class CustomDataField extends RXDataField {
private static String cssBooleanField = "[rx-view-component-id='%s']";
private String sBoolean = "rx-boolean";
String sFieldName = "span";
String sTrueButton = ".d-icon-check";
String sFalseButton = ".d-icon-circle_slash_o";
/**
* This constructor will be used for initialising the instance of this class.
*/
public CustomDataField(WebDriver drv,String guid,ErrorListener listener){
actualcssTag = String.format(cssBooleanField, guid);
driver = drv;
addListener(listener);
}
/**
* This method is used to see if element is enabled or not
*/
@Override
public boolean isEnabled() {
//Write the implentation as per the requirement
return true;
}
/*
* If Data can be passed as 'True' or 'False'
*/
@Override
public void setData(Object data){
}
/**
* This method will be used for getting the selected state of the Boolean Field.
* If the boolean field is set to True, then this method will return true. Else false will be returned
*
*/
@Override
public Boolean getData(){
return true;
}
/**
* This method is used to set the focus on the element

*/
@Override
public void setFieldFocus(){
new Actions(driver).moveToElement(getWebElement()).perform();
}
/**
* This method will be used for clearing / deselecting whatever was selected in the boolean field.
*/
@Override
public void clear(){
getWebElement().findElement(By.cssSelector(sBoolean)).clear();
}
/**
* This method will be used for getting the label of the element
*/
@Override
public String getLabel(){
try {
List<WebElement> labels = getWebElement().findElements(By.tagName("label"));
if (labels.size() == 1) {
return labels.get(0).getText();
}
}catch (Exception e){
return null;
}
return null;
}
private boolean isButtonChecked(WebElement button) {
return button.getAttribute("class").contains("is-checked");
}
/**
* This method will be used to see, if element is visible or not.
*/
@Override
public boolean isVisible() {
if (getWebElement().isDisplayed()){
return true;
}else {return false;}
}
/**
* This method will be used to see, if element is readOnly or not.
*/
@Override
public boolean isReadOnly() {
return true;
}
@Override
public WebElement apply(WebDriver input) {
WebElement resultCountElement = null;
if(driver.findElements(By.cssSelector(actualcssTag)).size() > 0){
resultCountElement = driver.findElement(By.cssSelector(actualcssTag));
}
return resultCountElement;
}
}
For more information about all the methods available in the various elements classes ( com.bmc.rx.test.framework.
elements), see UIFrameworkAPIJavaDocumentation.
Note

To access the UI framework API Java documentation, download the UIFrameworkAPIJavaDocumentation file,
extract the contents of the zip file, and open the index.html file.
Related topics
Changes in UI automation framework (see page 963)
Changes in UI automation framework

The UI automation framework has undergone the following changes since its first release in BMC Helix Innovation Suite.

The UI automation framework available in BMC Helix Innovation Suite version 18.11.01 con tains the following
enhancements:
Chrome driver is updated to version 2.42 is added so that the UI automation framework supports Google Chrome
versions 68-70.
Support for flexible driver executables is added, which enables users to use browser driver of any version. To use
it, download and copy the drivers in the folder called drivers under the UI-automation and define the driver
location in the properties.config file.

Added the following new property to the properties.config file:
# If you want to use drivers of your own choice, download them in the folder called drivers and define the
below property.
# If you do not want to use the drivers of your own choice, leave the driversLocation attribute as blank.
# For example, driversLocation=drivers -> this will pick up drivers.exe from drivers folder under the ui-
automation.
# driversLocation= -> By default this is set to blank. It then picks up drivers bundled in the ui framework
jars. These drivers are tested.
driversLocation=
Note
This feature is available only for Chrome browser .
Changes in BMC Helix Innovation Suite version 18.05

The UI automation framework available in BMC Helix Innovation Suite version 18.05 contains the following
enhancements:
Selenium is upgraded from version 3.4.0 to version 3.7.1.
Google Chrome driver is updated to version 2.38 so that the UI automation framework supports Google Chrome
versions 65 to 67.

The UI automation framework available in BMC Helix Innovation Suite version 18.02 contains the following enhancement:

UI framework now supports Chrome 64 version.

The UI automation framework available in BMC Helix Innovation Suite version 17.11 contains the following enhancements:
Support for Approval Console UI elements

A separate ApproveConsole element class is available to work with the Approval Console UI.
Utility methods that work with an application configuration (or setting)
Login enabled for Remedy Single Sign-On (RSSO)

The following changes were made in the UI automation framework available in BMC Helix Innovation Suite version 17.8.0:
Selenium is upgraded from version 3.0.1. to version 3.4.0.
UI framework now supports Mozilla Firefox 52.1.1 ESR version.

The following changes were made in the UI automation framework provided in BMC Helix Innovation Suite version 17.5.1:
API changes
Java class generation for view definition by using the Page class loader utility is enhanced for capturing the
screenshots in the event of an error. Ensure that you reload the page classes by using the Page class loader utility
(see page ).
Different wait related methods are introduced in the BasePage class.
For all the UI elements supported by BMC Helix Innovation Studio, isVisible(), isReadOnly(), isEnabled()
methods are added. Several methods are renamed to have uniform setData()and getData() methods.

The following table provides information about the properties added to the properties.config file:
timeout Sets the default timeout in seconds which is used by the wait methods.
timeout=10
poolingInterval Defines the pooling interval in seconds.
poolingInterval=2
Related topic

Releasing a version of your bundle

When you create a Digital Service application project using the Maven archetype, your application is created with bundle
version 1.0-SNAPSHOT and you do the development work with same version. You may need to release this bundle and
start the development work on a new version. For example, you want users to start using your application version 1.0 and
you need to start with the development of your application 1.1.
To release an initial version

The following image shows the process to release the initial version of an application:
Exporting bundle
Ensure that your definitions are up to date and run the following command to export your bundle:
projects\my-proj> mvn generate-resources -Pexport
Stopping bundle version 1.0 development

If you are using any sources in Source Control, branch or label your sources. Ensure that you do not modify definitions
for version 1.0. Remove the bundle from your BMC Helix Innovation Suite development instance, using the following
command:
projects\my-proj> mvn com.bmc.arsys:rx-sdk-maven-plugin:undeploy -N
Note that this is a required step.
Changing bundle to a released version
Note

If you have created or upgraded your application using BMC Helix Innovation Suite SDK release 17.08 or earlier,
edit the /package/pom.xml file and update the <execution> tag to make the following changes:
<build>
<plugins>
<plugin>
.
.
<executions>
<execution>
<id>update-def-file</id>
<phase>generate-sources</phase>
<goals>
<goal>update-def-file</goal>
</goals>
</execution>
<execution>
<id>add-manifest</id>
<phase>generate-resources</phase>
<goals>
<goal>add-manifest</goal>
</goals>
</execution>
.
.
.
</executions>
</plugin>
Update your POM files using the following command:
projects\my-proj> mvn versions:set -DnewVersion=1.0.0
After you run the command, you receive a success message. The following snippet illustrates a sample message:
[INFO] Updating project com.myco:my-proj

[INFO] from version 1.0-SNAPSHOT to 1.0.0
expression: rx-sdk.groupId no value
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] my-proj-all ....................................... SUCCESS [ 54.270 s]
[INFO] My Project ........................................ SKIPPED
[INFO] my-proj-package ................................... SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
The version is created in the following format:
For example, 17.11.0, 17.11.0-SNAPSHOT, 1.0-SNAPSHOT, 1.0.0.RELEASE.

Packaging
Ensure that all the sources, and the renamed definition files, are correctly packaged together in the deployment zip file.
Run the following command:
projects\my-proj> mvn clean install
The compiled deployment package is present at projects\my-proj\package\target\com.myco.my-proj-1.0.zip. The com.

myco.my-proj-1.0.zip file contains the following files:
db
record
<record-definition-name3>.options
<record-definition-name3>.data
<record-definition-name3>.delete
process
rule
<rule-definition-name>.def
association
view
<view-definition-name>.def
named-list
localized-string
<localized-strings.def>
configuration.data
role.data
code <jar file>
manifest file

Releasing
To provide the bundle to QA for black-box or integration testing, or to a pre-production shared system, make the
package file projects\my-proj\package\target\com.myco.mypackage.my-proj-1.0.zip available to administrators for the next
phase of delivery. Now you are done with bundle version 1.0.
To release a new version

Perform the following steps to release a new version of your application:
1. Update your POM files using the following command:
projects\my-proj> mvn versions:set -DnewVersion=1.1.0-SNAPSHOT
The new version is created in the following format:

For example, 17.11.0, 17.11.0-SNAPSHOT, 1.0-SNAPSHOT, 1.0.0.RELEASE.
For more information about guidelines on creating new versions, see Guidelines for versioning and undeploying
an application (see page 320).
2. Deploy the new version by using the following command:
projects\my-proj> mvn clean install -Pdeploy
Related topic
Localizing a Digital Service application

You can enable localization for your smart bundle and localize the Digital Service application definitions and data. After
you localize a smart bundle, user can view the application user interface (UI) and error messages in the preferred
language.
Localization files
After you generate a smart bundle from archetype, following files are automatically created in the application project:
localized-strings.json (located at bundle\src\main\webapp\resources\i18n)
localized-strings.properties (located at bundle\src\main\resources)
For more information on Projects created by the archetype, see Creating a Project using Maven and the Archetype (see
page 806).
Supported languages
You can localize your application in any language except the right to left languages. Right to left languages such as
Hebrew and Arabic are not supported.
BMC Helix Innovation Suite supports the following languages for the translation of error messages, warning messages,
and static strings on your application UI:
French

German
Italian
Japanese
Korean
Portuguese (Brazil)
Russian
Simplified Chinese
Spanish
Before you begin

Before you begin with localization of your application, ensure that the application is localizable. To make your application
localizable, you must extract the strings that you want to localization from your application code and definitions.
Extract the Java based string in localized-strings.properties file.
Extract the JavaScript based strings in localized-strings.json file.
To localize definition based strings
The following video helps you to localize your application:
https://youtu.be/KcsJPaeI510
1. Declare the custom view component properties (like field labels, column labels, action button labels, and so on)
as localizable.
a. Navigate to <view-component-name>.config.js file located in the view-components/<view-component-

name> folder.
b. Declare the view component properties as localizable. Following is a sample code to configure a view
component to declare localization properties:
rxViewComponentProvider.registerComponent([
{
name: 'Display Greetings',
group: 'Hello World Components',
icon: 'speaker',
type: 'rx-greeting',
designType: 'rx-greeting-design',
propertiesByName: [
{
name: 'greeting',
type: 'string',
isRequired: true,
isConfig: true,
isProperty: true,
localizable: true
}
]
}
]);

2. Redeploy your application.

To redeploy your application, in a command shell, navigate to the application parent directory and run the
following command:
mvn clean install –Pexport -Pdeploy
3. In BMC Helix Innovation Studio, if you have created any view definition using the custom view component, you
must create the view definition again (this is required as you change the source code for the view component in
Step 1).
4. Apply translations (see page 971).
To localize Java based strings
1. In localized-strings.properties file (located at bundle\src\main\resources), add the strings that you want to
localize.
2. Import the strings from the localized-strings.properties file to BMC Helix Innovation Suite.
To import strings, in a command shell, navigate to the application parent directory and run the following
command :
mvn clean install -Plocalization
After you run this command, the strings are available in the BMC Helix Innovation Studio.
3. Apply translations (see page ).
To localize static strings

To localize any static strings in your application code, you must apply the localization filter to all static HTML strings. To
retrieve localized strings, you must use the localization service.
The following code snippet is an example using the translate filter:
<input type="search" id="search" class="d-navigation__search-item" placeholder="{{'rx.core.components.search-

field.searchbox.placeholder' | translate}}"/>
The following code snippet is an example of using the $translate service
$translate([
'tms.approvals.myApprovals.title',
'tms.approvals.myApprovals.subtitle'
]).then(function (translations) {
$scope.title = translations['tms.approval.myApprovals.title'];
$scope.subtitle = translations['tms.approval.myApprovals.subtitle'];
});
Note

Ensure that the string localization key follow the following name space:
modulename.componentname.subpart.type.label (modulename.componentname is required)
For example, "tms.approvals.actionbar.action.approve" : "Approve"
To localize OOTB view component definitions

As an application business analyst, you can customize a view definition and localize it by using BMC Helix Innovation
Studio. For example, you can edit or create view definitions and then localize your application. To localize the OOTB view
component definitions, perform the following:
1. Log in to BMC Helix Innovation Studio, and through the Workspace, navigate to the application for which you
want to customize definitions.
2. Customize the definitions as per your requirements and save the definitions.
3. Apply translations (see page 971).
To localize record instances

You can localize record instances by using the locale field. The field ID of the locale field is 160.
1. Localize the server.

In a browser, open the BMC Remedy AR System Administration Console, navigate to General > Server
Information > Advanced, and enable Localized Error Messages (Localize Server).
2. Create a text field with field ID 160 in the record definition for which you want to localize record instances.
3. Create record instances and provide valid values for the locale fields.
When you use a record definition with locale field in a view component such as record grid, only the record instances for
the accepted locale are displayed.
To apply translations
1. In BMC Helix Innovation Studio, in your application, navigate to Translations > Download Translations and
download the localized-strings.json file.
Following is a sample localized-strings.json file:
{
"7a97b657-0162-426b-9df9-78e35d0fde6a":"Welcome"
}
2. Translate the localized-strings.json file in the following format:
{
"fr" : {
"7a97b657-0162-426b-9df9-78e35d0fde6a":"Bienvenue"
},
"de": {
"7a97b657-0162-426b-9df9-78e35d0fde6a":"
Willkommen

"
}
}
3. In BMC Helix Innovation Studio, navigate to Translations > Upload Translations and upload the translated
localized-strings.json file.
To localize error messages

To localize the error messages, perform the steps in To localize Java based strings (see page 970) section.
Related topics
Creating record instances (see page 346)
Creating a smart library of reusable components

You can create a smart library using BMC Helix Innovation Suite and it can be used as a reusable building block for
building applications.
To create a smart library, perform the following steps:
1. Create a library project (see page 972).
2. Deploy the library project (see page 973).
3. Create the required record definitions for the library. See Defining record definitions to store and manage data
(see page 324).
4. Create the required view definitions for the library. See Defining the user interface through view definitions (see
page 376).
5. Package the library (see page 973).
To create a library project

You can create source files for a library project using Maven archetype. Create a directory to store the project code.
Note
BMC recommends that you should not create the the library project in the sdk folder.
1. On the command prompt, navigate to the directory created.

For example: C:\projects
2. To create project, run the following command:
mvn archetype:generate -DarchetypeGroupId=com.bmc.arsys -DarchetypeArtifactId=rx-sdk-archetype-lib -

DarchetypeCatalog=local

-DarchetypeGroupId=com.bmc.arsys Maven uses BMC archetypes
-DarchetypeArtifactId=rx-sdk- Selects the library archetype. This sets the POM file to create a library package and does not generates a
archetype-lib working UI.
3. The command starts the archetype plugin in interactive mode and prompts for the following options:
Property Description Example
Values
groupId Project group ID. The ID usually follows the naming conventions of Java package names. com.
Note: You must provide the Developer ID as the groupID value. example
artifactId Project ID that is used as a part of filename. It usually has a short name as the project is already name spaced by the work-order-
groupId. lib
Note: The artifactId cannot be a combination of '-' (hyphen) and numeric character. For example, work-order-lib -12 is
not a valid artifactId.
version Project version. You can provide the value in any format (major.minor or major.minor.maintenance). 1.0-
SNAPSHOT
package Default Java package for the project. The default value is groupId value. com.
example
name Bundle name. This is used by the archetype to display the name of the application on the login page. Work Order
Confirm the configuration of all the properties.
After you create a new project, you should create a deployment package and deploy the package to BMC Helix
Innovation Suite server .
To deploy the library project

To built and deploy the library project, navigate to the project directory and run the following command:
For example:
Once the build is complete, verify that the library is available in the BMC Helix Innovation Studio.
To package the library

To create a deployment package for the library, on the command prompt, navigate to the library project and run the
following command:
mvn install -Pexport -Pdeploy

For example:
projects> cd work-order-lib
work-order-lib> mvn install -Pexport -Pdeploy
The deployment package is created in the target folder located in the library project directory.
For example, the deployment package for work-order-lib is located at projects\work-order-lib\package\target\com.

example.work-order-lib-1.0-SNAPSHOT.zip
The deployment package zip file contains the code bundle jar file and the def file which consists the definitions.
For example, com.example.work-order-lib-1.0-SNAPSHOT.jar file and com.example.work-order-lib-1.0-SNAPSHOT.def file.
Related topics
Creating a tailorable Digital Service application using definitions (see page 323)
Using Data Caching Service

For better performance, some applications might cache their own data, their metadata information, or even their
configuration items. BMC Helix Innovation Suite provides a Data Caching Service accessible at com.bmc.arsys.rx.services.
cache.CacheService to enable applications to cache data, metadata, and configuration items. After the application is
deployed, it can use CacheService to create the cache. After the cache is created, application can add data element to
the cache. The application's cache data is cleaned up when the application is uninstalled or reinstalled.
The Data Caching Service increases the application performance by reducing the following:
Time spent on requesting and receiving the data over the network. This facilitates the server to process more
requests in a shorter time period.
Load on the database server by processing the frequently used requests on the services.
Use the Data Caching Service to perform the following tasks:
Cache internal or external data of the application by using the com.bmc.arsys.rx.services.cache.Cacheable method
Create a cache for every tenant when creating local variables and storing transient data in those variables. The
application's cached data will never leak from one tenant to another.
Synchronize the cache across servers in a cluster.
Load custom data and initialize custom cache by using the com.bmc.arsys.rx.services.cache.CacheInitializer
method
A CacheConfiguration type is used to configure the cache, and consists of the following attributes:
Name of the cache
Maximum size of the cache

The cache size is configurable between 10 MB and 20 MB.

Cache initializer
If the initializer is not provided, the frequently used items will be added in the cache.
Data Caching Service sample code

The following code snippet illustrates a sample Data Caching Service code format. Application developers can use this
service in custom actions, REST Resource, and so on, to retrieve the application's data.
// Get the cache service

CacheService cacheService = ServiceLocator.getCacheService();
// Create a custom cache initializer

CacheInitializer initializer = new CustomCacheInitializer();
// Create cache configuration

CacheConfiguration cacheConfig = new CacheConfiguration(MY_CACHE, 1,initializer);
// Create cache
cacheService.createCache(cacheConfig);
For more information, see the CacheService information in Platform Service Java API Documentation (see page 1003).
Following are methods of the CacheService provided in the REST API call:
Task Method to use
To get all cache entries

Set<Cacheable> cacheables = cacheService.getAll
(cacheName);
To get specific cache entries

cacheService.get(id)
To reset the cache entries

cacheService.resetCache(cacheName);
To delete all cache entries

cacheService.deleteAll(cacheName);
To delete specific cache entries

cacheService.delete(cacheName, objectId);
Related topics
Undeploying a version of your application

By default, only two versions of an application can be deployed on a system. If two versions already exist, the developer
must undeploy a version of a code-based application from the QA and production environments.

Points to consider before undeployment
If you undeploy the latest version of an application, the entire application is undeployed. You cannot restore the
data and changes made during tailoring after the entire application is undeployed.
Best practice
BMC recommends that you undeploy the oldest version of an application. The version that is not used
by any tenant can be termed as the oldest version of an application.
If you do not specify a version to undeploy, by default, the entire application is undeployed.
To undeploy a version of your application from the development environment

To undeploy a version, navigate to the application's parent directory and run the following command:
mvn com.bmc.arsys:rx-sdk-maven-plugin:undeploy -N -DbundleVersion=<version number>
For example:
mvn com.bmc.arsys:rx-sdk-maven-plugin:undeploy -N -DbundleVersion=1.1.0
Related topics
Guidelines for versioning and undeploying an application (see page 320)
Upgrading to a new version of an application with zero downtime (see page 286)
Getting your Digital Service application ready for use (see page 915)
Enabling Remedy SSO OAuth 2.0 authentication for your application

Remedy Single Sign-On (RSSO) implements OAuth 2.0 protocol—an industry standard framework that enables a third-
party application to obtain limited access to an HTTP service, for example, an BMC Helix Innovation Suite application.
The OAuth 2.0 protocol authenticates either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own
behalf.
As a developer, you can create configuration settings in BMC Helix Innovation Suite to enable RSSO OAuth 2.0 in your
application. An administrator configures the RSSO OAuth resource server name, client ID, and client secret in the In-
bundle settings created by the developer.
This topic describes the steps to create the configuration settings to enable RSSO OAuth.

Process of creating and adding RSSO OAuth 2.0 settings in an application
The following section describes the steps to create In-bundle settings and add them to the application's Java code.
To create In-bundle settings for RSSO OAuth configuration
2. Select the application for which you want to enable RSSO OAuth.

5. In the New In-bundle Settings window, specify the following properties for the setting:
Component Enter the configuration name. The name is displayed in the Configurations tab in your bundle's Workspace. Example: OAuth
Name Configuration
Is View Do not select this option.

Component
Registered Select oauth-configuration

Module
Name
Status Select this option to indicate that this is an active setting.
Available as Select this option so that the setting is displayed in your application.
Navigation
Sidebar
Show In Select Both. The configuration setting is available in the application's Settings menu and the Administration tab of BMC Helix
Innovation Studio.
Permissions Select the roles and groups that can access the setting. You can add permissions to groups or application roles. You can select roles
from multiple applications deployed on the system.
First Menu Enter the name of the top level navigation menu that is displayed in the Settings menu. If multiple settings use the same name for
First Menu, then all those settings appear under the same navigation item.
Second Enter the name of the second level navigation item that is displayed in the left hand navigation of the Settings menu. If left blank, no
Menu second level item will appear. If multiple settings use the same name for Second Menu, then all those settings appear under the same
navigation item.

6. Click Save.
To add the RSSO OAuth In-bundle setting in custom code

After creating the In-bundle setting for RSSO OAuth, you must use the Setting name in your application's custom service
action code.
1. Open the application's custom service action code.
2. After the @Action and @Action Parameter section, add the folliowing code and save:
if (ServiceLocator.getOAuthService().isOAuthConfigured(
<ConfigurationName>)) {
String token = ServiceLocator.getOAuthService().getAccessToken(
<ConfigurationName>,
false);
After the developer deploys the application, the RSSO OAuth In-bundle setting is displayed in the BMC Helix Innovation
Studio Administration tab and the application's Settings tab as shown in the following example:
An administrator adds the RSSO OAuth details to enable RSSO OAuth for an application.
Related topics
Configuring OAuth 2.0 authentication
Troubleshooting
This section provides information about troubleshooting issues that you might encounter when working with BMC Helix
Innovation Suite.
Action Reference
To troubleshoot issues related to sandbox access Troubleshooting sandbox access issues (see page 980)
To troubleshoot issues related to codeless application development Troubleshooting application deployment issues (see page 980)
To enable logging for an application Enabling logging for a Digital Service application (see page 981)
To enable browser logging for an application Enabling browser logging in a Digital Service application (see page 987)

Action Reference
To troubleshoot issues when enabling automatic assignment for application Troubleshooting automatic assignment issues (see page 988)
requests
To report an error encountered while performing REST API operations Reporting application errors as issues (see page 992)
To troubleshoot connection issues related to the BMC Integration Service Troubleshooting BMC Integration Service connection issues (see page 991
)
Related topics
FAQs and additional resources (see page 1009)
Troubleshooting sandbox access issues

This section describes issues that you might encounter while accessing sandbox.
Troubleshooting user account locked error
If you get this error when you try to access the BMC Helix Innovation Suite URL, you can do either of the following:
Use the Unlock Account button on the sandbox Details page.
Log in through the midtier using your administrator account and open the User form to reset the password of
the developer account.
Troubleshooting BMC Helix Innovation Studio access authorization issues

You are trying to login to the BMC Helix Innovation Studio using your admin account instead of your developer account.
Log in to BMC Helix Innovation Studio by using your developer account credentials.
Troubleshooting application deployment issues

This section describes issues that you might encounter while creating or deploying codeless applications.
Troubleshooting package creation issue

Issue Description
Cannot create install or update Cause: Install and update packages can only be created for applications that you have created, that is, the developer ID of
packages in my development the application and the server must be the same. If you signed in with a different developer ID, you will cannot create install
environment or update packages.
Workaround: Sign in with the developer ID same as that of the server and create install or update packages.

Troubleshooting application deployment issues

Issue Description
Cannot reinstall an application by using Cause: Bundle ID is not specified in the manifest file of the install package ZIP file. The following error message is
BMC Helix Innovation Studio displayed:
6603 Bundle id is missing in the manifest file of provided package zip

file for re-install operation.
Workaround: Recreate the install package to include the manifest file and bundle ID that are mandatory for
reinstalling the application.
Cannot import an export package by Cause: The export package's name or version number, that you selected for import, is different than the installed
using BMC Helix Innovation Studio application's name or version number.
Workaround: Import the export package with name and version number that matches the installed application's
name and version number.
Cannot update an application by using Cause: You selected an invalid version in the Update from Version field.
an update package
Workaround: Select the version number of the available application and create an update package. For more
information, see Creating update packages to deploy incremental changes of applications (see page 769).
Cannot deploy an application or library Cause: You used a non-tenant specific application, that is, a code-based application for deployment through BMC
by using BMC Helix Innovation Studio Helix Innovation Studio. The following error message is displayed:
6604 Insufficient privileges to deploy an application or library with

code.
Workaround: Use a tenant-specific application, that is, a codeless application for deployment through BMC Helix
Innovation Studio.
Cannot deploy export package by using Cause: You are deploying the export package to a developer environment, that is, the developer ID of the
BMC Helix Innovation Studio application and the server is the same. The following error message is displayed:
6605 Cannot deploy export package on developer machine.
Workaround: You must use a tailoring environment for deploying export package, that is, the developer ID of the
application and the server must be different.
Related topics
Enabling logging for a Digital Service application

BMC Helix Innovation Suite platform provides logging capabilities that you can use to track the activities and debug
issues within the application. This topic provides information about enabling logs, setting logging levels , and viewing the
contents of the log file for the applications .
With BMC Helix Innovation Suite you can gather information to troubleshoot functional issues or errors that occur in a
bundle and log them in a log file. The logs for each bundle are stored in a separate log file unique to that bundle. For
example, logs for bundle A are stored in log file A, whereas logs for bundle B are stored in log file B.
BMC Helix Innovation Suite also allows multiple bundles to share the same log file name. For example, bundle A invokes a
service from bundle B, the logs for the completed execution will be stored in multiple files. To avoid logs from being
saved in multiple log files, BMC Helix Innovation Suite allows bundles to share the same log file name. The logs generated
by these smart bundles are stored in same log file by specifying same log file name for each smart bundle.

To enable BMC Helix Innovation Suite platform logs

To generate logs, you must turn on the Debug-mode shared configuration setting.
1. Log in to BMC Helix Innovation Studio and navigate to Administration tab.
2. Click Configure My Server > Centralized Configuration Settings > Centralized Tenant Configuration.
3. From the Component Type, select shared, and click Add Setting.
4. On the Add Setting page, enter the following details:
In Setting Name, select Debug-mode.
In Setting Value, set the value of Debug-mode to an integer that represents the component flags that you
want to enable. To calculate this value, see Selecting the Debug-mode flags based on component (see
page 982).
5. Click Save.
Selecting the Debug-mode flags based on component

The Debug-mode represents a bit field. Each area supported by logging must be enabled by adding the correct binary
value for the correct bit, which you can compute using a binary OR. The following table provides a list of values that you
can use to for the corresponding log component:
Note
The binary equivalent is just shown here to help in understanding which flags control which components; you
do not enter this as the Debug-mode.
Log component Typical troubleshooting Value Binary equivalent
Nothing enabled This is the default value. 000000000000000000000
SQL Low level errors involving the database, such as unique index violation. 1 000000000000000000001
FLTR Activity around Rules based on the time conditions, or record level events (on or after 2 000000000000000000010
create, update, delete, and so on).
Often used to trigger processes.
USER Login, logout, authentication, licensing, and so on. 4 000000000000000000100
API Activity at the AR System level. 16 000000000000000001000
PROCESS Execution of process steps, process blocking, in-process exceptions. 1048576 100000000000000000000
All but SQL Turn on logging for all the above components, except for low level errors involving the 1048598 100000000000000010110
database.
Turn on all of the Turn on logging for all the above components. 1048599 100000000000000010111
above

To enable logs
After you enable the logs, you must contact BMC Customer Support (see page 993) to view or retrieve the log
files.
1. Log in to BMC Helix Innovation Studio, navigate to the Administration tab, and select the required deployed
smart bundle.
2. Click Logger Configuration.
3. In the Logger Configuration Settings panel, enter the following details:

Option Description
File Name Specify the name of the log file.

By default, name of your smart bundle is the name of the log file.
Level Specify the level of logging for smart bundle. The options are:
TRACE
DEBUG
INFO
WARN
ERROR
The default level is ERROR.
4. Click Save.
Notes
If you use library services from an application, the library's logs are captured in the application's log file.
These logs are generated based on the Logger Configuration Settings (File Name, Level) defined for
the application.
Capturing the library's logs in the application's log file allows you to maintain the log activities for the
complete execution of the application in one single file.
For example, a PTO application uses the Approval library to approve or reject the leave request of an
employee. The logs for Approval library are stored in the log file for PTO application. The logs are
generated based on the Logger Configuration Settings defined for PTO application.

The library's Logger Configuration Settings are used only if a REST API call is made to the library
bundle with default-bundle-scope set to the library's bundle ID.
If default-bundle-scope is not set in REST API, then the logs are captured in arextension.log file.
Searching log files to track a single operation

An operation consists of several actions. For each operation, the logs are scattered across several files such as Process
Log, API Log, SQL Log and so on. Any log file that is enabled contains the Operation Id parameter unique for all logs of an
operation. To troubleshoot an application, you can search the Operation ID parameter in several log files and group the
logs related to a single operation.
Example
You want to troubleshoot why updating a request takes longer than expected. There are several rules and
processes that run when a request is updated. After enabling the API, rule, process, and SQL debug logs, you
can search for the Operation Id to identify the exact action that is causing the delay.
You can set the Operation Id for an operation. If you have not set the Operation Id, the server generates the Operation
Id.
How Operation ID works
The server tracks a single operation with the same Operation Id in different log files.
The server retains the Operation Id when the After Event rule executes.
The server generates a new Operation Id for a process that resumes after a wait state.
The server generates a new Operation Id when a Timer Event rule is executed.
When a custom rule or process is executed in a Thread Local context and spawns a new thread, you can copy the
Operation Id from the calling thread to the new thread. If the new thread is left blank, the server generates a new
Operation Id. The ThreadLocalContext provides a method to set and get the Operation Id.
To set the Operation ID

In the REST API HTTP header, add the parameter operation-id and set the value to an alphanumeric string of 1 to 30
characters. You can use any standard Java algorithms to generate the Operation Id. If you want to use the same
Operation Id for multiple API calls, you must set the Operation Id in the HTTP header for each call.
Format of log messages

The following example shows the general format of the log messages:
<BUNDLE> <TID: xxx> <TENANT ID:xxx> <USER: xxx > /*date */ <<log level>> <<actual message>>

For example:
<BUNDLE><TID: 0000000033> <TENANT ID: TNGAABDUC2YGIAO78IS4O6M82T3SUZ> <USER:admin> /* Wed Mar 15 2017 16:59:
36.459 */ DEBUG trackExpenses : Debug Level Is Enabled
<BUNDLE><TID: 0000000033> <TENANT ID: TNGAABDUC2YGIAO78IS4O6M82T3SUZ> <USER:admin> /* Wed Mar 15 2017 16:59:
36.462 */ TRACE trackExpenses: For Expense exception amount is 5000
Example of Operation Id in an API log
<API > <OpId: IDGG5K5KB1HMPAOD1EK2OD1EK28A9Z> <TID: 0000000001> <RPC ID: 0000000000> <Queue: Admin >
<Client-RPC: 390600 > <USER: Remedy Application Service > <Tenant-ID: 0
> <Overlay-Group: 0 > /* Fri Sep 15 2017 11:22:55.2270 */ +GLEWF ARGetListEntryWithFields -- schema
BundleDeploy:BundleRegistry from Unidentified Client (protocol 19) at IP address null using INTERNAL // :q:0.0
s null
> <Overlay-Group: 0 > /* Fri Sep 15 2017 11:22:55.2390 */ -GLEWF OK
s null
> <Overlay-Group: 0 > /* Fri Sep 15 2017 11:22:55.2940 */ -GLEWF OK
s null
To disable logs
1. Log in to BMC Helix Innovation Studio, navigate to the Administration tab, and select the required deployed
smart bundle
2. Click Logger Configuration.
3. In the Logger Configuration Settings panel, enter the name of the log file.
4. Leave the Level field blank; do not select any option.
5. Click Save.
To clear the logs
Caution
BMC recommends that you do not delete the log files if you are on production environment. To delete the log
files, stop the server services, clear the logs, and restart the server services.
1. Stop the services of the BMC Helix Innovation Suite server.

2. From the following default location of log files, select the application log file that you want to clear:
(Windows) – ARSystemInstallDir\<tenantdirectory>\ARserver\Db
(UNIX) – ARSystemInstallDir/<tenantdirectory>/ARserver/Db
3. Delete the application's log file. Alternatively, you can clear the contents of the log file.
4. Restart the services of the BMC Helix Innovation Suite server.
Using Logger service

BMC Helix Innovation Suite platform provides a Logger service (com.bmc.arsys.rx.services.common.Logger) for
developers to add logs in their server-side code. For example, a developer can add logs in service classes or REST
resources.
The following example shows how to get the Logger and use the Logger to log messages:
import com.bmc.arsys.rx.services.common.Logger;

public TaskResult createTask(Task task) {
Logger logger = ServiceLocator.getLogger();
if (logger.isDebugEnabled()) {
logger.debug(String.format("the task name is %s, assigned to %s", task.getName(), task.
getAssignee());
}
RecordInstance recordInstance = convertToRecordInstance(task);

try{
ServiceLocator.getRecordService().createRecordInstance(recordInstance);
logger.info(String.format("task %s is created", task.getId()));
} catch (RxException ex) {
logger.error(ex);
throw ex;
}
}
}
Note
If you use the Logger service in any of the register() methods associated with the bundle start event, the
logs for the applications are captured in the log file with a name such as arextension.log . On Windows, the
location of the file is < ARServerInstallDir>\ARServer\Db.
Related topic

Enabling browser logging in a Digital Service application

BMC Helix Innovation Suite platform provides logging capabilities that you can use to track the activities and debug
issues with the Digital Service application. The logs provide information about the actions invoked in the client during
interactions with an application. All the log messages are logged to the browser console. You can view all the server logs
and user interface logs in the browser console by adding debug parameter to an application URL.
To enable logging in code-based applications
1. In the application, to open the browser console, press F12.
2. On the browser console, navigate to the Console tab.
3. Add ?debug parameter in the application URL.

For example, http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug#/approval/console
The logs are populated in the browser console.
4. To get the logger, use ServiceLocator from com.bmc.arsys.rx.application.common and use getLogger() function.
You will get a com.bmc.arsys.rx.services.common.Logger and method like Logger.info can be used to log.
For example:
public Logger getLogger() {

if (logger == null) {
logger = ServiceLocator.getLogger();
}
return logger;
}
getLogger().info(“Custom message to log”)
To enable logging in codeless applications
1. In the application, to open the browser console, press F12.
2. On the browser console, navigate to the Console tab.
3. Add ?debug parameter in the application URL as follows:

http:// <server>:<jetty port> /innovationsuite/index.html?debug#/BUNDLEID/view/BUNDLEID.VIEWNAME
For example, http:// <server>:<jetty port> /innovationsuite/index.html?debug#/com.example.MyApp/view/com.bmc.
arsys.rx.approval:Approval%20Console
The logs are populated in the browser console.
Logging levels
You can specify the following logging levels in the debug parameter to filter the log messages:
Logging Description Example (code-based application)

level
Server logs
sql Logs SQL logs executed on the server http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=sql#
/approval/console

Logging Description Example (code-based application)

level
api Logs server API messages to the console http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=api#
/approval/console
rule Logs rules execution information to the console http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=rule#
/approval/console
process Logs processes execution information to the console http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=process#
/approval/console
debug Logs messages when any of the following events occurs: http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=debug#
/approval/console
A request is send or a request is resolved.
The application state is changed.
An action is executed.
An expression is evaluated.
bundle Logs all the messages for the custom code http://<server>:<jetty-port>/com.example.taskmanager/index.html?debug=bundle#/bx
/view/com.example.taskmanager
Client logs
info Logs messages of information level from the application. http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=info#
/approval/console
warning Logs warning messages from the server or messages http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=warning#
logged from the application. /approval/console
error Logs error messages when any request fails or client code http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=error#
errors occur. /approval/console
To add multiple logging levels to the debug parameter, separate the logging levels using comma. For example, to enable
server logging level and info level, specify the logging levels in the URL as follows:
http:// <server>:<jetty port> /com.bmc.arsys.rx.approval/index.html?debug=api,sql,info#/approval/console
If no value is passed to the debug parameter, all the logging levels are enabled.
Troubleshooting automatic assignment issues

This section describes issues that you might encounter while enabling automatic assignment for application requests.
You can use the return codes and their descriptions, that you configured when defining an assignment policy (see page
625), for debugging purposes.
The following table provides information about the return codes and their descriptions:
Return code Return code description Assignment status
0 Support group is assigned. Assignment is successful.
1 Support group and individual assignee are assigned. Assignment is successful.
2 Support group is assigned, but cannot find the Assignment has partially failed.
individual assignee for assignment.
Workaround:
Verify whether any persons are associated with the support group.

Return code Return code description Assignment status
3 Cannot find the support group for assignment. Assignment has failed.
Workaround:
Verify if the assignment rule is disabled. If the assignment rule is enabled but does
not successfully qualify, configure rule with the required valid qualification.
4 Assignment policy is disabled. Assignment has failed.
Workaround:
Enable the assignment policy.
5 The assignment policy specified is incorrect for this Assignment has failed.
record.
Workaround:
Verify whether you have associated the correct policy with assignment process.
Related topic
Troubleshooting Foundation data issues

This section describes issues that you might encounter while loading existing or custom Foundation data from Remedy
ITSM.
Troubleshooting issues while loading Foundation data

Issue Description
Cannot load the Foundation data to BMC Helix Innovation Suite If the new Remedy ITSM Foundation data is grouped with other data, the data is not
loaded to BMC Helix Innovation Suite. All the Foundation data is processed from Excel
spreadsheets in chunks of 100 rows. If there is any error in any one of the 100 rows,
each remaining row from the chunk is processed individually..
If there is failure in loading of updated ITSM Foundation data, you can retrieve the last
job execution instance by selecting BMC Helix Innovation Studio > Data Management
Console > Settings > AR Synchronization. You can use this information to verify the last
synchronize date and time, and ensure that the next scheduled update synchronizes the
newly-added or updated Foundation data.
In the processed Excel spreadsheet, the Foundation data that is not loaded displays an
Errored status. As a workaround, perform the following steps:
1. Resolve the issue in Remedy ITSM or BMC Helix Innovation Studio.
2. Download the processed spreadsheet to your computer.
3. Open the spreadsheet, delete the data from the Data-Load-Status column, and
save the changes.
4. From Data Management Console application of BMC Helix Innovation Studio,

select Visit Deployed Application > Data Load > Upload New > browse and select
the updated spreadsheet.
5. Select the updated spreadsheet and click Load Data.

Issue Description
BMC Helix Innovation Suite runs the data load job once again, processes the modified
Foundation data, and ignores the already-processed Foundation data. After the data
load is completed, open the processed spreadsheet and verify that the Foundation data
is successfully processed.
Foundation data load fails with java.lang. This error occurs due to insufficient Pentaho memory size.
OutOfMemoryError exceptions.
As a workaround, increase the Pentaho memory size by performing the following tasks:
1. Log in to BMC Remedy AR System server as an AR administrator.
2. Open the Java-based armonitor.conf (armonitor.cfg) configuration file by

navigating to the following location:
(Windows) ARSystemServerInstallDir \Conf\armonitor.cfg
(UNIX) /etc/arsystem/serverName/armonitor.conf
The armonitor.conf file is read by the armonitor (armonitor.exe) binary, which
runs the commands listed in the configuration file.
3. For diserver value, enter the Pentaho memory size that is required to load your
ITSM Foundation data.
The default Pentaho memory size is 1024. The size of ITSM Foundation data and
the minimum Pentaho memory required to process the data load is as follows:
If you have 15000 records in Excel spreadsheet, the minimum Pentaho

memory required is -Xmx1024m.


For example, if you want to load 5000 Company records, 15000 People
records, and 10000 Location records, then you do not need to increase
the Pentaho memory size. However, if you want to load 5000 Company
records, 50000 People records, and 10000 Location records, you must
increase the Pentaho memory size to 2048 as the People records
exceeds the permitted number of records that can be included in a single
Excel spreadsheet.
Troubleshooting issues while customizing or extending Foundation data

Issue Description
Cannot see the customized or extended Foundation data This issue occurs because of either of the following reasons:
You do not have permissions to access the record fields, that is, the fields that contain
additional information about the Foundation data.
To add permissions to access a record definition or a record field, see Creating or
modifying regular record definitions (see page 329).
You have disabled the direct association between Foundation record and regular record
(that contains additional information about Foundation data)
To enable the record association, see Creating record associations (see page 342).
In the view that you want to extend in Foundation view, you selected a mode that is
different than the parent Foundation view's mode.
You created multiple extension views that point to the same regular record definition. In
such case, BMC Helix Innovation Suite displays only the oldest view in Foundation view at
run time.

Related topics
Setting up Foundation data for custom applications (see page 641)
Troubleshooting incoming and outgoing email issues

This section describes issues that you might encounter while configuring incoming or outgoing emails. The errors are
captured in the arserver.log file.
Issue Description
Outgoing profile is not created. Cause: While creating a process or rule by using Send Message or Send Message by
Template you select the outgoing profile and the profile does not exist. The following error
message is displayed:
9807 Email profile not found.
Workaround: Create an outgoing profile.
Outgoing profile is not mapped with the outgoing mailbox. Cause: While creating a process or rule by using Send Message or Send Message by
Template you select the outgoing profile and the profile is not mapped to any outgoing
mailbox. The following error message is displayed:
Error 9803 No Mapping found for outgoing email profile.
Workaround: Create an outgoing profile and map the profile with the outgoing mailbox.
Related topics
Configuring incoming and outgoing email (see page 750)
Sending a user message from a process (see page 470)
Troubleshooting integration service connection issues

By default the user credentials for the BMC Integration Service connection are configured automatically when a sandbox
is provisioned. If you face issues with the BMC Integration Service connection, verify the user credentials provided for
the BMC Integration Service connection. An administrator can modify the user credentials for the BMC Integration
Service.
To modify the user credentials
2. In the Settings pane, navigate to Configure My Server > Integration Service.
3. As needed, modify the URL, user name, or password, and save the changes.
Related topic
Integrating with another application by using a connector (see page 615)

Reporting application errors as issues

When you encounter an error on BMC Helix Innovation Studio, you can report the error as an issue. Reporting an error
as an issue provides you with the following benefits:
Reduced time to resolve errors.
Ability to provide details on how the error was encountered.
Note
You can report issues only from a tailoring, test, or production environments. If you encounter an error while
you are creating an application in a development environment, you can report the error and post your
questions on BMC Communities .
After you report the issue, the details are sent to the administrator who can then submit a case to BMC Customer
Support to resolve the issue. For more information, see Submitting user reported issues to BMC Customer Support (see
page 782).
The following illustration describes the workflow of reporting an issue:
To report errors
1. Click Report Issue on the error message.
2. Describe the steps that led to the error.
3. Click Submit Report.
Warning
When you click Submit Report, by default the issue data and logs will be shared with BMC Customer Support
to resolve the issue.

Related topics
Submitting user reported issues to BMC Customer Support (see page 782)
Support information
This topic contains information about how to contact Customer Support, and the support status for this and other
releases.
Contacting Customer Support

If you have problems with or questions about a BMC product, or for the latest support policies, see the Customer
Support website . You can access product documents, search the Knowledge Base for help with an issue, and
download products and maintenance.
If you do not have access to the web and you are in the United States or Canada, contact Customer Support at 800 537
1813. Outside the United States or Canada, select your country at Contact BMC to view local Support Contacts.
If you have signed up for the developer program, and you are using an Amazon Web Services Sandbox, post your queries
on BMC Communities .
Support status
As stated in the BMC Software Product Support Policy , BMC provides technical support for a product based on time
rather than number of releases. For subscription-based product support, see the BMC Software Subscription Services
Support policy .
To view the support status for this release, see the BMC Helix Innovation Suite Product Support page .
Policies
This section includes the following BMC Helix Innovation Suite policies:
Innovation Suite Availability policy (see page 994)
OnDemand Change Management policy (see page 996)
Innovation Suite Custom Application policy (see page 996)
OnDemand Notification policy (see page 998)
OnDemand Language Support policy (see page 1000)
Innovation Suite Permissions policy (see page 1000)
OnDemand Incident Response policy (see page 1002)
Innovation Suite Upgrade policy (see page 1003)

Innovation Suite Availability policy

BMC commits to a specific service level agreement (SLA) for availability with real penalties if the agreement is breached.
Your subscription agreement contains details about your Innovation Suite SLA.
BMC uses BMC technologies such as BMC TrueSight Operations Management to monitor your environments, and
provides monthly availability reports. Availability is a percentage of total service time, such as 99.95 percent, and is
calculated by using the following formula:
Availability = (Service Time – Excluded Downtime – Non-excluded Downtime) x 100

(Service Time – Excluded Downtime)
The values in the formula are defined as follows:
Service Time: Total minutes for a particular calendar month
Excluded Downtime: All downtime that is scheduled or mutually agreed-upon for the purpose of performing
routine, non-emergency, or emergency maintenance on Innovation Suite services, or that occurs on non-
production systems. Excluded Downtime also includes downtime that is caused by factors outside the reasonable
control of BMC, including, but not limited to, customer-managed performance or automated functional testing.
Non-excluded Downtime: All downtime that is not Excluded Downtime
For example, for a given month, the service time was 720 hours (43,200 minutes). During that month, there were 2 hours
(120 minutes) of planned maintenance performed on Innovation Suite services. There was an additional 20 minutes of
unplanned downtime that was not due to any of the factors listed in Excluded Downtime.
In this example, availability is calculated as follows:
Availability = (43200 – 120 – 20) x 100 = 99.95 %

(43200 – 120)
In the case of unscheduled production downtime, BMC provides a Reason for Outage document as described in the
Innovation Suite Response Policy.
In the event of any production downtime (scheduled or unscheduled), the customer will be notified as defined in the
OnDemand Notification policy (see page 998).
Downtime definition by category

The OnDemand team defines downtime by using the following categories:
Full downtime
Inability to log on and perform work for a majority of the user population
A significant and prolonged performance event that significantly impacts the user population
Internal BMC monitoring indicates that the system is unavailable
Partial downtime
Failure of a critical business function (for example, incoming email processing, critical batch job or
integration)

Periods of instability causing users to be unable to work beyond five minutes
Note
Unscheduled partial downtime impacts a small user base and therefore is considered Excluded Downtime.
Unscheduled full downtime is considered to be Non-excluded Downtime.
Downtime definition by functionality

The following list describes functionality that would classify as full downtime in the case of an unscheduled unavailability
event:
Core Innovation Suite Services
Any performance of core components that are impaired to the point of being non-usable where the issue is
deemed to be within the direct control of OnDemand
The following list outlines other functional areas that would classify as partial downtime in the case of an unscheduled
unavailability event:
Inbound email processing
Reporting processing
Notification Engine processing
Approval engine processing
Assignment Engine processing
Any non-critical administration functionality
Note
Both full and partial unscheduled unavailability will be treated as a severity 1 incident.
Customer applications causing downtime

The following issues are also considered Excluded Downtime:
Any issue caused anywhere in the application based on customer-implemented logic
Any issue caused anywhere in the application based on a third-party component
Any issue caused anywhere in the application based on customer integrations

Requesting a service credit

To receive a service credit, you must submit a request by sending an e-mail message to SLArequest@bmc.com. To be
eligible, the credit request must (i) include your account number in the subject of the e-mail message; (ii) include, in the
body of the e-mail, the dates and times of each incident of Non-excluded Downtime that you claim to have experienced;
(iii) include your server request logs that document the Non-excluded Downtime (any confidential or sensitive
information in these logs should be removed or replaced with asterisks); and (iv) be received by BMC within fifteen (15)
days after the end of the calendar quarter in which the downtime occurred.
Additional terms related to SLA credits are as defined in your subscription agreement.
OnDemand Change Management policy

This topic describes the Change Management (CM) policy. The Customer is responsibility to any changes to the
customer’s application.
Testing and review requirements

The following list describes the requirements for the test and review processes:
All changes must be tested successfully using the BMC testing framework requirements. Test cases should cover
at least 90% of code.
Innovation Suite Custom Application policy

Innovation Suite supports the ability to have customer application (Custom application) built to suit your needs. Any
custom applications must conform to the BMC design standards. This conformance ensures the best experience for
supportability and upgrades.
When you add a custom application, you must consider not only the Innovation Suite Custom Application policy, but all
other Innovation Suite Policies published in the Innovation Suite online documentation portal.
General approach to supporting custom applications

The following information provides an overview of the general approach to supporting your custom Innovation Suite
application:
The custom application is treated as a customization, and as such, follows the OnDemand Customization policy
(including adoption of overlays and custom object approach).
The custom application is governed by the change management process and as such follows the OnDemand
Change Management policy (see page 996) and procedures.
The custom application is limited to 1000 Remedy objects. Support for larger applications is at the discretion of
BMC, and a charge could apply.
No service level agreement (SLA) targets are associated with a custom application.
BMC reserves the right to disable any custom Innovation Suite Custom application that impacts the
performance or availability of the Innovation Suite service. You will need to correct the offending code in the
development environment and promote it again.

Every user of a custom Innovation Suite application is allocated a named subscription. No read-only access to a
custom application is available for end users.
The management of the custom application is your responsibility.
No additional hardware or resources are allocated based on the size of your environment to support the custom
application. Scale of the environment is achieved by using user subscription pricing, and the Remedy environment
is expanded based on the pricing formula. If additional costs are incurred to expand environments to account for
a custom application, an additional fee will apply.
Third-party applications must be evaluated separately from this policy to ensure compliance.
Any third-pary applications must meet all requirements in this policy.
You assume all responsibility for any and all licensing and support implications for the custom applications.
This policy does not apply to any non-Innovation Suite, third-party applications.
Your custom Innovation Suite application responsibilities

Any custom Innovation Suite application that you create using the Innovation Suite subscription is your responsibility.
The following responsibilities are included:
Ensuring that all functional testing of the custom application is performed prior to moving to production.
Ensuring that the custom application continues to function as intended after BMC upgrades the Innovation Suite
platform or other applications.
Notifying BMC Operations about any expected increase in usage.
Ensuring that the custom application does not cause a performance impact or degradation to any other part of
the Innovation Suite service.
Ensuring that the custom application does not impact the availability of the service as measured by the SLAs. For
an overview of the approach to the service availability of OnDemand IT Service Management, see the Innovation
Suite Availability policy (see page 994).
Every custom application should conform to the best practices as defined in the User Guide.
Custom Applications will leverage the certification process to ensure adherence to the best practice guidelines.
Note
There are no Service Level Availability commitments for any custom applications that run in the Innovation
Suite environment.
Custom Remedy application integrations

Your custom Innovation Suite application might require integrations, and as such, require Innovation Suite to interact
with an external application or technology. Such integrations are considered to be non-standard and a customization.
The following general guidelines apply for integrations to a custom Innovation Suite application:

The code created must conform to the same design standards and best practices as outlined in the Innovation
Suite design standards.
Supported external integrations must utilize REST API web services.
Integrations directly to Innovation Suite forms are prohibited.
Any external code (such as plug-ins or hosted components) to facilitate the custom application is not allowed.
Typically, you can implement other methods, such as REST API web services.
Support for custom applications

If you create a support ticket for an issue caused by code in a custom Innovation Suite application, the BMC Service Desk
will provides general information about the customization policy only. Investigating and resolving an issue with a custom
application are solely your responsibility.
As per the customization policy, SLAs do not apply to custom Innovation Suite applications.
Upgrade process
BMC performs periodic upgrades to the Innovation Suite offering. When upgrades occur, you are responsible for
ensuring that your custom Innovation Suite application still functions as intended after the upgrade. All upgrades to the
Innovation Suite service are released in accordance with the Innovation Suite Release Management policy. You will be
given an opportunity to test your custom application in concert with the upgraded service in the Quality Assurance
environment. If issues are detected, you can make changes, test the application in the development environment, and re-
promote the application to the quality assurance environment.
Subscription licensing considerations

Innovation Suite requires that all system users have a valid user license subscription (named) to use any application on
the system. Any end users who are using a custom Remedy application will require a named license. No ratio of user-to-
end-user support exists in the Innovation Suite subscription.
Capacity considerations
Capacity considerations exist for any custom Innovation Suite applications that are hosted in the BMC Cloud.
OnDemand Notification policy

The OnDemand Notification policy addresses target lead times for certain types of notifications. Depending on the type
of event, different contacts may be notified. A summary of the notification type, notifier and notification recipient, and
associated lead time is as follows:
Notification Notifier Notification Minimum lead Notes

type recipient time or
notification
period
Maintenance BMC SaaS Customer 21 days for See also Maintenance notifications (see page ).
- scheduled Operations maintenance production
notification systems
distribution
list

Notification Notifier Notification Minimum lead Notes

type recipient time or
notification
period
7 days for non-

production
systems
Maintenance BMC SaaS Customer ASAP See also Maintenance notifications (see page 999).
- emergency Operations maintenance
notification
distribution
list
New BMC Customer 30 days New version releases for OnDemand services usually follow the on premises product
Innovation Business maintenance release schedule by a matter of weeks. This allows the BMC SaaS Operations team time to
Suite Relationship notification test the release in the cloud environment and certify its readiness for OnDemand
version Manager distribution customer consumption.
releases (BRM) list
Security BMC Customer Within 24 Any type of security incident that affects your data or system is managed by BMC's
incidents Information maintenance hours after Information Systems Security Officer. Notification may come in the form of a phone call
Systems notification validation of and/or email. Only affected customer(s) are notified.
Security distribution the security
Officer list event
BMC- BMC SaaS Customer As soon as the Disaster recovery procedures begin immediately within your contracted Recovery Time
declared Operations maintenance disaster is Objective (RTO).
disaster notification declared by
distribution BMC
list
Disaster Customer BMC SaaS 30 days Disaster recovery testing events are available to Premium Disaster Recovery subscribers
recovery Operations only.
testing
Maintenance notifications
You will receive a system bulletin from the BMC SaaS Operations team if any of the following situations occur:
A sudden downtime in the production environment because Innovation Suite service has stopped functioning
An upcoming planned downtime for Innovation Suite
Upcoming activities such as scheduled go-live announcements, month-end freeze reminders, and shutdown
reminders
This notification might be addressed to a specific subgroup if the application is related to a certain set of users, or it
might be sent as a global notification if an application downtime (or other general announcement) has occurred.
Announcements that address the BMC end user community are of critical importance and are presented clearly and
carefully.
If downtime is required because of an approved change request, a system bulletin is sent a few days before and on the
same day as the change request fulfillment. The bulletin also explains that the scheduled downtime is occurring because
of an approved change request.

Every now and then a BMC-instigated change will require an extension to the change window in order to complete the
request. When this situation arises, BMC SaaS Operations will provide a minimum of 15 minutes notification (prior to the
end of the original scheduled window) to the customer. If an extension is necessary, the change window will be extended
by one hour unless the extension notification states otherwise.
Reminder
All maintenance notifications are sent via email from ondemand_maintenance@bmc.com. These notifications
are sent to individuals on the maintenance notification list supplied by each customer. If you would like to
receive these notifications or need to remove an individual from this list, please contact the BMC OnDemand
Service Desk or your Business Relationship Manager.
OnDemand policy changes

BMC SaaS Operations updates its operational policies from time to time. Minor policy changes are not formally
announced, however you may configure a "watch" notification for any of the policies which you would like to receive
system notifications. To watch a page, select the eye icon in the upper right corner of the page. Any edits done to that
page will push an email notice to you.
Major policy changes, although rare, will be communicated via email to each customer's general notification contact list.
OnDemand Language Support policy

The current version of the Innovation Suite solution supports English language only at this point. Innovation Suite
application can be created to support any UNICODE language.
Note
System data, configuration, and best practice data is distributed with the applications. The system data
supports localization when applicable. Configuration and best practice data is typically distributed in English
only.
Innovation Suite Permissions policy

This topic describes the access permissions that Innovation Suite provides for supported administration levels and
customer environments.
Note
This policy can change from time to time. Be sure to refer to this topic periodically to proactively check the
policy.
Summary of administration levels

The following list describes the administration levels that the Innovation Suite solution supports:

Application Data Administration—Provided through the application user interfaces. A customer can assign user
permissions to users who perform application data administration. An example of application data administration
is setting up support groups.
System Administration—Management of the supporting software, hardware, and infrastructure that provides the
service. Examples of system administration are tuning the operating system, changing hardware parameters, and
allocating indexing on databases. This is reserved for BMC staff only.
Customer environments and administration access

Customers can have different access levels based on the environments they are working in. Customers will have multiple
environments; namely, production, quality assurance, development, and, in some cases, additional environments.
Typically, access to the production and quality assurance environments is tightly controlled to ensure the integrity of the
service. Customers have more latitude in the development environments to facilitate staging changes to their services.
Administration access policy for customers

This section describes the administration access policy for customers, while considering administration levels and
customer environments. The following topics are addressed:
Application data administration
Platform administration
System administration
For the purpose of the following discussion, an additional environment is treated the same as a development
environment.
Application data administration

Customers have full access to configure applications by using Innovation Suite or custom-built administration interfaces.
Platform administration
Customers can change some aspects of the platform in the development environment only
All platform administration in the quality assurance and production environments is performed by BMC Operations only.
System administration
Customers are not provided with access to system administration functions in any environment.
BMC quality of service commitment

The access policy is defined to ensure that BMC can deliver the best service possible. The production environment has
the greatest impact on the customer’s consumers: users and end users. This policy will help BMC and consumers of the
service to experience the following:
Higher quality of service (QoS)

BMC is responsible for the delivery of the service per our contractual commitments. As such, customers are
prevented from modifying the system in any way that could cause instability and unreliability.

Greater consistency
A common approach to the access policy for all OnDemand customers helps to simplify and optimize operations,
leading to proactive and detailed customer communication.
Standardization
Following common industry practices, BMC ensures that changes are introduced to the production services by
using a well-defined and controlled process that progresses through various stages (environments) to ensure
quality of service.
OnDemand Incident Response policy

If service is disrupted in your production environment, the Innovation Suite team restores service as quickly as possible.
After service has been fully restored, BMC provides a Reason for Outage (RFO) document in the following situations:
The disruption resulted in an outage (as defined in the Innovation Suite Availability Policy)
The disruption resulted in significant service degradation (Severity 1) as deemed by BMC Operations
Note
BMC uses the following criteria to identify outages:
The incident impacts Innovation Suite Service
The incident affects at least 20% of a customer's users (for example, 20% or more users
cannot log on)
BMC uses the BMC TMART system as the primary input for determining an outage. BMC might also
take other evidence into account when making such determinations.
Outages do not include performance issues.
If the RFO documentation does not clearly define probable preventive actions, the customer may request a detailed Root
Cause Analysis (RCA) document.
Reason for Outage documents

BMC will provide a Reason for Outage (RFO) document within three business days of the conclusion of an incident. RFO
documents include the following information:
Symptoms observed by the BMC Incident Response Team
Steps taken to mitigate impact or restore service
Preventive actions (when available at the time of RFO document delivery; see Root Cause Analysis documents
(see page 1003) for additional details about preventive actions)
RFO documents are not provided for the QA, development, or sandbox environment. Additionally, the investigation,
determination, and mitigation of a root cause for an incident are not part of the RFO document.

Root Cause Analysis documents

Upon customer request, BMC will deliver a Root Cause Analysis (RCA) document within 20 business days of the
conclusion of an incident. The following information is included in the RCA document:
Timing and duration of the event
Details describing the action taken to restore service
Technical details uncovered during the review of available log data (including an assessment of the root cause)
Recommendations for preventive action
BMC is committed to providing an assessment of the root cause, but an RCA document might not contain any actual
root cause information, because it is not always possible to determine or define a fundamental root cause. RCA
documents are not provided for the QA, development, or sandbox environment.
In some complex outage scenarios, when not enough diagnostic data is available or when BMC is unable to reproduce an
issue, BMC might need to enable additional logging in the production environment to capture diagnostic data.
Innovation Suite Upgrade policy
Release availability
Innovation Suite platform usually have a release per quarter with monthly patches.
You will be notified approximately 30 days before a new release becomes available. The overall goal for the upgrade
process is to ensure that your environments are upgraded to the new release with no impact.
The upgrade process

The table below describes both the actions that BMC performs during an upgrade and the actions that you must
perform during the upgrade, for each phase in the upgrade process. BMC strives to make each platform upgrade non-
invasive as possible to the customer including having limited or no downtime.
Upgrade BMC actions Customer actions
Pre-release
Push new platform release to a sandbox environment that has the Customer tests custom applications based on test
customer’s custom application. framework use cases.
Customer has approximately 30 days to test custom application and Provide feedback to BMC Operations on issues
provide any feedback. encountered.
Production
Upgrade the production environment Communicate issues back to BMC Operations.
PDFs, videos and API documentation

This topic describes and links to PDFs, videos and other documents that support this product release. If the ready-made
PDFs of this space do not satisfy your requirements, you can export a custom PDF.

BMC Confidential. The following information is intended only for registered users of docs.bmc.com.
Ready-made PDF of this space

The following table provides ready-made PDF that contain snapshots of the content in this space. Ready-made PDF
is created for new releases and service packs at the time of their release. Although this PDF contain all topics, the
content of some topics is better suited for online viewing.
Snapshot Date File size
BMC Helix Innovation Suite 18.11.01 December 19, 2018
BMC Helix Innovation Suite 18.11 November 30, 2018 39,516 KB
BMC Helix Innovation Suite 18.08.01 October 18, 2018 39,485 KB
BMC Helix Innovation Suite 18.08 September 14, 2018 35,860 KB
BMC Helix Innovation Suite 18.05.01 July 29, 2018 35,884 KB
BMc Helix Innovation Suite 18.05 June 6, 2018 35,485 KB
BMC Confidential. The preceding information is intended only for registered users of docs.bmc.com.
API documentation
The following table lists API documentation that are not available as topics in the documentation portal.
Title Date File size
Platform REST API Documentation December 19, 2018 662 KB
Platform Application Java API Documentation December 19, 2018 1,430 KB
Platform Service Java API Documentation December 19 , 2018 3,950 KB
Platform JavaScript API Documentation December 19 , 2018 312 KB
Note
You must not use any JavaScript API that is not documented in the JavaScript doc. Such APIs are not
guaranteed to remain or to be kept backward compatible.
Videos
The following table lists topics that contain videos that supplement or replace the text-based documentation.
Topic Duration Description

(in
minutes)
Integrating with REST services in a codeless way (see page 8:43 This video demonstrates how to integrate with JIRA REST API service.
604)
https://youtu.be/n2X0YUTJ_68
9:17


(in
minutes)
Integrating with another application by using a connector This video demonstrates how to use the JIRA connector to modify the conversation
(see page 615) flow in BMC Helix Chatbot.
https://youtu.be/qDxSOeS9I6w
Developing codeless applications (see page 794) 8:01 This video demonstrates how to develop a codeless application.
https://youtu.be/T2C7h3NdejA
Registering a record (see page 543) 2:56 This video demonstrates how to register a record definition.
https://youtu.be/Pzh9jgPyN9U
Configuring self approval flows (see page 544) 3:18 This video demonstrates how to configure self-approval flows.
https://youtu.be/dzxE5es3sNg
Configuring approval flows (see page 546) 4:43 This video demonstrates how to configure approval flows.
https://youtu.be/6b5TWcQmzbc
Creating an approval process (see page 537) 7:30 This video demonstrates how to create an approval process.
https://youtu.be/s4RcufyJQJ8
Setting up your IDE and installing BMC Helix Innovation 4:20 This video gives an overview of the list of components required to develop the
Suite SDK (see page 800) application and how to setup the Integrated Development Environment (IDE).
https://youtu.be/5mzWv7y3_3s
5:41 This video provides details on how to create a maven project using BMC Helix
Creating a Project using Maven and the Archetype (see Innovation Suite SDK and IDE and how to deploy the project to your system.
page 806)
https://youtu.be/_aXeUOGRlNY
Deploying your Digital Service application for the first 5:07 This video provides details on how to deploy the Maven project to BMC Helix
time to start working in Innovation Studio (see page 813) Innovation Suite server.
https://youtu.be/A7B6xXoElw0
6:52 This video helps you to customize the application by modifying the definitions on
Creating the definitions for a tailorable Digital the application using BMC Helix Innovation Studio.
Service application (see page 323)
https://youtu.be/bVvcC6IKaLA
3:48 This video gives and overview on how to package the application for deployment.
Getting your Digital Service application ready for use (see
page 915) https://youtu.be/2-DQ8l_Cy5Q
Overview of process to upgrading to a new version of an 2:15 This video gives an overview of the process of upgrading to a new version of an
application with zero downtime (see page 286) application with zero downtime:
https://youtu.be/d-Ae2JkKIUE
Enabling Skype for Business in a chatbot application (see 3:56 This video provides the process overview to enable Microsoft Office 365 Skype for
page 594) Business as a communication channel in a chatbot application:
https://youtu.be/sCH59t-gVEo
BMC Helix Innovation Suite 18-02 enhancements 5:26 This video provides information about the updates made on BMC Helix Innovation
Suite platform, such as the following:
Chatbot framework support for multiple chat providers


(in
minutes)
BMC Helix Innovation Suite Cognitive Service updates including increased

limit of training data sets
Localization support for certain field names and Foundation category names
Approval library updates such as leveraging Foundation data to assign

approvers and more readable Approval record definitions
Row-level security for roles from multiple applications
Remedy SSO OAuth 2.0 support for BMC Helix Innovation Suite applications
https://youtu.be/N0spVe_jEbk
17-11 enhancements - Leverage cognitive capabilities in an 1:19 This video provides information about BMC Helix Innovation Suite Cognitive Service.
application
https://youtu.be/cYOjy-CfH5Q
17-11 enhancements - Chatbot framework and Cognitive 2:30 This video provides information about the Chatbot framework and the Cognitive
Search Service Search Service.
https://youtu.be/mSgBU2iEE-U
17-11 enhancements - Platform enhancements 1:17 This video provides information about the updates made on BMC Helix Innovation
Suite platform, such as the following:
Remedy Single Sign-On OAuth 2.0 authorization
Operation Id parameter
https://youtu.be/HiBrPqwACc0
Adding cognitive capabilities to a custom application (see 3:57 This video provides the process overview to use the BMC Helix Innovation Suite
page 552) Cognitive Service in your application.
https://youtu.be/k72xCJlvqK8
BMC Helix Innovation Suite 17.8.0 - Integration 1:25 https://youtu.be/_imlenurwfc

enhancement
This video provides information about connectors.
BMC Helix Innovation Suite 17.8.0 - Support for creating 1:00 https://youtu.be/vvAfkgcFYp0
codeless applications and libraries
This video provides information about creating codeless applications and libraries
BMC Helix Innovation Suite 17.8.0 - Deploying applications 0:56 https://youtu.be/M7XcL3ym_dc

across environments
This video provides information about deploying applications across environments.
BMC Helix Innovation Suite 17.8.0 - Interface design 2:21 https://youtu.be/Qh02kIo3dJ0

enhancements
This video provides information on the updates made on BMC Helix Innovation
Studio interface, such as the following:
Displaying associations in a drop-down list
Adding attachments to processes
Copying a view definition
Filtering record definition grid
Creating install packages to deploy entire applications 4:20 https://youtu.be/3h1cXnvRkh8

(see page 766)
This video provides information about creating install packages, so that you can
deploy entire applications by using BMC Helix Innovation Studio.


(in
minutes)
Creating update packages to deploy incremental changes 4:20 https://youtu.be/oBcglgR59I0

of applications (see page 769)
This video provides information about creating update packages, so that you can
deploy incremental changes of applications by using BMC Helix Innovation Studio.
Creating export packages to deploy tailoring changes of 3:37 https://youtu.be/gAwdNleOZqU

applications (see page 775)
This video provides information about creating export packages, so that you can
deploy tailoring changes of applications by using BMC Helix Innovation Studio.
Creating a view for associating records (see page 401) 1:52 https://youtu.be/dJPbXfdijMg
This video demonstrates an example of how to create view based associations.
https://youtu.be/ZwSiBI4lKL8
This video demonstrates an example of how to create drop-down based

associations.
BMC Helix Innovation Suite 17.5.0 - Upgrade 1:10 https://youtu.be/3_HE9e9K61o

enhancements
This video describes the upgrade enhancements in BMC Helix Innovation Studio.
BMC Helix Innovation Suite 17.5.0 - Data security and 3:26 https://youtu.be/ADLtYNHCW-s
performance enhancements
This video describes the data security and performance enhancements in BMC Helix
Innovation Studio, such as the following:
Secure data access through hierarchical groups
Audit updates to record definitions
Cache application data by using the Data Caching Service
BMC Helix Innovation Suite 17.5.0 - Debugging and 1:25 https://youtu.be/f8Epo26hgPQ

troubleshooting enhancements
This video describes the debugging and troubleshooting enhancements in BMC
Helix Innovation Studio, such as the following:
Improved application logging
Error handling in Process Designer
Client automation testing
BMC Helix Innovation Suite 17.5.0 - Tenant administration 2:46 https://youtu.be/CZ2swoY7tbI

enhancements
This video describes the tenant administration enhancements in BMC Helix
Innovation Studio, such as the following:
Load foundation data in bulk
Out-of-the-box Geography data
Grant application permissions by using Functional roles
BMC Helix Innovation Suite 17.5.0 - Rule designer 1:04 https://youtu.be/1TaeT7aE-iM

enhancements
This video describes the enhancements to the Trigger component in the rule
designer.
BMC Helix Innovation Suite 17.5.0 - API enhancements 1:08 https://youtu.be/i9_h4TfkZ_c


(in
minutes)
This video describes the API enhancements in BMC Helix Innovation Studio, such as
the following:
• Ability to leverage Foundation data in Digital Service application
• Ability to include and update approval requests in Digital Service application
BMC Helix Innovation Suite 17.5.0 - View designer 1:58 https://youtu.be/UdNHxSygZks

enhancements
This video describes the enhancements to the view components such as Record
Grid, Select Group component, and Action button.
BMC Helix Innovation Suite - powerful development 1:17 https://youtu.be/nMqH9yudyIM

platform
This video provides a quick overview to BMC Helix Innovation Suite.
Quick and easy application development experience 2:09 https://youtu.be/MYp23R8zKU0
This video explains how BMC Helix Innovation Suite can provide quick and easy
application development experience.
Easy to use Foundation library 0:58 https://youtu.be/6ChoDcSEV_Y
This video describes the new features available with Foundation library in BMC Helix
Innovation Suite.
Process and Rules designer enhancements 1.21 https://youtu.be/u3Pc_rN4nn4
This video explains the new and powerful Process Designer and Rules Designer.
Faster branding and skinning of your applications 0:53 https://youtu.be/5L8hAKMcq7k
This video explains what's new in skinning and branding using BMC Helix Innovation
Suite.
Quick and easy services management 1:05 https://youtu.be/zUhvR8GtUzg
This video explains how easily a SaaS Administrator can manage services using BMC
Overview of developing an application (see page 798) 3.52 https://youtu.be/N8ew_BwdbPY
This video explains the various concepts and architecture details of developing an
application in BMC Helix Innovation Suite.
Creating record definition (see page 329) 2:09 https://youtu.be/-QWpuvC4hNs
This video demonstrates how to create record definitions.
Inheritance in records (see page 338) 1.59 https://youtu.be/WE7xvdsepaA
This video explains concept of inheritance in records and shows steps on inheriting
properties from one record to another.
Using the select group component (see page 396) 1.46 https://www.youtube.com/embed/EcMrG5AyzWg
This video explains using select group component in a view definition.
Creating view definition (see page 378) 2.39 https://www.youtube.com/watch?v=IJOSEigTYJY
This video explains how to create view definitions in BMC Helix Innovation Studio.
Creating complex view layouts (see page 378) 1:43 https://youtu.be/bG9J1F1xlNE
This video explains how to create complex view layouts.


(in
minutes)
Creating associations (see page 342) 1:24 https://youtu.be/9bOObkK2Kx8
This video demonstrates how to create association between records.
Adding permissions to record definition (see page 329) 1:00 https://youtu.be/y0UEfO4PKJU
This video demonstrates how to add user permissions to a record definition.
Action buttons (see page 384) 1:05 https://youtu.be/T93mxH2G118
This video demonstrates how to use action buttons to a view definition.
Named list definition (see page 417) 1:38 https://youtu.be/pHWJ0IpwlZA
This video explains how to create a named list definition.
Using the Expression editor (see page 378) 2:03 https://youtu.be/LAY–nBT5rs
This video demonstrates how to use the expression editor.
Using menu item (see page 519) 3:10 https://youtu.be/genwa5EUdok
This video demonstrates how to use the menu item in shell.
Using record editor (see page 396) 2:07 https://youtu.be/JvZSHbE6fAg
This video demonstrates how to use record editor to a view definition.
Using Data editor (see page 346) 1:56 https://youtu.be/gehTnBcqAZk
this video demonstrates how to create record instances using Data Editor.
Rule designer (see page 490) 1:34 https://youtu.be/Gd2lifwL-AA
This video demonstrates various sections and functions of the rule designer
interface
Localizing a Digital Service application (see page 968) 6:07 https://youtu.be/KcsJPaeI510
This video demonstrates how to localize an application.
FAQs and additional resources

This topic provides information that supplements the BMC Helix Innovation Suite documentation.
Frequently asked questions

This topic provides answers to frequently asked questions (FAQs) about BMC Helix Innovation Suite.
What can you do by using Sandbox?
Design and develop your innovative ideas
Build tailorable definitions for your app so that it can be safely customized by your end users
String together the UI of your application
Define your data model and relationships

Configure and tailor existing apps using BMC Helix Innovation Suite
Create new workflows, processes or UI using designers
Design and develop new custom components
How do I set account usernames and passwords?
When you first request a Sandbox (on the Developer Portal), you are provisioned two accounts, developer account and
administrator account. By default, the developer account is developer and administrator is admin (as shown in the image
below). You can specify the account names and passwords.
You can changes the usernames for these accounts and specify the passwords for these accounts. The passwords you
specify must meet the following criteria:
Passwords must consist of at least one uppercase character and at least one lower case character.
Passwords must consist of at least one numeric value.
Passwords must consist of at least one special character (any of the following special character ~!@#$%^&*_-).
The length of the passwords must be between 8 to 30 characters.
If I am a BMC customer, do I need to sign-up for the Developer program?
Yes, you still need to sign-up for the program to ensure you benefit from the exclusive Developer content and the
Personal Sandbox that will be available only as part of the program.
Do I need to be an existing BMC Customer or Partner to be part of the program?
No, that is not a pre-requisite to sign up for the program.
Can I deploy the application I built in the sandbox into production?
The personal sandbox you get is only a Development Environment. This does not have a Production Environment with a
run-time available to deploy applications in the cloud at this time.
How long do I have access to the sandbox?

You have unlimited access to the sandbox as long as you use it. The sandboxes will be reclaimed by BMC if there is a
week's worth of inactivity. You will have to request a new sandbox once your sandbox has been reclaimed.
How do I reset developer password?
You can reset the developer password by using Sandbox details page.
1. On the Sandbox details page, navigate to Manage Your Sandbox > RESET PASSWORD, click RESET PASSWORD.
2. Select Innovation Suite Developer, enter the new password, and reset the password.
The following image shows the Manage Your Sandbox section:
How do I set the required language for Innovation Studio?
BMC Helix Innovation Suite supports the following languages:
German (de)
Japanese (ja)
Russian (ru)
Spanish (es)
French (fr)
Italian (it)
Korean (ko)
Brazilian Portuguese (pt-br)
Chinese (zh-cn)
Swedish (sv)
Dutch (nl)
The following table describes how users can select the required language from various browsers:

Browser Operating System Steps to change the language
Google Windows, apple Open Settings, search for language settings, and add the required language.
Chrome MacOS
Mozilla Firefox Windows, apple Navigate to Open Menu and click Options. Search for language settings and add the required language.
MacOS
Edge Windows In Control Panel, in the Clock, Language, and Region option, add the required languages in the order of preference.
You must download the install pack of the added languages and then restart the computer.
BMC Helix Innovation Suite also provides localized error messages in the supported locales.
How do I reset Foundation Data user password?
You can reset the Foundation Data user password by using BMC Helix Innovation Suite.
1. Log in to BMC Helix Innovation Suite as a developer.

For more information about the roles and their permissions in BMC Helix Innovation Studio, see Roles and
permissions (see page 743).
2. On the Administration tab, click Administration > Foundation Data > Manage People > All People.
3. Select the user for whom you want to change the password, click Edit, and navigate to the Basic tab.
4. On the Basic tab, click Access Details.
5. In Password, enter the new password, and click Save.
How do I unlock an account?
If you encounter the error ERROR 624 User account locked, when you login to BMC Helix Innovation Studio, navigate to
he Sandbox details page, and click Unlock Account.
How are test metrics calculated for Innovation Suite Cognitive Service?
Example of how cognitive test metrics are calculated

You have created a data set to test whether BMC Helix Innovation Suite Cognitive Service can categorize appropriate
service requests in Category A and Category B. The following table indicates the number of expected and predicted
categories:
Expected Category A Expected Category B Total Predictions of expected

categories
Predicted Category A 8 4 12
Predicted Category B 2 6 8
Total predictions for A and B 10 10 20
Based on the above results, the accuracy, precision, recall, and F-score for Category A and Category B are calculated as
shown in the following table:

Test metrics Category A Category B
Accuracy 8/10 = 0.8 6/10 = 0.6
Recall 8/10 = 0.8 6/10 = 0.6
Precision 8/12 = 0.67 6/8 = 0.75
F-score 2* (0.80*0.67)/ (0.80 + 0.67) 2* (0.60*0.75) / (0.60 + 0.75) = 0.66
The consolidated results for BMC Helix Innovation Suite Cognitive Service for Category A and Category B are calculated
by using the weighted macro average as shown in the following table:
Test metrics Formula Result
Accuracy 10/20*0.80 + 10/20*0.60 0.70
Recall 10/20*0.80 + 10/20*0.60 0.70
Precision 10/20*0.67 + 10.20*0.75 0.71
F-score 2*(0.70*0.71) / (0.70+0.71) 0.70
Note
For multi-class categories, Accuracy and Recall that is computed for each category and the consolidated
calculation for BMC Helix Innovation Suite Cognitive Service are the same.
What do I do when I get the error 'You are not authorized to access Innovation Studio?'
If you encounter the error You are not authorized to access Innovation Studio when you log in to BMC Helix Innovation
Studio, use your developer account to log in. This error occurs when you try to log in to BMC Helix Innovation Studio by
using an administrator account.
What do I do when Innovation Studio locks constantly?
If you encounter the following error even if you do not have any failed login attempts:
ERROR (624): User account locked out due to too many failed login attempts. Please contact your
Administrator.; developer
In this case, you should create a new account in BMC Helix Innovation Studio and use the account for development. To
create a new account, perform the following steps:
2. Navigate to Administration > Configure My Server > People > Manage User Accounts.
3. Create a user with Administrator permissions and a fixed license.
How do I access database record and transaction record in a process?

To access the transaction record of a rule, you can use record as the process input, and have rule call process
and pass the transaction record. See Working with rules (see page 490).
To get the database value of a record, you can use Get Record action, and access the database value using the
activity results of the Get Record action. See Get Record action (see page 457).
How to use transaction (TR) field or DB field in rule qualification?In rule qualification, you can use the function
NEWVALUE() for TR field and the function OLDVALUE() for DB field. See Working with rules (see page 490).
How do I create display only field to store action results?
You do not need the display only field to store the activity results. In a process, you can get the activity results in the
following ways:
You can use the expression ${activityResults.<activityGUID>.xxx> to access an activity output.

All activity results are stored in the process context and can be accessed anywhere.
If an activity is not executed, you get an empty value.
If an activity returns a record (that is Get Record Service Task), only the record identity (record ID and record
definition name) is persisted to the process context. Record field values are not persisted to the process context.
If you access field values of Get Record Service Task, you get the latest database value of the record. See Get
Record (see page 457).
You can use the activity Output Map to store activity result in a process variable.
How does a process transaction works in process runtime?
When a process is started through an API (Record API triggers rule, which starts the process or Start Process API),
process transaction starts at the REST APIs.
The process transaction joins the API transaction and the process runs till its completion or it is goes to a wait step. Wait
steps are User Tasks or Receive tasks. When the process reaches a wait step, it persists all the transaction values and
returns from the wait state. When the process resumes the execution from a wait step, the process transaction
continues till it completes or reaches the next wait step. The records, signal inputs, process operations, process context,
and the wait state information are all persisted in one transaction.
For more information on APIs, see API documentation (see page 1003).
For more information on User Tasks and Receive tasks, see Activities (see page 434).
How are process instances managed?
Process instances are managed by the platform and third party process engine Activiti. The platform manages process
context and Activiti engine manages process instance state information.
Process context consists of process variables and process activity results.
Process instance state information consists of process current activity, start time of a process, and end time of
completed process activities.

For process context, there is a form to store active process instances, and a form to store completed process instances.
The archive policy of completed process instances is that all completed process process instances are moved to an
archive form after three months. Process instance state information follows the similar pattern.
How does a process instance resumes from User Task?
The condition to resume a process instance from User Task is specified in the Completion Criteria property of User Task
(process designer element). Completion Criteria specifies the condition when the user task is considered as complete . T
he condition is an expression that evaluates fields of a task record.
The platform service EntryEventNotificationService is used to monitor registered record events. User Task uses
EntryEventNotificationService to monitor the task completion. Records that need to be monitored are registered
in the Entry Event Registration system form and the Notifier Listening field is set to true.
When a record event occurs, the EntryEventNotificationService evaluates the record instance condition and if
the condition is true, the Pending Notification flag is set.
A background thread notifies event listeners of all pending notification records with the Notification Information
provided by the record event register. When the listener is notified, the record event is cleaned up from the
registration form and the Notifier Listening flag is reset. Event listeners are notified by a separate pool of threads
where the pool size can be configured.
Where are my overlay objects?
To make the platform operational in varied customer environments, the way you customize objects in core BMC
applications has changed from 17-02 onwards. You can customize the objects developed in your own applications, but
you cannot customize the objects developed in com.bmc.arsys. For example, objects in core BMC applications like
Foundation, Approval, and Assignment cannot be customized. Y ou cannot customize the record definitions by updating
the permissions or adding security labels, adding or updating record fields, and so on. Therefore, you must delete the
customizations and then perform the upgrade the BMC Helix Innovation Suite. If you attempt to customize any objects
developed in core BMC applications, you encounter the following error message:
If you attempt to customize any objects developed in core BMC applications, you encounter the following error message:

Why are the required Default Tenant field values displayed empty?
In BMC Helix Innovation Suite, you may find the required fields of the Default Tenant (Administrator > Configure My
Server > Manage Tenants) such as Domain Identifier and Virtual Host Name are empty. This is because the default tenant
fields are imported during the platform creation and when you use tools such as data import there is an option to not
trigger the required field check.
I am unable to export a licensed application that includes definitions and data? What do I do?
If you are working on a dedicated system, ensure that you have assigned the application license to yourself using the
Foundation Person UI. For more information, see Creating or modifying Person data (see page 664).
I am unable to see my licensed application. What do I do?
To see a licensed application, you must have that application license assigned to you using the Foundation Person UI. For
more information, see Creating or modifying Person data (see page 664).
Application upgrade FAQs

How do I enable logging for applications that are created by using BMC Helix Innovation Suite 17.02 or earlier?
The logs for applications created using the BMC Helix Innovation Suite SDK 17.02 or earlier are stored in the arextension.
log file located at the following location:
Windows: <ARSystemInstallDir>\Arserver\Db
UNIX: <ARSystemInstallDir>/Arserver/Db
By default, only error messages are logged. If you want to log all messages (debug, info, warning, and error), you must
change the log level to debug in the logback_server.xml file. The following configuration enables debug log level:
<logger name="com.bmc.arsys.server.extension.impl.LogServiceImpl"
level="debug" additivity="false">
<appender-ref ref="AlwaysOnLog" />
<appender-ref ref="ExtensionLog" />
</logger>
Note

When you make changes to the logback-server.xml file, you do not need to restart the Remedy AR System
server. After making the changes to the logback_server.xml file, you must reload the file by using the Reload
Log Conf File option in the Server Information form on the Log Files tab.
The logback logging framework provides this logging functionality.
Additional resources
The Developer community site provides information outside of the BMC Helix Innovation Suite documentation that
you might find helpful.
The Securing BMC Helix Innovation Suite against web and CSRF attacks (see page 1022) topic provides information about
the WhiteHat Sentinel PE security penetration testing and protection against CSRF attack vulnerability.
The following BMC sites provide information outside of the BMC Helix Innovation Suite documentation that you might
find helpful:
BMC Helix Innovation Suite Product Support
BMC Helix Innovation Suite subscription
BMC Helix Innovation Suite community
BMC Helix Innovation Suite Knowledge Base
BMC Helix Innovation Suite YouTube playlist
BMC Helix Innovation Suite marketplace
BMC Helix Innovation Suite podcasts
Types of expressions in expression editor

This topic provides information about expressions that you can build by using the Expression Editor.
Terminology
JavaBean Expression (see page 1017)
Assignment (see page 1018)
Condition (see page 1018)
JavaBean Expression
The expression we introduced in BMC Helix Innovation Suite is called JavaBean expression. The syntax is based on UEL
(Unified Expression Language), and used in JSP 2.0 (Java Server Page). The word "JavaBean" comes from JSP where it
uses the expression to access JavaBeans. The dots in the expression is to navigate to properties of the bean. Notation
"${}" is used to dereference the expression to a value.

Assignment
Assignment is about assigning some value to a target. It has an assignment target and a value expression. Both can be
JavaBean expressions. The value expression can have arithmetic operations (+, -, *, /, %), with each value expression
surrounded by dereference notation "${}",
Condition
The expression for the condition has to be evaluated to a boolean value- true or false. Condition expression can have
arithmetic operations (+, -, *, /, %) on value expressions; relational operations (>, <, =, !=, >=, <=) on value expressions; and
logical operations (AND, OR, NOT) on relational operations.
BMC Helix Innovation Suite JavaBean Expression Syntax

Context Indicator (see page 1018)
Items in a collection (see page 1020)
Associated record instances (see page 1020)
Keywords (see page 1020)
Supported Data Type (see page 1021)
Context Indicator
In the value expression, the first part of the expression is the context indicator. Here are context indicators we support
today, and how they are used:
processContext
The value is from a process variable, which can be process input, output or local variable. If the variable is a non-primitive,
i.e. record instance or a java object, you can use "." to navigate to fields/properties of the non-primitive object.
Syntax Example Notes
${processContext.<variable ${processContext. "Ticket ID" is the name of the process variable

name or id>...} Ticket ID}
${processContext. "Task" is a process variable. it is a Record Instance type. This expression resolves to Task variable's
Task.4} Assignee field (field id 4).
activityResults
The value is from the result of a process activity.
${activityResults.<activity definition ${activityResults.<GUID>. The expression evaluates to the Service Task output.
GUID>.output...> output}
${activityResults.<GUID>. The activity in this example is Service Task "Service Level Calculation".
output.timeToResolve}
The expression evaluates to the calculation result. The result is a compound java
object, so we can use "." to refer to its properties.
${activityResults.<GUID>. The activity in this example is Service Task "Get Records By Query", so the output is a
output[0].8} list of record instances.

This expression resolves to the first record instance's Description field (field id 8).
${activityResults.<activity definition ${activityResults.<GUID>. The activity in this example is Approval Process, which has "Approval Status" as the
GUID>.<process output variable name Approval Status} = \" process output. This condition expression checks if the approval status is "Approved"
or id>...> Approved\" or not.
userTask
This context is only applicable to Process UserTask completion condition. It resolves to the UserTask record instance.
${userTask.<userTask field name or Id ${userTask.Status} = \" This expression checks if the status of user task record instance is changed to
>} Reviewed\"" "Reviewed".
If the condition is true, the User Task is completed, and the process instance
resumes.
ruleContext
the value is from the record instance that triggers the rule.
${ruleContext.<field name or Id>} ${ruleContext.Status} = \"New\" This expression checks the Status field of the record instance that triggers the rule
actionResult
the value is from the result of the current rule action.
${actionResult.output.<property name>} ${actionResult.output. This expression resolves to the rule action output.
timeToReview}
The output is a compound java object, so we can use "." to refer to its properties.
${actionResult.<process output variable ${actionResult.Approval The action in this example is Start "Approval Process". The process has "Approval
name or id>...} Status} Status" as the process output.
recordContext
the value is from the record instance that the grid is operating on.
${recordContext._associations.<association definition GUID>.< ${recordContext._associations.<association The expression refers to the record

node side>[index].<field id>} definition GUID>.nodeB.[0].8} instance in the record grid
view
The value is from a view component
${view.components.<view component ${view.components.<GUID>. This expression resolves to the ID field of the first selected row of a record
GUID>..} 379} grid.

Items in a collection
List
we use "[]" notation with numerical index. For example, output[0]
Map
we use "[]" notation with the map key being a string. For example, values["Short Description"]
Associated record instances

From JavaBean point of view, when two record instances are associated, the associated record instance can be
interpreted as the property of the first record instance. For example, when Employee record is associated with
Department record, we can also interpret Department being a property of Employee. Therefore, using JavaBean
expression, we can naturally navigate from one record instance to associated record instances.
${<record>._associations. ${processContext.Task._associations.<association Task and Customer are associated.

<association definition GUID>. definition GUID>.nodeA[0].10001995})
<nodeSide>} This expression navigates from Task record instance to the
associated Customer record instance.
${activityResults.<activity definition GUID>.output. The record here is from an activity result, and the activity is
_associations.<association definition GUID>.nodeA[0]. GetRecord. The association expression is the same as the
10001995} above.
${recordContext._associations.<association definition The record here is from a record grid. The expression is able
GUID>.nodeB.[0].8} to bring fields of associated record into the grid.
Keywords
Keywords can be used in the expression. They are resolved to a value during the runtime. Keywords are available under
the "General" subtree of the expression dictionary UI. Here are supported keywords in BMC Helix Innovation Suite, and
the value each keyword is resolved to. Some of the keywords are only applicable to a particular definition.
Current Date
This keyword resolves to the current date, and the time defaults to midnight.
Current Date and Time

This keyword resolves to the current date and time.
Current Group IDs

This keyword resolves to the list of the group IDs of which the current user is a member. If there are no groups, the value
is an empty string. If there are groups, the value is a string displayed in the following format:;<groupID>;<groupID>;
<groupID>;
Current Groups
This keyword resolves to the list the group names of which the current user is a member. If there are no groups, the
value is an empty string. If there are groups, the value is a string displayed in the following format: <groupName>
<groupName> <groupName>

Current Operation
This keyword resolves to the current record operation. This keyword is only applicable to a rule definition.
Current Record
This keyword resolves to the current record rule is operating on. This keyword is only applicable to a rule definition.
Current Record Definition Name

This keyword resolves to the current record definition name. This keyword is only applicable to a rule definition.
Current Roles
This keyword resolves to names of the list of roles that map to groups to which the current user belongs. If there are no
roles or no mapped groups, the value is an empty string. If there are mapped roles, the value is a string displayed in the
following format: <roleName> <roleName> <roleName>
Current Server URL

This keyword resolves to the URL of the current server. It is in the format of http://<hostname>:<port> or
https://<hostname>:<port>, depending on if SSL is configured or not. The host name here is the server external name,
which is visible outside of the firewall.
Current Time
This keyword resolves to the current time.
Current User
This keyword resolves to the current logged in user.
Current User Locale

This keyword resolves to the language and country code for the current logged in user. It is in the format of
<language>_<countryCode>
Current Week Day

This keyword resolves to the current day of the week
Process Correlation ID
This keyword resolves to the process correlation id. The correlation id can be used to uniquely identify a process
instance execution. If the process is in a parallel execution through parallel gateway or parallel multi-instance loop, using
this keyword in the parallel path, it generates separate correlation id to identify each execution path. This keyword is only
applicable to a process definition.
Supported Data Type
Expression supports all Rx data types except Attachment. The supported data types are Integer, Floating, Decimal,
Selection, Boolean, Date, Date/Time, Time, Text.
Process expression and rule expression supports Record Instance, Custom Java Object (developer defined Java
object).

Action supports Map and List as the Action input parameters, but with restrictions. The restrictions are the
following:
Map
Map key being a constant, but map value is an expression. the key value pairs are itemized explicitly:
The JSON of the action definition input map

{
"assignTarget": "values[\"Description\"]",
"expression": "${processContext.name}"
},
{
"assignTarget": "values[\"Submitter\"]",
"expression": "$USER$"
}
FooServiceImpl.java:
@Action()
public RecordInstance createSomething(
@ActionParameter(name = "values") Map<String, String> values) {
...
}
An action that returns a map can be used as the map input of the next action.
List
A comma separated string can be used as the input value for List<String> parameter.
An action that returns a list can be used as the list input of the next action.
Securing BMC Helix Innovation Suite against web and CSRF attacks
The following topics contain information and instructions on BMC Helix Innovation Suite security planning:
Action Reference
Understand the security penetration tests done by BMC Helix Innovation Suite. Protection against CSRF attack vulnerability
By the security penetration testing, BMC identifies whether applications are vulnerable to web attacks and
implements the required countermeasures to reduce any vulnerabilities.
Understand the protective measure used by BMC Helix Innovation Suite against cross-site request forgery Protection against CSRF attack vulnerability
(CSRF) attacks. (see page 1022)
Protection against CSRF attack vulnerability

BMC Helix Innovation Suite includes a protective measure against cross-Site request forgery (CSRF) attacks. To address
the CSRF security risk, BMC Helix Innovation Suite uses custom request header for every REST API request in the
Innovation Software Development Kit (SDK).
What happens in a CSRF attack?

In a CSRF attack, users are forced to execute unwanted actions on a web application in which they are currently
authenticated.

If the victim holds a regular user account, a CSRF attack can force the user to perform state-changing requests, such as
transfer funds, and change the email address. If the victim holds an administrative account, the attack can compromise
the entire web application. For more information, see Cross-Site Request Forgery (CSRF) at the OWASP website.
To protect against this vulnerability, BMC Helix Innovation Suite has an HTTP header for every cross-origin request.
How does BMC Helix Innovation Suite handle a CSRF attack?

BMC Helix Innovation Suite has used a custom request header for every REST API call in the Innovation Software
Development Kit (SDK). This defense relies on the Same-Origin Policy (SOP) restriction that only JavaScript can be used
to add a custom header, and only within its origin. By default, web browsers don't allow JavaScript to make cross-origin
requests.
The following custom header is added to BMC Helix Innovation Suite SDK:
X-Requested-With: XMLHttpRequest
If you are initiating your own HTTP requests, you can add the X-Requested-With header by specifying the following
values:
``` myAppModule.config(['$httpProvider', function($httpProvider) { $httpProvider.defaults.headers.common["X-

Requested-With"] = 'XMLHttpRequest'; }]); ```
For more information, see Downloading and installing Innovation Suite SDK (see page 805).
If the header is not found, a Response.Status.BAD_REQUEST response is returned to the client.
If you use a generic HTTP request client in your development and testing, ensure that the custom request header is
included with every request; otherwise, you will get a BAD_REQUEST response.

1
18 08 14
a
absolute timeout 880
access 65, 421, 497, 632, 980
accessibility 320
access innovation suite 59
access reporting 528
access url 59
account 782
account locked out 980
accuracy 283
action button 134, 376, 377, 384, 860
action for dialog 587
actions 823, 860
activities elements 434
add 262, 421, 446, 590, 756
add attachments 396
add data 775, 777
adding 759
adding filters to record grid 378
additive 204
add permission 529
add template 685
admin 743
administration 59, 321, 505, 632, 710, 742
administrator 275, 321, 735, 743, 747, 779, 782
advanced 677
agent 650
alert box 860
alias 623
allow 43
allow customization 515
analyst 664, 743
ancestor 360
ancestor security label 362, 370
angularjs 202, 826
angular objects 869
angular service 867
angular service examples 867
annotate 823
annotation 429
annotations 447

anonymize 739
api 880, 884, 896, 1003
api connection 609
api docs 1003
api documentation 1003
application 14, 27, 33, 36, 43, 66, 68, 97, 202, 270, 277, 286, 292, 313, 319, 320, 323, 515, 554, 590, 632, 759,
779, 794, 798, 799, 815, 818, 915, 965, 980, 981
application bundle 37
application business analyst 747
application capabilities 636
application components 37
application concepts 36
application data 559, 562
application design 90
application development 794
application error 992
application integration 615
application issues 782
application license 632
applications 36, 535
application scenario 68
application switcher 519, 523, 526, 533
application upgrade 27
apply 818
apply translations 968
approval 536, 537, 549, 881
approval api 886, 887, 888, 889, 890, 891
approval apis 884, 889
approval console 376, 377, 550
approval details by user id 887
approval flow 47
approval flows 536, 543, 546
approval library 322, 535
approval notifications 549
approval process 47, 536, 537, 546
approval request 550
approvals 47, 322, 535, 543, 544, 546, 550
approve 550
archetype 214, 794, 798
architecture 39
ar system 742
artifactid 27, 806
assign 362, 632, 664, 744
assign business analyst 664
assign business analyst role 664
assignee not found 988
assignment 535, 623, 625, 629

assignment calculator 570

assignment engine 478, 623
assignment failed 988
assignment method 625
assignment policy 623, 625
assignment policy disabled 988
assignment policy failed 988
assignment process 478, 623
assignment record definition 623
assignment rule 623
assignment rules 625
assign permissions 529
assistant 590
associate 183, 417
associate records 342, 384
association 108, 186, 297, 342
associations 41, 126, 323, 396, 401, 468, 654, 657, 658, 673, 675, 677, 679, 681, 682, 692
atrium core 742
atrium integrator 710
attach file to process 448
attachment 448
attachment in process 448
attachment parameter 448
attachments 289, 756
attachment size 289
attributes 497
audit 351, 721
audit associated fields 351
auditing 351
authentication 604, 609
authorization 604, 609
authorization error 980
authorization rest api 911
auto approval 47
auto assigning 629
auto assignment 478
auto assignment java program 570
auto categorization 478
automated 255
automatically 261
automation 27, 918, 930, 942
automation framework 27, 918, 930
automation framework example 930
automation framework ui 27
automation methods 927
automation project 918
automation ui framework 945

availability 994
azure 594
b
ba 30, 275, 277, 322, 323, 329, 335, 351, 360, 362, 370, 373, 401, 415, 442, 623, 625, 629, 664, 743, 750, 763, 765, 766,
771, 773, 775, 794, 794
basetest class 927
basic 677, 835
basic auth 604, 609
best practice 421, 612, 782, 975
best practices 307
bmc chatbot 47
bmc contributor 90, 97, 103, 108, 110, 126, 145, 173, 176, 202
bmc internal 696
bmc service cloud 782
bmc support 782, 1009
bot 590, 594
brand 632
branding 633
build 97
build application 95
building 66, 173, 202
bulk 641, 691, 696
bulk data load 691, 696, 700, 725
bulk edit 404
bulk load 685, 727, 731, 737
bulk loading 641, 684, 691, 696, 700, 725
bundle 27, 37, 794
bundle access 664
bundle class 214
bundle project 815
bundles 664
bundle version 965
business 664
business analyst 275, 664, 743, 747
business conditions 490
business error 452
business logic 90, 95
business rule 493
business rules 490
business unit 644

cache 974
cache data 974
caching 36
call activity 429, 434
call assignment policy 629
cancel 47, 537
cancellation 47, 537
cancel process instance 474
capabilities 535
capturing 452
cardinality 342
case 1009
categories 559
categorization 643, 657, 661, 669, 673, 681, 691, 696
category 892
ccs 632, 756
centralized 756
centralized configuration settings 756
centralized tenant 632
chaining 47, 537, 546
change 457
change management 996
changes 351, 942, 963
changing bundle version 965
chat action 579, 587
chatbot 282, 535, 576, 579, 589, 590, 594
chatbot accuracy 602
chatbot architecture 578
chatbot benefits 602
chatbot collaboration service 585, 589
chatbot configuration 588
chatbot evaluation 602
chatbot framework 282, 535, 576, 578
chatbotlink 602
chatbot metrics 602
chatbot precision 602
chatbot provider 589
chatbot recall 602
chat context 586
chat context listener 586
chat event handler 585
chat provider 585
choose 779
city 658
clean up innovation studio 268
client log 987
code 307

code based 794, 798, 799, 915

code based application 794
code compliance 307
coded 794
code development 307
coded library 257
codeless 277, 277, 295, 632, 636, 763, 766, 773, 794, 980
codeless app 794
codeless application 257, 277, 295, 636, 763, 766, 773
codeless application use case 277
codeless connection 604, 607, 609, 612, 614
codeless integration 604
cognitive chatbot 588
cognitive fscore 567
cognitive precision 567
cognitive recall 567
cognitive service 277, 281, 535, 552, 785
cognitive service configuration 554
cognitive service end to end process 552
cognitive service use case 281
cognitive testing 559
cognitive training 554, 559
collaborate 820
collaborative applications 820
collaborative development 820
collect data 974
command 874
command rest interface 238
common 643
company data 692
complex view layout 378
compliance 307, 826
components 36, 815, 826, 853
concept 36, 41, 45, 45, 96, 278
concepts 641
conclusion 202
conditional flow 192
configurable definitions 41
configuration 97, 297, 505, 588, 632, 735, 750, 756, 782, 867, 989
configurations 554, 616, 835
configure 421, 590, 735, 750, 782, 880
configure assignment 629
configure bmc chatbot 47
configure chatbot provider 556
configure chatbot service 589
configure cognitive service 556
configure workspace 556

configuring 535
connect 594
connector 615, 617, 620
connector action 623
connector configuration 615, 623
connector configurations 50, 616
connector development 615
connector profile 615
connectors 50, 535, 616, 623
connector type 616
constraint 342
consumable changes 261
consume 261, 286, 779
consume customization 262
consume remedy sso 911
consume rsso 911
consumption 785
container 376, 377, 391
containers 393
context key 474
control user access 519
conventions 869
conversation 535
conversation capability 576
conversation workspace 579
copy 351, 378
corrected 20
country 658
coverage 918
create 68, 110, 145, 202, 261, 270, 323, 346, 348, 362, 391, 396, 401, 421, 457, 488, 493, 497, 554, 586, 588, 590, 661,
661, 662, 664, 668, 669, 671, 673, 675, 677, 679, 681, 682, 742, 744, 749, 798, 806, 823, 826, 835, 853, 860, 870, 873, 874,
875, 882, 918
create app from user interface 794
create application 269, 273
create business analyst 664
create business analyst role 664
create configuration setting 505
create document 429, 488
create export package 775, 777
create install package 766
create library project 972
create update 769, 771
creating 110, 145, 255, 257, 747
creating extensions 202
creating project 806
crud operations 96
csrf 1022, 1022

csrf attack 1022, 1022

csv data 559
csv file 562
csv structure 559
custom 826, 853, 860, 875, 915
custom actions 320
custom application 262
custom command 238
custom datapagequery 228
customers 650
customer support 632, 782, 1009
custom form 735
custom foundation data 696, 710
customizable definitions 515
customization 43, 262, 290, 323, 415, 763
customization layer 45
customization points 262
customizations 313, 515, 996
customize 763
customized data 763, 765
customize foundation data 691, 704, 735, 989
customize user menu 523
customizing definitions 632
custom javascript code 976
custom rest resource 232
custom rest resources 870
custom service 212, 225
custom service action 225
custom service extensions 212
custom services 823
custom settings 221
custom ui 247, 826
custom user interface 826
custom view component 320, 835
custom view components 247, 320
d
data 103, 641, 641, 643, 661, 662, 664, 668, 669, 671, 675, 677, 679, 681, 682, 739, 835, 867
data caching service 974
data definitions 41
data editor 346
data load tool 727, 731
data model 90, 95, 96
data page 867
datapagequery 228, 873, 881

data privacy 739

data sets 562
data sync 737
data sync interval 737
data sync utility 700
debug 798, 917, 987
deep dive 273
define 43, 360, 497, 515
define relationship 342
definition 43, 488, 497, 763, 765
definitions 41, 313, 319, 323, 515, 798
delete 457, 662, 664, 668, 669, 671, 744, 749, 782
deleted data 692
delete test results 567
department 644
dependency 27, 815
deploy 632, 763, 765, 813, 915, 915, 980
deployable package 915
deployable packages 980
deploy app across environment 763
deploy application 632
deploy applications 134
deploy apps 763
deploy code based application 632
deploy codeless application 632
deploy codeless applications 277
deployed application 980
deploy entire application 766
deploying package 813
deploy library project 972
deployment 14
deployment application 775, 777
deployment management 277, 763, 765, 769, 771, 775, 777, 980
deployment model 36
deployment package 37
deprecated 10, 14
descendant 360
descendant security label 362, 370
design 202, 292, 421
design manager 835
design time view component 835
develop 33, 50, 95, 799
develop applications 33
developer 275, 743
developer environment 800
developer id 204
developers 794

developing 794, 976

developing application 307, 806
developing smart application 798
development 33, 202, 307, 816, 915
development concepts 36
development environment 134, 763, 800
development rules 307
development steps 295
development tutorial 204
dialog 579
digital service 36
digital service application 33, 39, 45, 292, 313, 759, 799, 818, 915, 981
digital service application concepts 36
digital workplace 636
direct 342
disable 27, 981
disable auditing 351
disable fts 754
display 452
display only form 297
dissociate records 384
district 658
document 421, 488, 497
document definition 421
domain 661
domain data tag 661
domain object 217
domain tag 661
download 800
download template 685
download template spreadsheet 685
downtime 998
dropdown based 396, 401
dwp 636
e
eclipse 800
edit 662, 664, 668, 669, 671, 744, 749
edit multiple records 404
edit record 384
element 486, 488
elements 452, 468, 590, 643
email 750, 756, 991
email actions 289
email profile 470

emails 632, 991

emai receive 495
embed app 636
embed view 636
employees 650
enable 262, 594, 981
enable auditing 351
enable fts 287, 335
enable reporting from is 528
enable skype for business 594
encrypting 373
end event 429
enforce password 756
enhancements 14
entity 579
environment 779, 798, 799, 915
error 452, 632, 782, 980, 987, 988, 991, 992, 1009
error 624 980
error 9803 991
error 9807 991
error boundary 452
error details 1009
error end 452
error handling 240
error message 1009
error messages 877, 991
evaluate cognitive service 567
evaluate expression 473
event 446
events 429, 452
example 45, 835, 860, 880
example opt in change 261
excel 684
excel spreadsheet 685
excel spreadsheets 691, 696
exceptions 877
exclusive gateway 429, 442
execute 918
existing 664
export package 632, 763, 980
expression 1017
expression builder 499
expression editor 323, 499, 1017
expressions 473, 499
extend 636, 735, 989
extendable applications 415
extendable definitions 290, 323

extendable defintions 415

extend application capabilities 636
extend foundation data 691, 735, 989
extend foundation definitions 704
extending 45, 880
extend view 376
extension 290
extension container 290
extensions 415
external 505
external app 636
externallink 47, 50, 278, 283, 602, 609, 636, 700, 710, 911, 976
f
fallback 23, 788
faq 1009
faqs 1009
features 10, 14, 30, 36, 275
field 373
field mask 373
fields 41, 329, 338, 340
field value locale 788
field values 788
file type 448
filter 661
filter foundation fields 710
filter preset 404
filter process instance 474
filter records 376
find person by using search criteria 896
first 813
first time data load 727, 731
fixed 20
fixes 10
flows 47
forget 739
form 759
format chatbot response 579, 583
form fields 396
form view 297
foundation 641, 641, 661, 684, 691, 696, 700, 725, 735, 881, 892, 896, 989
foundation customization 691, 721, 735, 989
foundation customizations 710
foundation data 14, 278, 625, 629, 641, 684, 685, 686, 688, 691, 692, 696, 700, 704, 725, 727, 731, 735, 737, 896, 896,
898, 898, 899, 901, 902, 903, 904, 905, 906, 907, 907, 908, 909, 910, 911, 989

foundation data changes 721

foundation data element 643
foundation data from itsm 696
foundation data mapping 692, 696
foundation data model 14
foundation data repository 725
foundation data types 643
foundation error 989
foundation library 14, 278, 641, 641, 643, 661, 673
foundation service 892, 894, 896, 898, 898, 899, 901, 902, 903, 904, 905, 906, 907, 907, 908, 909, 910, 911
foundation sync 735
framework 39, 942, 963
framework services 39
frequently asked questions 1009
from 691, 700, 725
fscore 283
fts 287, 754
fts configuration 335
fts fields 335
fts settings 756
full text 632
full text search 287, 754
functional role 45, 744
g
gateway 192, 442
gateway elements 442
gateways 429
gdpr 739
gdpr requests 739
general data protection regulation 739
generate 452
geography 643, 658, 661, 671, 673, 682, 691, 696
geography data workaround 671
get 457, 604, 867
getapproval 886
get card by search text 896
get category by search text 902
get list of organizations data page 899
get organization by id 901
get organization by searching with organization type 899
get organization information 898
get organizations for site 908
get person for site 907
get person information 894

get persons for an organization 898

get region by search text 904
get region information by id 905
get signature 889
get single approval 889
get site area by id 911
get site area by search text 910
get site areas for site 909
get sites by id 907
get sites by search text 906
get specific category by id 903
get started 59
getting 67
getting started 29, 30, 269, 289, 321
github 800, 816
give permission 529
global search 519, 523, 526, 533
glossary 52
goals 275
graphical 254
grid 126
groups 742
grunt 800
guidelines 307, 313, 319, 320, 559
h
handling 877
hands on 269, 270
helper view 192
hierarchical 360
hierarchical groups 360
home 10
host application 636
host innovation suite 636
html 583
http header 1022
i
iam api key 556
ibm watson 590
ide 798, 800
identify 457
identity and access management 556

idle 880
ignore words 287, 754
implementation 68
implementation code 307
implementing service 215
import data 775, 777
import definitions 775, 777
importing 759
improve accuracy 567
in bundle 505, 554
in bundle setting 976
incident report 1002
incoming 632, 991
incoming email 289
incoming mailbox 750
incorrect assignment policy 988
index 324
indirect 342
info 987
information 894
inherit 370
inheritance 329, 338, 340, 360
inherit record 329, 338, 340
initial 110
inner join 324, 325
innovation 739
innovation sdk 798
innovation studio 10, 14, 20, 52, 202, 322, 490, 633, 747, 794, 813
innovation studio licenses 40
innovation suite 10, 14, 20, 66, 204, 800, 818, 993, 994, 996, 1003, 1009
innovation suite application 1009
innovation suite cognitive service 552
innovation suite server 36
input 421, 559
input output 421
install 800, 918
install codeless application 773
install package 257, 763, 766, 980
install upgrade 266
instances 346
integrate 535
integration 50, 617, 620
integration service 616, 991
integration service connection 991
integration service troubleshooting 991
intent 579
intent examples 559

intents 559
interactive 590
interface 65, 870, 873, 874, 882
interfaces 90, 583
internet explorer 11 24
introduction 1022
invoicing customization point 262
islink 636
is reporting 528
issue 992, 1009
issues 20, 632, 782, 979, 991
itsm 691, 692, 696, 700, 704, 710, 725, 727, 731, 735, 737
itsm foundation data 691, 696, 700, 725
itsm foundation spreadsheet 727, 731
j
java 202, 800
javadocs 1003
java exceptions 452
java library 254
javascript 202
jdk 800
join 362
join form 297
join record 324
join record definition 325
js 800
json 497
json schema 607, 612
k
key concepts 36, 52
knowledge articles 782
known 20
l
lab 269, 273
label 360, 362, 370
labels 348, 661
lab exercises 269
language support 1000

layout 391
learn 33
libraries 36, 535
library 43, 96, 97, 108, 173, 176, 183, 186, 192, 204, 319, 515, 794, 815
license 632, 818
licenses 759
license types 40
licensing model 40
lifecycle 173, 202
limit 43
limitations 24, 675
link 782
list 126
listapprovaldetailsbyentryids 888
load 641, 684
load balancer 625
load balancer by capacity 625
load balancer by number 625
load data 685, 688
load data in bulk 685, 686, 688
load foundation data 688, 691, 696, 700, 704, 725
load foundation data in bulk 727, 731
locale 415, 788
localization 415, 788, 968
localization files 968
localize 23
localize custom view components 968
localize text 415
location 643, 654, 661, 668, 673, 679, 691, 696
log 987
log file 981
logging 981, 987
logging service 240
login 880
log level 981
logs 981
loop 186
lunch catering 255
m
machine learning 552
manage 749
manage deployment 763, 765
manage mapping 623
manage process 474

manage process dashboard 474

managing 322, 747
manufacturer 644
map foundation data 696
mapping 623
marketplace 307
mask 373
maven 794, 794, 798, 800, 806
maven archetype 806
maven command 975
maximum 289, 756
mealorderinfo 217
mealorderservice 215
menu group 519, 523, 526, 529, 533
menu item 519, 523, 526, 529, 533
menu restrictions 529
message 470
messaging 583
messaging service 597
metadata 497
methods 823
metrics 785
metrics dashboard 785
mobile 393
mobile applications 393
modal view 384, 393
model 835
modified date 376
modify 362, 661, 662, 664, 744, 749
modify foundation data 735, 989
modify process 474
module 1 202
move tailoring changes 763, 765
multiinstance 186
multiple 583
multiple application roles 362
multiple developers 820
multiple selection field 396
multi tenancy 36, 747, 759
n
named license 40
named list 41, 103, 297, 323, 417
named list definition 417
naming 869

naviagation bar 523, 526, 533

navigation 59, 65
navigation bar 519
nested container 391
new 286, 779
new user 664
node 800
no permissions 980
notifications 470, 536, 549, 998
notify approvers 536, 549
number 289, 756
o
oauth 604, 609
object 421, 497
office 365 594
onboard 321
onboarding 321
on premise 696, 700, 725, 735, 989
on premises 691, 692, 700, 725, 727, 731, 737
open source 816
open source code 816
operating organization 644
operational 657, 669
opt in 286, 320, 779
opting 779
opt out 286, 320, 779
organization 643, 644, 661, 662, 673, 675, 691, 696, 892
organization data 278
orientation 67
other 815
outbox profile 289
outer join 324, 325
outgoing 632, 991
outgoing email 289
outgoing email profile 470
outgoing mailbox 750
outgoing profile 750, 991
output 421
overlay foundation fields 691
overlay objects 691
overview 29, 30, 36, 67, 321, 322, 641, 691, 742, 877, 979

p
package 27, 763, 765, 769, 771, 775, 777, 798, 915, 915, 980
package codeless application 766
package creation fails 980
package deployment 813
package not created 980
packages 90
packaging 254, 915
packaging new release 266
page class loader utility 945
parallel gateway 429, 442
parameter 756
parent security label 360
parent security labels 348
password 725, 1009
password length 725
password strength 725
patch 01 23
pdf 1003
pending 550
penetration testing 1022
pentaho 684, 700, 725
pentaho job sequence 696
pentaho sequence 696
pentaho transformation 700, 725
pentaho transformations 710
people 650, 664, 673, 677
permission 664
permissions 329, 338, 340, 348, 360, 362, 370, 378, 421, 632, 980, 1000
person 643, 650, 661, 664, 677, 691, 696, 892, 894, 896
personal data 739
person data 278, 692
person information by notification 898
person record 744
pii 739
pin 486
platform 14
policies 993, 994, 996, 996, 998, 1000, 1000, 1002, 1003
policy 535
pom xml 27, 806, 815
poolinginterval 27
post 604
postal codes 658
powerful 270
prebuilt view components 376, 377
precision 283

prepare 799
preparing for development 292
preserve work 268
privacy 739
process 63, 173, 183, 192, 255, 322, 323, 360, 421, 429, 434, 442, 446, 447, 448, 452, 473, 474, 488, 617, 918
process activities 617
process conditions 490
process connector element 617
process dashboard 474
process definition 297, 421, 429, 442
process definition element 442, 448
process definition elements 429, 434, 447, 448, 473
process designer 63, 273, 348, 421, 452, 468
process diagram 474
processes 486
process expressions 499
process flow 442, 474
process for dialog 587
process instance 474
process instance progress 474
process variable 421
process variables 421, 537
product 30, 36, 657, 669
production 779
production environment 763
profile 289, 470, 616, 750, 991
profile name 750
project 27, 202, 798, 799, 806
promote application across environments 763
properties 27
property 486
province 658
public 43, 319, 515
publish 33
put 604
q
quick start 68
r
rca 1002
ready for use 915
reason 550

rebuild 204
recall 283
receive task 434
recommendations 307
record 323, 324, 329, 338, 340, 342, 346, 351, 396, 543, 867
record association 342
record definition 108, 297, 324, 329, 338, 340, 362, 370, 396, 644, 650, 654, 657, 658
record definitions 376
record definition types 325
record editor 346, 376, 377, 853
record events 490, 495
record field 324
record grid 134, 376, 377, 404
record instance 324
recordinstancedatapagequery 882
record instance editor 346
record instances 882
records 41, 322, 351, 457, 468
rectify data sets 567
redeploy 204
reference 319, 325, 993, 993, 994, 996, 996, 998, 1000, 1000, 1002, 1003
region 654
regions 668
register 33
registered fulfillment data 103
register record 536
registration 543
regular 362
regular form 297
regular record 324
regular record definition 325
reindex 754
reinstall codeless application 773
reject 550
release notes 10, 20, 993
release version 965
releasing 254, 257
remedy 691, 696, 700, 725
remedy itsm 278
replace 739
report 1009
report error 992
reporting 782
reporting in is 528
report issue 992
repository 725
requests 629

requirements 68, 202

reset passwort 980
resolution 657, 669
resolve 782, 1009
resource 875
responsive layout 384, 393
rest 823, 873, 874, 875, 882
rest api 604, 614, 870, 877, 881, 882, 892, 896, 1003
rest api error message 870
rest connection 614
rest definition 607
restful api 892
restful resource 823
rest methods 607
rest resource 232
restrict 661
rest service 254
resume process instance 474
retrieve 882
reusable components 972
revert 779
review 918
rich text 376, 377
role 664
roles 30, 275, 632, 742, 743, 749
rollback 779
root cause 657, 669
root cause analysis 1002
round robin 625
row level 348
row wrap 393
rsso oauth 976
rsso oauth authentication 911
rule 65, 192, 493, 620
rule connector element 620
rule definition 297
rule definitions 490
rule designer 65, 348, 490, 491
rule elements 491
rules 41, 322, 323, 491, 535
rule trigger 491
rule triggers 490
run 918
run load process 688
run process 474, 688
rxbundle 214
rxexception 877

s
saas administrator 275
safe process 262
salesforce 782
sample code 873, 882, 974
sample fulfillment 103
sample source 204
sandbox 33, 1009
save 981
schedule 446
schedule sync 737
scope 43, 319, 515
sdk 800, 806
sdk upgrade 27
search 632, 739
search approval 891
search category name 335
search fields 335
search metadata 335
search process 474
search process instance 474
search records 376
search relevancy 335
section 508 826
security 348, 360, 362, 370, 1022
securitylabelchng 457
security labels 348, 457
security planning 1022
seed data 562
select group 396
self 342
self approval 47, 543
self approval flows 47, 544
self approvals 544
sequence 442
server 818
server log 987
service 594
service class 823
service consumption 785
service interface 823
service level agreement 994
servicelocater 215
service provider 644

services 535
service task 429
session 270
session 1 269
session 2 270
session 3 273
session time 880
set 457, 641
set parameter 384
setting 348
settings 554, 632
setting service 221
setup 134, 798, 799, 800
shared 505
shared system 747
shell 519, 523, 526, 529, 533
shell navigation 523
shell permissions 519
show alert 470
simple 68
site 654, 668, 892
site area 654, 668, 892
site data 692
size 756
skills 30
skillset 30
skin 632
skinning 633
skype for business 594
sla 994
slack 590
slack application 590
sliding panel 112
sliding panel view 112
smart app 33
smart application development 798
smart application development steps 295
smart application environment 800
smart bundle 37
smart it 636
smart library 972
sms 597
sms conversation capability 597
solution 254, 254, 257
solutions 36
source control 820
source server 725

spreadsheets 684, 691, 696

sql form 297
stack 36
standard libraries 798
standard library 27
started 67
start event 429
start process 474
state 658
status 782
status bar graph 474
store hashed 373
storing actions 860
strong password 725
structure 497
structure of digital service application 292
subclass 877
submit 632, 782
submit report 992
sub process 429, 434
sub record definition 329, 338, 340
suggest assignee 429, 478, 570
suggest categorization 478
suggest category 429
suite 739
super record definition 329, 338, 340
support 583, 993
support contract id 782
supported 583, 654, 657, 658
supported foundation data 692
supported itsm foundation data 692
support email 782
support group 644
support group not found 988
support id 782
suspend process instance 474
sync 721
synchronize 691, 727, 737
synchronize data changes 721
synonyms 754
synonyms list 287
syntax 583
system 50
system event 495
system locale 23, 788
systems 535

t
table 404
table grid view 126
tabular format 404
tag 661
tailor 763, 765
tailorable 323
target server 725
task 322, 710, 742, 750, 754, 976
task detail 192
task list 192
task manager automation 930
technical support 993
technology 36
telemetry framework 785
template 470
template spreadsheet 685
tenant 632, 756
tenant administrator 45, 275, 664, 743, 744, 749, 759
tenant configuration 754
tenant configuration settings 756
terminologies 52
terms 52
test 779, 798, 917
test application 917
test auto categorization 283
test cases 918
test chatbot 602
test cognitive service 283
test data 567, 602
test data limit 283
test environment 763
testhelper class 927
testing 254, 917
test metrics 283
test results 918
tests 255
testserver class 927
text field 373
themes 322, 633
third party 535
third party code 816
third party dependency 816
thirdpartylink 20, 24, 30, 33, 247, 283, 320, 505, 556, 559, 579, 590, 594, 597, 700, 800, 806, 945, 992, 993, 1009
ticket 782

time 813
time frame 474
timeout 27, 880
timer 183
timer event 429, 446
timer events 490, 495
time zone 658
total 289, 756
train 562
train cognitive service 562
training 30, 562
training data 567
training data limit 559
training data rows 559
training data sets 559
training timer 562
translation 968
trigger 446, 495
troublehooting 992
troubleshoot 731, 989, 991
troubleshooting 351, 979, 980, 988, 989, 991
tutorial 66, 67
twilio 597
types 342, 661, 675, 677, 679, 681, 682
u
ui automation 27, 945, 954, 963
ui framework 945
ui framework methods 954
ui preferences 632
ui test framework 27
undeploy 915
undeploy application 975
undeploying package 915
undeploy library 268
undeploy version 320, 975
uninstall application 268
uninstall codeless application 773
unlimited 818
unlimited users license 759
unlock account 1009
update 362, 457, 756, 779, 867
update foundation data 704, 735
update from version 769, 771
update package 763, 769, 771, 980

updates 10, 23, 24, 351, 963

update status 890
update to version 769, 771
updating 27, 348
upgrade 23, 24, 27, 286, 320
upgrade sdk 27
upgrading 254, 1003
upload spreadsheet 686
usage 43, 785
usage report 785
use case 277, 277, 278, 281
use cases 289
user 632, 664
user access 632
user account 632
user assistance 30
user data 867
user details 523
user group 529
user interface 95, 110, 145
user menu 523
user messages 470
user profile 523
user reported 782
user role 529
user roles 743
users 742, 747, 782, 818
user task 429, 434
using 322, 457, 468, 583, 641, 661, 815, 884
v
value 23
values 756
variables 421
vendor form 297
vendor organization 644
vendors 650
verify pin 486
version 257, 286, 779
versions 320, 965
videos 30, 286, 323, 329, 338, 340, 342, 346, 378, 384, 396, 401, 417, 491, 523, 526, 533, 537, 543, 544, 546, 552, 594,
604, 615, 766, 769, 775, 794, 800, 806, 813, 915, 945, 968, 1003
view 110, 126, 134, 145, 376, 377, 396, 401, 636, 826, 853, 980, 981
view based 396, 401
view component 247, 254, 384, 404, 529

view components 323, 415

view definition 297, 376, 377, 378, 384, 391, 396, 404, 415, 417
view designer 391, 636
view layout 378
view pentaho jobs 696
view permissions 378
view process 474
views 41, 270, 323, 378
visual designer 63
vulnerability 1022
w
wait for approval review 549
wait step 446
warning 987
web api 604, 614
web application 1022
web request 429
web requests 612
what's new 10, 14
whats new 10
whitehat sentinel 1022
wide display 607
wide layout 559, 607
workarounds 20
work order 68, 90, 96, 97, 108, 110, 112, 126, 173, 176, 183, 192, 204
work order console 192
work order library 108
workspace 59, 322
work task 173, 176, 183, 186
work task record 176
x
x requested with 1022

© Copyright 2016 – 2018 BMC Software, Inc.
BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and
may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the
U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners.
Cisco and Cisco/BUPTNIC are registered trademarks or trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.
AppScan, AIX, DB2, IBM, IBM Watson, Watson, and Watson Analytics are trademarks or registered trademarks of International Business Machines Corporation in
the United States, other countries, or both.
IT Infrastructure Library® is a registered trade mark of the AXELOS Limited.
ITIL® is a registered trade Mark of the AXELOS Limited.
Linux is the registered trademark of Linus Torvalds.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
BusinessObjects, Crystal Reports, and SAP are trademarks or registered trademarks of SAP AG in Germany and in several other countries.
UNIX is the registered trademark of The Open Group in the US and other countries.
ASAP is a trademark or registered trademark of SAP SE in Germany and in several other countries.
BMC Software Confidential.
The information included in this documentation is the proprietary and confidential information of BMC Software, Inc., its affiliates, or licensors. Your use of this
information is subject to the terms and conditions of the applicable End User License agreement for the product and to the proprietary and restricted rights
notices included in the product documentation.
Click here for the provisions described in the BMC License Agreement and Order related to third party products or technologies included in the BMC product.
BMC Software Inc.

2103 CityWest Blvd, Houston TX 77042-2828, USA
713 918 8800
Customer Support: 800 537 1813 (United States and Canada) or contact your local support center

BMC+Helix+Innovation+Suite 181101 PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

BMC+Helix+Innovation+Suite 181101 PDF

Uploaded by

Copyright:

Available Formats

BMC Helix Innovation Suite 18.

Date: 2018-12-19 01:48

BMC Helix Innovation Suite 18.11 Page 2

BMC Helix Innovation Suite 18.11 Page 3

Capabilities of configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

BMC Helix Innovation Suite 18.11 Page 4

BMC Helix Innovation Suite 18.11 Page 5

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638

BMC Helix Innovation Suite 18.11 Page 6

Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

BMC Helix Innovation Suite 18.11 Page 7

Creating a custom user interface with AngularJS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826

BMC Helix Innovation Suite 18.11 Page 8

Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993

BMC Helix Innovation Suite 18.11 Page 9

Navigating BMC Helix Innovation Studio (see

Administering (see page 632)

If you are an Administrator this is a good place to start.

Troubleshooting (see page 979) Developing applications (see page 794)

If you are a Developer, this is a good place to start.

Communities Developer Portal Sample Videos Podcasts Marketplace

Join discussions Find apps, connectors,

Release notes and notices

BMC Helix Innovation Suite 18.11 Page 10

Date Release Summary

Improved fallback mechanism for displaying localized field values.

Easier conversion between types of Organization and Person.

Support for outgoing profiles to enhance the email capabilities.

Ability to change the layout of view components.

Responsive web layouts in the browser.

Creation of codeless applications and libraries in a tailoring environment.

Using a new PIN field in Foundation data to verify individuals.

Configuring approval flows using one single wizard.

Introducing Business Analyst role in BMC Helix Innovation Suite.

Enable extension of application definitions.

Ability to identify updates to the security label.

Section 508 compliance.

Additionally, BMC Helix Innovation Suite includes the following enhancements:

Zero downtime upgrade of Innovation Suite.

Audit fields from associated record definitions.

BMC Helix Innovation Suite 18.11 Page 11

Date Release Summary

Full-text search capabilities in a Digital Service application.

Incoming and outgoing email configuration.

Deploy code-based application across environments in a dedicated systems.

Support for GDPR.

Report application errors as issues to customer support.

Zero downtime upgrade to a new version of an application.

Support for multiple chat providers

Support for enabling chat conversations through SMS

Support for enabling chat conversations through Skype for Business

Ability to format chatbot responses

Associate and display field values for Approval record definitions

Leverage Foundation Data to assign approvers of the approval requests

Localize field values of a record definition

Localizable Foundation category data

Enable row-level security for roles from multiple applications

Automated assignment using Cognitive Service.

Data load and synchronization capability for ITSM Foundation data.

Leverage Smart Reporting in BMC Helix Innovation Suite application.

Automatically persist user settings between sessions.

Display associations in Approval Console.

Disassociate records to prevent orphaned records.